# Grafana Loki: label-indexed log aggregation for Prometheus users

> Loki stores compressed log lines and indexes only their labels, which keeps storage small and operations close to Prometheus. It is the right tool when you already run Grafana and Kubernetes, and the wrong one when you need full-text search.

**grafana/loki** — Like Prometheus, but for logs. By storing compressed, unstructured logs and only indexing metadata, Loki is simpler to operate and cheaper to run.

- Repository: https://github.com/grafana/loki
- Website: https://grafana.com/oss/loki
- Stars: 28,944 · Forks: 4,118
- Language: Go
- License: AGPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/grafana-loki

## The problem Loki solves: log storage that costs less than a full-text index

Most log systems index everything. Every line gets tokenised and written into an inverted index, which makes arbitrary text search fast and makes the storage bill large. Loki takes the opposite position. The README states that Loki "does not index the contents of the logs, but rather a set of labels for each log stream." The log lines themselves are stored compressed and unstructured. Only the metadata is indexed.

That single decision drives everything else. Because the index is small, it is cheaper to run and simpler to operate, which is what the project means when it calls itself cost effective. It also means a query cannot begin with a word you saw inside a message. It begins with a label selector, the same kind you already write in PromQL, and only then filters the matching streams by content.

Who this is for: teams already running Prometheus and Grafana who want logs correlated with metrics using the same label set, and platform teams running Kubernetes who want pod logs collected without hand-writing per-application parsing rules. The README notes that Loki is "an especially good fit for storing Kubernetes Pod logs" and that pod metadata such as labels is scraped and indexed automatically. Who it is not for: anyone whose daily work is searching log bodies for a stack trace fragment with no idea which service emitted it.

## How Loki works: three components, push instead of pull

A Loki-based logging stack has three parts, as the README lays them out. Alloy is the agent that gathers logs and sends them to Loki. Loki is the service that stores logs and processes queries. Grafana queries and displays them. Native support exists in Grafana from v6.0 onward.

The data flow is push-based, and the README calls this out as an explicit difference from Prometheus: Loki "delivering logs via push, instead of pull." An agent on the node or in the pod reads log output and pushes it to Loki's HTTP API. The API documentation is the reference for getting logs in.

The storage split is the mechanism worth understanding. A stream is identified by a label set. Loki indexes that label set and the time range, then appends the raw, compressed log lines. Query time therefore has two phases: the index narrows to a set of streams, and then the engine scans those streams' chunks and applies your filter expression to the line contents. If your label selector matches almost everything, you have paid for a full scan. If it matches nothing, you get nothing, however well you remember the message text.

Loki is described as horizontally scalable, highly available and multi-tenant, and as a system with no dependencies, the same way Prometheus ships as a single binary. The repository also carries an operator/ directory and a production/ directory, and the examples/ tree contains getting-started, ha-monolithic and nomad configurations, which tells you the project expects to be deployed in more than one shape.

## Install Grafana Loki and send a first log line

The README does not inline install commands. It points to the installation documentation at grafana.com/docs/loki/latest/installation/, to the Alloy install page, and to a Getting Started guide. So the commands below are the ones the project's own tooling exposes, not a hand-rolled procedure.

The repository builds with make, and the Makefile defaults to running build steps inside containers. Running the same target on the host is a supported path: the Makefile comment says you can run `make BUILD_IN_CONTAINER=false target` if you have the correct tools installed and want to speed up development. The Go version pinned in the Makefile is 1.26.6, and the module is `github.com/grafana/loki/v3`.

```bash
make BUILD_IN_CONTAINER=false loki
```

After that, the Docker driver client is the shortest route to a first log line if you already run containers. The README lists it as "a Docker plugin to send logs directly to Loki from Docker containers", with its own page under the clients section of the docs. LogCLI is the counterpart on the read side: the README describes it as providing "a command-line interface for querying logs", which is how you confirm the line arrived without opening Grafana.

For a Kubernetes deployment, the README's Helm chart migration notice matters before you start. Effective March 16, 2026, the chart is being forked to grafana-community/helm-charts, and the chart in the Loki repository will continue to be maintained for GEL users only. Pick your chart source deliberately rather than copying a manifest from a blog post.

One more operational tool is worth knowing on day one: Loki Canary, which the README describes as monitoring your Loki installation for missing logs. It is the project's own answer to the question of whether ingestion is silently dropping data.

## Where Loki is the wrong tool

The absence of full-text indexing is not a footnote, it is the product. If your incident workflow is "grep for this exception class across every service for the last week", Loki will make you do it in two steps: first guess the labels, then scan. A system that indexes log contents answers that query directly. Loki's README is honest about the trade: it does not do full text indexing on logs, and it is simpler and cheaper because of that.

Label cardinality is the second failure mode, and it is the one teams hit in production. Because labels are what get indexed and what define a stream, a label whose value changes per request (a user ID, a request ID, a full URL) multiplies streams. The README's labels documentation is the place to read before you design a schema; the labels page is listed among the commonly used sections. Nothing in the README suggests Loki protects you from a bad label choice.

Third, the agent story has a boundary. The README states plainly that Alloy replaced Promtail in the stack because Promtail is considered feature complete, and that future development for logs collection will be in Grafana Alloy. If your existing setup is built around Promtail, that is a migration you will eventually be doing, not a configuration you can leave alone indefinitely.

Finally, this is a system you operate. Loki is multi-tenant, horizontally scalable and highly available, which are properties you get by running the pieces, not by installing a binary. The operations documentation and the troubleshooting page exist because there are error messages to deal with.

## Loki compared with Elasticsearch-style log search

The real alternative for most teams evaluating Loki is an inverted-index log store in the Elasticsearch family, and the difference is architectural rather than a matter of feature checklists. An inverted-index system tokenises log bodies at ingest and writes them into an index. That makes content queries fast and makes the index roughly the size of the data, or larger. Loki inverts the priority: it writes a small index over labels and stores the bodies compressed and unindexed, so storage stays small and content queries cost a scan of whatever the label selector admits.

The consequence is a different operational profile. With an inverted index you tune shards, mappings and retention on the index. With Loki you tune label cardinality and the chunk store, and you accept that query cost is a function of how well your selectors narrow. The README frames the choice in exactly those terms: compared to other log aggregation systems, Loki does not do full text indexing, and by storing compressed, unstructured logs while indexing only metadata it is simpler to operate and cheaper to run.

There is a second axis, and it is the one that decides adoption in a Prometheus shop. Loki indexes and groups streams using the same labels you already use with Prometheus, which lets you move between metrics and logs without translating a naming scheme. An Elasticsearch deployment does not give you that for free; you build the correlation yourself. If your team lives in Grafana and PromQL, that alignment is worth more than content search. If your team lives in a log-search UI and thinks in queries over message text, it is worth less, and you should pick accordingly.

## Licence, upgrades and the cost of staying current

Loki is licensed under AGPL-3.0. The repository also carries a LICENSING.md file alongside LICENSE, which is where the project itself explains how licensing is applied across the codebase; read that rather than treating the top-level identifier as the whole story. This is not legal advice, and whether AGPL-3.0 obligations affect your deployment depends on how you run and modify the software, so route that question to your own counsel.

Upgrade cost is documented rather than implicit. The README links an Upgrading Loki page under grafana.com/docs/loki/latest/upgrading/, and the repository keeps a CHANGELOG.md. Releases are frequent: v3.7.7 and v3.6.16 were both tagged on 2026-08-27, and the operator shipped v0.11.0 on 2026-08-18. Two maintained minor lines plus a separately versioned operator means you have a choice about how fast to move, but it also means an upgrade plan is not optional over a long horizon.

The last push to the default branch was on 2026-08-27, so the project is being worked on. The cost that is easy to underestimate is not the binary, it is the stack around it: Alloy on the ingest side, Grafana on the query side, and a Helm chart whose maintenance home is changing. Budget for those three moving parts, not just for Loki.

## Conclusion

Adopt Loki if your logs are Kubernetes pod output, your team already runs Prometheus and Grafana, and you can live with label-scoped queries. Do not adopt it if your primary workflow is full-text search across arbitrary log bodies, or if you need a query language that matches on message content without first narrowing by label. Before committing, verify three things: that your label scheme is low-cardinality enough to be useful, that Alloy is deployed as the agent (Promtail is feature complete and no longer where log collection development happens), and that you have read the Helm chart migration note, because the chart in the Loki repository is being forked to grafana-community/helm-charts and will only be maintained for GEL users.

## FAQ

### What is Grafana Loki used for?

It is a log aggregation system for storing and querying logs. The README describes it as inspired by Prometheus, indexing labels for each log stream rather than the contents of the logs, and as an especially good fit for Kubernetes Pod logs.

### Is Grafana Loki deprecated?

No. The repository is not archived and the last push to the default branch was on 2026-08-27, with v3.7.7 and v3.6.16 released the same day. What the README does say is that Promtail, the older log collection agent, is considered feature complete and that future log collection development is in Grafana Alloy.

### Is Grafana Loki free or paid?

The source is published under AGPL-3.0, with a LICENSING.md file in the repository covering how licensing is applied. The README's Helm chart notice refers to GEL users, and the chart in the Loki repository will continue to be maintained for them only.

### Is Loki better than Splunk?

The README does not compare Loki with Splunk, so no direct answer is possible here. The architectural difference it does state is that Loki does not index log contents, only labels, which makes it simpler to operate and cheaper to run than systems that do full text indexing.

### How do I install Grafana Loki on Ubuntu?

The README does not give per-distribution install steps. It points to the installation documentation at grafana.com/docs/loki/latest/installation/ and to the Getting Started guide, and the repository itself builds through make with BUILD_IN_CONTAINER=false for a host build.

### What are Grafana Loki and Alloy together?

They are two of the three components of a Loki-based logging stack. Alloy is the agent that gathers logs and sends them to Loki, Loki stores and queries them, and Grafana displays them. Alloy replaced Promtail, which the README says is feature complete.

## Sources

- [Official documentation](https://grafana.com/oss/loki)
- [Official README](https://github.com/grafana/loki#readme)
- [Project repository](https://github.com/grafana/loki)
- [Release notes](https://github.com/grafana/loki/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/grafana-loki