Published

Grafana Loki

Log aggregation server by Grafana Labs that indexes only labels and stores compressed log chunks, queried with LogQL from Grafana. Runs here as one container with filesystem storage. Fits one server or a small fleet that wants its container and system logs searchable in one place.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 1 GB of logs a day from one server and its containers, up to 500 active streams, a few people querying the last 30 days from Grafana.	0.5 vCPU · 1 GiB RAM · 6.361 GiB disk	0.72 vCPU · 2.7 GiB RAM · 16.631 GiB disk
MediumEstimate	Up to 5 GB of logs a day from a few servers, up to 2,000 active streams, dashboards and alert rules querying Loki through the day.	1 vCPU · 2 GiB RAM · 31.027 GiB disk	1.32 vCPU · 3.9 GiB RAM · 44.997 GiB disk
HeavyEstimate	Up to 20 GB of logs a day, the docs' ceiling for monolithic mode, up to 5,000 active streams (the default per-tenant limit), heavy LogQL use.	2 vCPU · 4 GiB RAM · 123.527 GiB disk	2.52 vCPU · 6.3 GiB RAM · 151.372 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Loki (app)	0.5 / 1 / 6.361	1 / 2 / 31.027	2 / 4 / 123.527	[7][10][11][26][28]

How the estimates are worked out

Loki · Light: No monolithic sizing upstream. RAM: two hours (max_chunk_age) of 1 GB/day is 0.083 GB of open chunks, plus the 100 MB results cache and the Go runtime of all components → 1 GiB. vCPU: gzip of about 12 KB/s and short LogQL queries → half a core. Disk: image 0.194 GiB (0.045 compressed + 0.149 unpacked, both kept by the containerd store) + 30 days × 1 GB / 5 (assumed gzip ratio) = 6 + WAL 2 h of ingest × 2 = 0.167 → 6.361; GB taken as GiB.
Loki · Medium: RAM: two hours of 5 GB/day is 0.417 GB of open chunks, plus the 100 MB results cache and up to 4 concurrent queries (querier max_concurrent) → 2 GiB. vCPU: one core for compression and dashboard queries over a few days of data. Disk: image 0.194 GiB (0.045 compressed + 0.149 unpacked, both kept by the containerd store) + 30 days × 5 GB / 5 (assumed gzip ratio) = 30 + WAL 2 h of ingest × 2 = 0.833 → 31.027; GB taken as GiB.
Loki · Heavy: RAM: two hours of 20 GB/day is 1.667 GB of open chunks, plus cache and 4 concurrent queries → 4 GiB, one ingester request of the docs' smallest microservices tier (2 CPU, 4 Gi). vCPU: 2, the same request; the docs warn queries can need 10× more. Disk: image 0.194 GiB (0.045 compressed + 0.149 unpacked, both kept by the containerd store) + 30 days × 20 GB / 5 (assumed gzip ratio) = 120 + WAL 2 h of ingest × 2 = 3.333 → 123.527; GB taken as GiB.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Loki	3100/tcp	Internal only	HTTP API: push (/loki/api/v1/push, /otlp/v1/logs), LogQL queries, /ready; no authentication	[2][8][9]
Loki	9095/tcp	Internal only	gRPC between Loki components (default grpc_listen_port); unused from outside	[7]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Loki	10001:10001	`loki`	No	`/loki`	[1][4][6][14]

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
LokiAssumption	6	30	120	[7][12][13]

What the growth figures rest on

Loki: Retention is off by default, so Loki keeps every log and never deletes by free space: 30 days × 1 GB/day / 5 (assumed gzip ratio; chunk_encoding gzip) = 6 GiB a month, without end. With compactor retention on, disk levels off at about one retention period.
Loki: Retention is off by default, so Loki keeps every log and never deletes by free space: 30 days × 5 GB/day / 5 (assumed gzip ratio; chunk_encoding gzip) = 30 GiB a month, without end. With compactor retention on, disk levels off at about one retention period.
Loki: Retention is off by default, so Loki keeps every log and never deletes by free space: 30 days × 20 GB/day / 5 (assumed gzip ratio; chunk_encoding gzip) = 120 GiB a month, without end. With compactor retention on, disk levels off at about one retention period.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Stop Loki (docker compose stop loki), then copy the whole /loki volume with a helper container, for example docker run --rm -v <volume>:/loki:ro -v "$PWD":/backup alpine tar czf /backup/loki.tgz -C /loki . The Loki image has no shell or tar. [2][14][15]DerivedUpstream documents no backup procedure for the filesystem store. Every data path (chunks, TSDB index, WAL, compactor) is under path_prefix /loki, and BusyBox was removed from the image in 3.5.8, so the copy runs outside it.

Upgrade steps

Read the upgrade guide and the release notes of every version you cross; upstream advises sequential upgrades and testing skipped versions first. Then back up /loki, set the new pinned tag and run docker compose pull and docker compose up -d. [15][16]
With your own config file, check it first: run the new image with -config.file=<your file> -verify-config=true, or diff -print-config-stderr of the old and new tags, as the upgrade guide shows. [15]
After the start, Loki replays its WAL; wait until the container is healthy (loki -health on /ready) and check docker compose logs loki before relying on it. [5][7][8]

Roll back

Stop the stack, restore the /loki copy taken before the upgrade into the volume, pin the previous tag and run docker compose up -d. Logs received after the backup are lost. [15]DerivedThe upgrade guide covers upgrades only, not downgrades; an older binary on index and WAL files written by a newer one is not documented as safe, while the pre-upgrade copy is.

Known breaking changes

In 3.7.3: Promtail was removed from the Loki project (end of life on March 2, 2026). Move log shipping to Grafana Alloy; alloy convert turns a Promtail config into an Alloy config. [16][18][19]
In 3.7.0: Labels extracted by parsers in a query (json, logfmt) no longer override structured metadata with the same name; queries that relied on that return different results. [16]
In 3.6.0: The built-in Loki UI moved to a Grafana plugin (Loki Operational UI); Loki now serves only the APIs the plugin uses. [17]
In 3.5.8: BusyBox was removed from the image: no /bin/sh, ls or wget, so docker exec … sh and shell or wget healthchecks fail. Use docker cp, a helper container, or loki -health (3.7+). [5][15]
In 3.0.0: Structured metadata is on by default and needs the tsdb index with schema v13, or Loki will not start; migrate to TSDB first. New limits: 256 KB per line, 15 labels per series; a service_name label is added; retention needs delete_request_store. [15]

Limits

The template is the Loki server only; something must send it logs. Promtail is end of life: use Grafana Alloy (loki.write to http://loki:3100/loki/api/v1/push; reading container logs needs the Docker socket, so it is not templated), the Loki Docker logging driver, or OTLP at /otlp/v1/logs. [8][18][19][20][24]
Each app in a generated file gets its own internal network, so Grafana in the same file cannot reach Loki yet: add loki-internal to the networks of the grafana service, then use http://loki:3100 as the Loki data source URL. [3][8]
The Docker logging driver runs inside the Docker daemon on the host, not on the Compose network: install grafana/loki-docker-driver:3.7.8-amd64 (or -arm64), turn on publish-loopback and set loki-url to http://127.0.0.1:3100/loki/api/v1/push. [21][22][23]
Retention is off: Loki keeps every log forever and does not delete when the disk fills. To cap it, enable compactor retention, for example by adding -compactor.retention-enabled=true -compactor.delete-request-store=filesystem -store.retention=744h after -config.file=/etc/loki/local-config.yaml in command. [7][12][13]
Monolithic mode with the filesystem store suits up to about 20 GB/day on one server. Grafana Labs does not support the filesystem store in production; there is no high availability, durability is the disk's, and millions of chunk files in one directory cause trouble. [10][12]
Default limits per tenant: 4 MB/s ingestion (6 MB burst), 5,000 active streams, 256 KB per line, 15 labels per series, and entries older than one week are rejected. Keep labels few and low-cardinality. [7][15]
The config is baked into the image and the image has no shell. To change it beyond command-line flags, mount your own file and point -config.file at it, as the Docker install docs do. [1][4][15]

Security

Loki has no authentication (auth_enabled false, one tenant): anyone who reaches port 3100 can read every log and push new ones. Keep it on the internal network; publish-loopback maps it on 127.0.0.1 only. Agents on other hosts need an authenticating reverse proxy or mTLS in front. [2][9]
Logs often hold tokens, IP addresses and personal data. Whoever can query Loki or its Grafana sees them, so limit Grafana access, drop sensitive lines in the agent, and set a retention period. [9][13]
By default Loki sends anonymous usage statistics to stats.grafana.org. To turn it off, add -reporting.enabled=false to the command, or set analytics.reporting_enabled: false in your own config. [2][7]
The image runs as the non-root user loki (10001:10001) on a distroless base with no shell. A named volume works as is; a bind mount must be owned by 10001, or run with --user. [1][4][6]

Backup

Everything Loki stores is in the /loki volume: chunks (under fake/ in single-tenant mode), the TSDB index, the WAL, the compactor's files and rules. Copy it with Loki stopped, from a helper container, since the image has no shell. [2][12][14]
Decide whether the logs are worth backing up: often only the config matters, and old logs can be dropped by retention. Keep any config file or command-line flags you added with your Compose file. [4][13]