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.

Navigating Nuance: Handling Feedback & Collaboration

Let’s be honest – even experienced developers can stumble when communicating technical ideas in English. For non-native speakers, the subtleties of professional jargon, especially within the context of DevOps and observability tools like Grafana Loki, can feel particularly challenging. It’s not just about knowing the words; it’s about conveying your meaning clearly, respectfully, and collaboratively – something that often requires a different approach to direct translation. A key area where this manifests is in receiving and responding to feedback on code reviews or PRs.

Often, the initial comment you receive isn’t necessarily a criticism of your code, but rather a suggestion for improvement framed within a specific technical standard or best practice. For example, a reviewer might say, “This stream could benefit from more descriptive labels – consider adding service and environment.” This isn’t about pointing out an error; it’s about guiding you towards a more robust and maintainable solution. Similarly, a Slack message requesting clarification on a particular LogQL query (“Can you explain why this index-light setup is working?”) requires careful phrasing to demonstrate understanding and willingness to engage in a deeper discussion. Avoiding overly literal translations – like simply saying “I don’t understand” – is crucial. Instead, try phrases like, “Could you elaborate on the reasoning behind using this specific query?” or “I’m having trouble connecting that LogQL pattern to the index-light architecture; could you walk me through it again?”

Furthermore, the language used in PR descriptions plays a vital role in setting expectations and facilitating collaboration. A well-written description should clearly articulate why changes were made, referencing relevant labels or query patterns. It’s not enough to simply state “Fixed bug.” Instead, aim for something like: “Implemented label filtering based on the user_id field to reduce index load. This addresses issue #1234 and improves query performance by approximately 15% (based on initial testing).” This level of detail demonstrates a proactive approach and allows reviewers to quickly assess the impact of your changes.

Finally, remember that asking for clarification is always acceptable – in fact, it’s encouraged! It signals engagement and a commitment to learning. Don’t be afraid to admit you need further explanation; it’s far better to ask than to misunderstand and potentially introduce unintended consequences.

# Example Loki LogQL query demonstrating label usage
lokiql() {
  echo "query = stream_name = \"metrics\" version = 1.0" | \
    lokiql --query="label_join(stream_name=\"metrics\", fields=\[\"service\", \"environment\", \"job_name\"])"
}