> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture of Loki

> Explains Grafana Loki architecture and workflow collecting labeling storing and querying logs using lightweight agents, labeled indexes, compressed chunks, object storage, and LogQL

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

| Component | Purpose | Example / Notes |
| - | - | - |
| Collector / Agent | Tails application logs and forwards them to Loki | `Grafana Alloy Agent`, `Fluentd`, `Fluent Bit`, `Logstash`, `OpenTelemetry Collector` |
| Labels (Index) | Small indexed set of key/value pairs attached at ingest time | Only labels are indexed — the log line itself is stored raw |
| Chunk storage | Compressed log content (append-only) | `S3`, `Google Cloud Storage`, `Azure Blob Storage`, or local filesystem for dev |
| Query engine | LogQL + frontend (Grafana) for searching and visualizing logs | CLI `logcli` or Grafana UI |

## 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:

```text theme={null}
{job="syslog", env="prod"}
sshd: session opened
sshd: auth failure

{job="apilogs", env="prod"}
GET /users 200 8ms
POST /login 200

{job="syslog", env="dev"}
disk usage 81%
kern: usb connect
```

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:

```text theme={null}
index

{job="syslog"}
{job="apilogs"}
{env="prod"}
```

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:

```bash theme={null}
$ logcli query '{job="syslog"} |= "error"'
```

Example LogQL selector and a sample result:

```logql theme={null}
{job="syslog"} |= "error"
```

```text theme={null}
logs
level=error msg="db timeout"
sshd[402]: error: auth fail
app: error opening app.log
level=error msg="502 upstream"
```

## 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.](https://mintcdn.com/kodekloud-c4ac6d9a/dEcIUoAxuol-3ZBK/images/Grafana-Loki/Grafana-Loki-Essentials/Architecture-of-Loki/three-machines-alloy-agent-loki-grafana.jpg?fit=max\&auto=format\&n=dEcIUoAxuol-3ZBK\&q=85\&s=2576b3a00ec4a2c247ac78bb3bdd4525)

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

* Grafana Loki — [https://grafana.com/oss/loki/](https://grafana.com/oss/loki/)
* LogQL documentation — [https://grafana.com/docs/loki/latest/logql/](https://grafana.com/docs/loki/latest/logql/)
* logcli — [https://grafana.com/docs/loki/latest/tools/logcli/](https://grafana.com/docs/loki/latest/tools/logcli/)
* Grafana Alloy Agent — [https://grafana.com/docs/agents/latest/](https://grafana.com/docs/agents/latest/)
* Fluentd — [https://www.fluentd.org/](https://www.fluentd.org/)
* Fluent Bit — [https://fluentbit.io/](https://fluentbit.io/)
* OpenTelemetry Collector — [https://opentelemetry.io/docs/collector/](https://opentelemetry.io/docs/collector/)
* Amazon S3 — [https://aws.amazon.com/s3/](https://aws.amazon.com/s3/)
* Google Cloud Storage — [https://cloud.google.com/storage](https://cloud.google.com/storage)
* Azure Blob Storage — [https://azure.microsoft.com/en-us/services/storage/blobs/](https://azure.microsoft.com/en-us/services/storage/blobs/)

> **[Watch Video](https://learn.kodekloud.com/user/courses/grafana-loki/module/d9262c89-9213-4e21-8599-d54b9c773885/lesson/fcb9ebe1-9d44-48dd-9eca-1c47b148ff49)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.