English for Loki Logging Developers

Loki conversations circle around one core trade-off constantly: unlike traditional log systems, it only indexes labels, not full log content, so the vocabulary centers on label design and how that choice shapes query performance.

Key Vocabulary

Label — a key-value pair attached to a log stream (like service or environment) that Loki actually indexes, as opposed to the log line’s text content, which is stored but not indexed. “Don’t put the request ID in a label — labels are meant for low-cardinality dimensions like service name, and a unique-per-request label will blow up the index.”

Stream — the set of log lines sharing an identical combination of label values, which Loki stores together; a new unique label combination creates a new stream. “Every user ID we’re putting in a label is creating a brand-new stream — that’s exactly why the index size is exploding, not the volume of log lines itself.”

Cardinality — the number of distinct values a label can take, which directly determines the number of streams Loki has to track and is the single biggest factor in its performance and cost. “This label has essentially unlimited cardinality since it’s a UUID — move it into the log line content and query it with LogQL’s filter instead, don’t index it as a label.”

LogQL — Loki’s query language, which first selects a set of streams using label matchers and then filters or parses the actual log line content within those streams. “Narrow the stream selection with labels first, then filter by content — a LogQL query that scans every stream because the label selector is too broad will always be slow.”

Chunk — the compressed unit of log data Loki stores for a stream, written once accumulated content reaches a size or time threshold, and the level at which log content is actually retrieved. “Query latency here isn’t about labels — it’s about how many chunks need to be decompressed and scanned once the query drops down to filtering log content.”

Common Phrases

• “Is this a label, or does it have high enough cardinality that it belongs in the log line content instead?”
• “Is this creating a new stream per request, or are the label combinations actually bounded?”
• “Is the LogQL query narrowing by label first, or is it scanning too many streams before filtering content?”
• “Is the slowness coming from stream selection, or from decompressing too many chunks during content filtering?”

Example Sentences

Diagnosing an index-size problem: “Storage costs jumped because someone added a per-request label — that’s turning every single request into its own stream instead of grouping requests under a shared, low-cardinality label.”

Reviewing a slow query: “This LogQL query only filters by log content and barely narrows by label first — it’s scanning far more streams than it needs to before it even gets to filtering.”

Explaining the architecture to someone from an Elasticsearch background: “Loki doesn’t index full text like Elasticsearch does — it only indexes labels, so query speed depends heavily on how well the label selection narrows things down before content filtering starts.”

Professional Tips

• Treat label cardinality as a hard constraint from day one — retrofitting a high-cardinality label out of a running system is far more painful than avoiding it upfront.
• Explain streams concretely when onboarding teams from other logging systems — the “one unique label combination equals one stream” mental model prevents most early cardinality mistakes.
• Flag any label that could plausibly be a UUID, request ID, or timestamp — these are the most common cardinality disasters in review.
• Push every slow LogQL query to narrow by label before it filters content — queries that lead with unindexed content filtering are the most common performance complaint.

Practice Exercise

1. Explain to a teammate why a request ID should never be used as a Loki label.
2. Describe how label cardinality directly drives the number of streams Loki has to manage.
3. Write a sentence reviewing a LogQL query that filters content before sufficiently narrowing by label.