Loki Architecture

Loki's founding decision fits in one sentence: index the labels, not the text. Elasticsearch builds an inverted index over every word of every line — spectacular for search, expensive to build and store. Loki indexes only each stream's label set, a few kilobytes per stream, and compresses the log content itself into chunks in object storage.

The bet behind that refusal: most operational queries start with "which service, which time window," and a label selector plus a time range answers both without any text index at all. The bet makes Loki dramatically cheaper to run and measurably slower at needle-in-haystack full-text search. Both halves are real, and this topic prices them.

The Founding Trade

In a classic log store, the full-text index is the dominant cost: it often rivals the raw data in size, and it wants fast local disks because every ingested line updates it. Loki refuses to build that index, which removes the cost entirely and moves the work to query time instead. Every design property of Loki, good and bad — the tiny operational footprint, the object-storage economics, the slow rare-string hunt — follows from this one refusal. Hold onto that; it explains everything below.

Streams and Chunks

A stream is one unique combination of label values. Its lines append into chunks — compressed blocks that shrink log text roughly 5–10x and flush to storage at around 1.5 MB each — while the index records only which streams exist and which chunks cover which time ranges. On Harborline, bookings running on two hosts produces exactly two streams.

# one stream = one unique label set
{job="bookings", host="app-01", env="prod"}
{job="bookings", host="app-02", env="prod"}
# per-request IDs ride on the lines themselves — never as labels

With a healthy label set like this, five services on a handful of hosts produce a few dozen streams, and the index stays well under 1% of the stored data. That ratio is the whole economic argument in one number — and it survives only as long as the labels stay few and static.

Object Storage Economics

Chunks and the TSDB index both live in object storage — GCS, S3, or a plain filesystem — at roughly $0.02 per GB-month instead of SSD-backed cluster nodes. Harborline runs Loki as a single binary on obs-01 with filesystem storage, and the architecture is the same one that scales to petabytes when the components run as separate services; retention becomes a lifecycle policy on cheap storage rather than a cluster-resizing project.

Queries as Distributed Grep

Without a text index, a query decompresses and scans chunks — Loki is a distributed, parallelized grep. The label selector and time range narrow the candidate chunk set first; brute force handles the rest. "Errors in bookings in the last hour" scans a few megabytes and returns in well under a second. "This UUID, anywhere, in the last 30 days" scans everything Loki has stored — the exact query Elasticsearch answers in milliseconds is the one Loki grinds through. Which engine is "fast" depends entirely on which query you actually run.

Cardinality Rules Here Too

Every new label value combination mints a new stream, and every stream costs index entries plus its own chunks. Make request_id a label and you get one stream per request: millions of one-line streams, chunks flushed nearly empty, an index bigger than the data it indexes, and ingesters running out of memory. The three costs from Chapter 1 — cardinality, sampling, retention — all apply to logs, and cardinality is the sharpest edge. It is the same disease that killed the Prometheus server in Chapter 3 when someone labeled a metric by user ID, wearing a different uniform.

Structured Metadata

So where do request_id and trace_id go? Loki 3.x's answer is structured metadata: key-value pairs attached to individual lines, filterable at query time, and held out of the stream index entirely. You keep per-request correlation without paying per-request streams. The rule of thumb the rest of the book uses: labels describe where logs come from (job, host, env); structured metadata or the line body carries what they contain.