Skip to main content
Think about how a parcel makes its way across the country. Couriers pick up packages from many different buildings, everything goes to a central sorting center where each parcel is labeled by destination and priority, and then the parcels sit in storage until they’re needed. When you want to find one, you search by the label instead of tearing open every box on the shelf. Grafana Loki uses the same pattern for logs. Its architecture can be summarized as four core responsibilities: collect, label, store, and query. Below we walk through each phase and show how they fit together.
  • Collect
  • Label
  • Store
  • Query
Table — Key architecture components

​
1) Collect — lightweight agents near your apps

Loki does not read application processes directly. Instead, a lightweight agent runs close to your applications, tails log files or listens to stdout/stderr, and pushes log entries to Loki’s HTTP API. Most common agents:
  • Grafana Alloy Agent (recommended)
  • Fluentd
  • Fluent Bit
  • Logstash
  • OpenTelemetry Collector
You can run many agents that point to a single Loki server (or a cluster) so the collection layer integrates with your existing logging setup.
Use a lightweight forwarder (e.g., Grafana Alloy Agent or Fluent Bit) on each node to minimize resource usage and simplify log shipping. Agents add labels as the logs are forwarded so streams are grouped at ingest time.

​
2) Label — group streams and keep indexing minimal

When logs arrive, Loki groups them into streams using the labels attached by the agent (for example, job or env). Loki indexes only those labels; the log lines themselves are stored exactly as they were produced. This selective indexing is the core of Loki’s cost and performance benefits. Example mapping of log lines into labeled streams:
Because Loki only indexes labels, choose them carefully. If you need to search arbitrary text across logs frequently, consider adding labels for those fields or using LogQL parsing operators — otherwise full-text search will be slower or unavailable.

​
3) Store — compact index + compressed chunks in object storage

Loki stores two things side-by-side:
  • A compact index of labels and time ranges that points to log chunks.
  • The compressed log chunks that contain the raw log lines.
For production systems, chunks are typically stored in cost-efficient object storage such as Amazon S3, Google Cloud Storage, or Azure Blob Storage. Object storage provides durability and scalability that makes long-term log retention affordable. For development or single-node setups, Loki can write chunks to the local filesystem. Example of a tiny index snapshot:
Benefits of this split design:
  • Small, fast index lookups (label queries are quick).
  • Low-cost, scalable storage of the large log payloads.
  • Retention and lifecycle policies handled by the object store.

​
4) Query — LogQL, logcli, and Grafana

Loki exposes a query language called LogQL for filtering, parsing, and aggregating logs. Queries can be executed:
  • From the CLI using logcli
  • From Grafana, where logs appear side-by-side with metrics and dashboards
Example CLI query:
Example LogQL selector and a sample result:

​
Concrete setup example

Imagine three machines:
  • Machine 1: Runs the Loki server and object-store connector.
  • Machine 2: Runs your application A + a local agent that tails logs and forwards them with labels.
  • Machine 3: Runs your application B + a local agent.
Each application node runs an agent that collects logs and forwards them to the central Loki server. The Loki server labels, indexes, and writes compressed chunks to object storage. Grafana queries Loki to retrieve and display logs alongside metrics. That’s the full journey of a log: from the moment it’s written to the moment you read it back in Grafana.
A system diagram titled "Three machines, one journey" showing app nodes on multiple machines running an "Alloy agent" that send logs to a central Loki server (machine 1), which processes and indexes them and forwards to Grafana.
These phases are described in more detail later in this article, followed by a walkthrough to install and run a local Loki + Grafana stack so you can try the end-to-end flow yourself. Links and references

Watch Video