Grafana Loki: Label-Indexed Log Aggregation

What Grafana Loki is

Grafana Loki is a horizontally scalable, highly available, multi-tenant log aggregation system from Grafana Labs, written in Go and inspired by Prometheus. Its tagline is "like Prometheus, but for logs". The defining design choice is that Loki does not index the contents of log lines. It indexes only a small set of labels for each log stream and stores the log data itself as compressed chunks, which the README says makes it simpler to operate and cheaper to run than systems that do full-text indexing.

Because those labels are the same kind you already attach to Prometheus metrics, you can move between metrics and logs for the same workload using the same selectors. The README calls Loki an especially good fit for Kubernetes Pod logs, where metadata such as Pod labels is scraped and indexed automatically. Unlike Prometheus, Loki focuses on logs instead of metrics and receives data by push rather than pull.

It is meant for platform, SRE and DevOps teams who want centralized logs without running a heavy full-text search cluster, and especially for teams already using Grafana and Prometheus.

How it works

A log stream is a set of log lines that share the same labels. Labels are how Loki finds a stream in its data store, so the docs stress that a good label set is key to efficient queries. Log data is compressed into chunks and written to an object store such as Amazon S3 or Google Cloud Storage (the docs' FAQ also names Azure Blob Storage), or to the local filesystem for development and proofs of concept. The index stays small because it covers labels only.

A typical Loki stack has three parts:

• An agent, for example Grafana Alloy, which scrapes logs, turns them into labelled streams and pushes them to Loki over an HTTP API. Alloy replaced Promtail in the recommended stack; Promtail is now considered feature complete.
• Loki, which ingests and stores logs and processes queries.
• Grafana for querying and visualizing, with LogCLI or the HTTP API as command-line and programmatic alternatives.

Loki is built as many microservices compiled into one binary. The -target flag picks which components a process runs, and -list-targets prints the list for your version. Components include the Distributor, Ingester, Querier, Query Frontend, Query Scheduler, Compactor, Index Gateway, Ruler and Overrides Exporter; the bloom components and the Table Manager are marked deprecated. That build model gives three deployment modes:

• Monolithic (-target=all): every component in one process. The docs position it for experiments and for read/write volumes up to approximately 20GB per day.
• HA monolithic: several -target=all instances sharing one S3-compatible bucket, using memberlist for ring state, common.replication_factor: 3 with at least three instances, one instance set as the main compactor, and a load balancer in front. It replaces the deprecated Simple Scalable Deployment (SSD), which is scheduled for removal in Loki 4.0.
• Microservices: each component runs as its own process for fine-grained, per-component scaling, intended for the largest installations on Kubernetes.

Because stored data is decoupled from the software that ingests and queries it, the docs say you can redeploy a cluster in a different mode with minimal or no configuration changes.

Key features

• Label-only indexing: a much smaller index than full-text log stores, with compressed chunks in low-cost object storage.
• Scalability: the docs claim Loki scales from a Raspberry Pi up to ingesting petabytes a day.
• Multi-tenancy: several tenants can share one Loki instance with isolated data and requests; a tenant ID is assigned in the agent and auth_enabled turns it on.
• LogQL: a query language modelled on PromQL, with label matchers, line and label filters, parsers such as json, and metric queries that turn log lines into time series.
• Alerting: the ruler component continually evaluates queries against logs and can send alerts to Prometheus Alertmanager or Grafana's alert manager.
• Structured metadata: a place for high-cardinality values you still want to search, instead of turning them into labels.
• Observability stack integration: native support in Grafana, plus correlation with Mimir metrics and Tempo traces.
• Operational tooling: LogCLI for querying from the terminal, a Docker driver client that ships container logs directly, and Loki Canary to detect missing logs.

Getting started

The official quickstart runs Loki locally with Docker Compose on Linux, alongside flog (a log generator), Alloy, an nginx gateway, MinIO for storage and Grafana. You need Docker and Docker Compose installed.

mkdir evaluate-loki
cd evaluate-loki

Download the three configuration files:

wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/loki-config.yaml -O loki-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/alloy-local-config.yaml -O alloy-local-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/docker-compose.yaml -O docker-compose.yaml

Start the stack and check the containers:

docker compose up -d
docker ps -a

Grafana is then available at http://localhost:3000 with the Loki data source preconfigured. In Explore, the quickstart walks through LogQL queries such as selecting a stream, filtering for a string and computing a rate:

{container="evaluate-loki-flog-1"} |= `status`
{container="evaluate-loki-flog-1"} | json | status=`404`
sum by(container) (rate({container="evaluate-loki-flog-1"} | json | status=`404` [$__auto]))

To build and run a single-binary Loki from source with an up-to-date Go toolchain, the README gives:

$ git clone https://github.com/grafana/loki
$ cd loki
$ go build ./cmd/loki
$ ./loki -config.file=./cmd/loki/loki-local-config.yaml

Use cases

• Kubernetes cluster logging, collecting Pod logs with their labels and querying them next to Prometheus metrics in Grafana.
• Incident investigation, jumping from a metric spike to the logs of the same service using identical label selectors, then on to traces in Tempo.
• Cost-conscious retention, keeping large log volumes in object storage rather than on SSD-backed search nodes.
• Log-derived metrics and alerts, such as a per-container rate of HTTP 404 responses evaluated by the ruler.
• Shared platforms, where one Loki deployment serves several teams or customers as isolated tenants.
• Small setups, a single binary on one host for homelabs or modest services within the monolithic mode's guidance.

How it compares

The README's own comparison is with "other log aggregation systems" that do full-text indexing: Loki trades that indexing away for a smaller index, cheaper storage and simpler operations. The practical consequence is that queries narrow down by labels first and then scan the matching chunks, so search-heavy workloads over arbitrary fields depend on good label design and structured metadata rather than an inverted index. Teams that rely mostly on free-text search across everything may find a full-text engine a better fit; teams that already think in Prometheus labels usually find Loki's model natural.

Against Prometheus itself, the difference is scope and data flow: Prometheus pulls metrics, while Loki receives logs pushed by agents.

Things to know before adopting

• Licence: Loki is AGPL-3.0-only. If you modify Loki and offer it to users over a network, the AGPL requires making your modified source available. LICENSING.md lists folders under Apache-2.0 instead, including clients/, pkg/push, pkg/logproto/, pkg/loghttp/, pkg/logqlmodel/, pkg/util, production/ and tools/.
• Label cardinality is the main operational risk: the docs warn that high cardinality makes Loki build a huge index and flush thousands of tiny chunks, and that Loki "performs very poorly" in that state. Avoid unbounded values such as timestamps or IP addresses as labels. New users are advised to move k8s.pod.name and service.instance.id from labels to structured metadata.
• Deployment-mode changes: SSD is deprecated and slated for removal in Loki 4.0, yet the Docker Compose quickstart still runs in SSD mode, so treat it as a demo and plan production around monolithic, HA monolithic or microservices mode.
• Helm chart move: effective March 16, 2026 the Loki Helm chart was forked to grafana-community/helm-charts; the chart in the Loki repository continues to be maintained for GEL (Grafana Enterprise Logs) users only.
• Agent choice: Promtail is feature complete and future log-collection work happens in Alloy, so new deployments should start with Alloy or another supported client.
• Several maintained release lines: v3.7.9 and v3.6.19 were both published on October 20, 2026; check the upgrade guide before moving between minors.

Project activity

As of October 2026 the repository has about 29,000 stars and 4,150 forks. It was created in April 2018, is written in Go and is licensed AGPL-3.0-only with the Apache-2.0 exceptions above. The latest release at the time of writing is v3.7.9 (October 20, 2026), and the repository had a push on the day of writing. Source is at github.com/grafana/loki and documentation at grafana.com/docs/loki.