Grafana Loki

Last reviewed Aug 26, 2026 · 869 words

Loki stays cheap only as long as you keep labels few and static: fewer than about 10 per stream, and never a request ID, user ID or timestamp among them. It indexes labels, not text, so each unique label combination is a stream with its own index entry and its own chunk files. Five well-chosen labels across 30 containers gives a few hundred streams and a log database that would fit on an SD card; one dynamic label turns that into millions of streams and a service that falls over at 512 MB. Get that rule right and everything else about running Loki at home is a single container.

Monolithic mode on one box is the whole install

Loki's microservice deployment modes exist for clusters ingesting terabytes; a homelab runs the same binary with every component in one process. The container is grafana/loki on port 3100 with a config file mounted:

auth_enabled: false
server:
  http_listen_port: 3100
common:
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory
schema_config:
  configs:
    - from: "2024-01-01"
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h
limits_config:
  retention_period: 30d
compactor:
  working_directory: /loki/compactor
  retention_enabled: true
  delete_request_store: filesystem

Mount /loki on a volume, and check http://loki:3100/ready before you start sending logs; it answers "ready" after about 15 seconds. Retention does not happen unless the compactor section is present with retention_enabled: true, which is the most common reason a homelab Loki fills a disk 6 months in. Thirty days is a sensible default; the chunks compress well and a 30-container host typically writes tens of megabytes a day on disk, though that estimate swings with how chatty your applications are.

Getting logs in: Alloy, the Docker driver, or the old agent

Promtail, the agent every older tutorial uses, is end-of-life; Grafana Alloy replaced it, and a new setup should start with Alloy. Its loki.source.docker component discovers containers through the Docker socket and attaches the container name, compose project and service as labels, which is exactly the small static set you want. The alternative for Docker-only hosts is the grafana/loki-docker-driver logging plugin, which ships container logs straight to Loki with no agent; the trade is that a Loki outage can stall container logging, and the driver's retry options need to be set to avoid that. For systemd hosts, Alloy's loki.source.journal covers the journal, and for everything else there is a plain HTTP push endpoint. Whatever you choose, look at the labels it produces before you look at anything else.

LogQL is four lines you will actually use

Add Loki as a data source in Grafana at http://loki:3100 and open Explore. The queries that cover 90 percent of homelab use are a stream selector with a filter, a parser, and a count:

{container="caddy"} |= "error"
{container="immich_server"} | json | level="error"
sum by (container) (count_over_time({compose_project="media"}[5m]))
rate({container="vaultwarden"} |= "Username or password is incorrect" [15m])

The first is grep. The second turns JSON logs into fields you can filter on without those fields ever becoming labels, which is the trick that keeps the index small. The last two are metrics computed from logs, so a dashboard panel or an alert rule can fire on "failed logins per minute" with no exporter. Alerting rules live in the rules_directory in the same YAML format as Prometheus rules.

Full-text search is deliberately bad, and that is the trade

Because the index holds only labels, "find this string anywhere in the last year" means decompressing and scanning every chunk in the range, and it is slow in proportion to the range. Over hours it is instant; over months, it is minutes. If your real need is ad-hoc search across long spans, VictoriaLogs does full-text indexing with a similar footprint, and Graylog or OpenSearch do it with a much larger one. If your real need is "tail my containers when something breaks", Dozzle does that with no storage at all. Loki is for the middle: retained, queryable, cheap, and best when you already look at Grafana every day.

Object storage is the scaling path, not the starting point

Every guide from Grafana assumes S3-compatible object storage, and for a company that is right. On one host the filesystem backend is simpler and faster to restore. Move chunks to MinIO or a cloud bucket when the volume passes what one disk holds comfortably or when a second Loki node is on the horizon, and not before; a tar of /loki is a complete backup until then.

What I'd do

One grafana/loki container in monolithic mode with the config above, filesystem storage, 30-day retention, compactor on. Alloy shipping Docker logs with container, service and project labels and nothing else. Grafana Explore for looking, 2 or 3 LogQL alert rules for failed logins and error rates. Revisit labels every time you add a source, because label discipline is the entire difference between Loki being the cheapest log system you have run and the one that ate the disk.