Skip to main content

Common Loki Terminologies

Key Concepts​

Log Stream​

A log stream in Grafana Loki is a sequence of logs that share the same set of labels. These log entries are grouped together based on the metadata defined by the labels. The log stream forms the foundation of how logs are organized in Loki.

Key Points:​

  • Identification: Each log stream is uniquely identified by its labels. No two log streams can have the same exact labels, ensuring that logs from different services or environments don’t get mixed up.
  • Functionality: Log streams help in organizing log data for quick retrieval. By grouping related logs together, Loki can efficiently handle large volumes of log data.

Example:​

Imagine you have multiple services running. You could have log streams like:

  • Logs from a web server: {service="web", host="server1"}
  • Logs from a database: {service="db", host="server2"}

Each service would have its own log stream, and you can easily query logs related to the web server or database separately.

Labels​

Labels are key-value pairs used to tag or categorize log streams. They define the identity of each log stream and play a vital role in querying logs efficiently.

Key Points:​

  • Syntax & Definition: A label is a simple key-value pair like {hostname="server1", app="nginx"}. Here, hostname is the key, and server1 is the value.
  • Importance: Labels help categorize log streams, enabling easy filtering and sorting. For example, you can filter logs for a specific application or host using these labels.
  • Best Practices: Choose descriptive and concise labels to avoid ambiguity. Make sure the labels are relevant to the operations you're monitoring.

Example:​

  • Logs from Nginx web server could be tagged as: {app="nginx", env="production"}.
  • Logs from the MySQL database might be tagged as: {app="mysql", env="development"}.

These labels help easily identify the source of the logs, making it simpler to filter and query specific logs when needed.

Queries​

Queries in Loki are instructions used to retrieve and analyze logs. Loki uses LogQL, a powerful query language inspired by PromQL (Prometheus Query Language), which allows users to filter and aggregate logs based on their labels.

Key Points:​

  • LogQL: The query language used in Loki. It allows you to query logs based on labels and expressions.
  • Structure: A query can be a combination of filtering and aggregation. For example: rate({app="nginx"}[30m]), which retrieves the rate of logs for the nginx app in the last 30 minutes.
  • Performance: Crafting efficient queries is important for performance, especially when dealing with large datasets. Using labels effectively in queries ensures faster responses.

Example:​

To retrieve logs from the nginx app where the log level is error over the last 30 minutes, the query might look like:

{app="nginx", level="error"} |= "timeout" | logfmt

This query does the following:

  • Filters for logs with the label app="nginx" and level="error".
  • Searches for logs containing the string "timeout".
  • Uses logfmt to format the output logs.

Visualizing Loki's Log Structure​

Let’s visualize how log streams, labels, and queries work together in a typical setup:

Key Points from the Diagram:​

  • Logs are grouped into log streams, and each stream is uniquely identified by labels (e.g., app="nginx", hostname="server1").
  • Queries are written to filter logs based on labels, like app="nginx" or level="error".
  • The result of these queries is a set of filtered logs that match the criteria.

Examples​

Example 1: Creating a Log Stream​

To create a log stream for your Apache web server, choose relevant labels like hostname and application:

{hostname="web1", application="apache"}

This means all logs coming from the Apache application running on web1 will be aggregated into this log stream.

Example 2: Executing a Query​

If you want to check for error logs generated by the nginx application, your LogQL query might look like:

{app="nginx", level="error"} |= "timeout" | logfmt

This query will:

  • Find logs labeled with app="nginx" and level="error".
  • Search for logs that contain the string "timeout".
  • Format the logs using logfmt.

Example 3: Aggregating Logs​

You can aggregate logs to find the rate of errors over time:

rate({app="nginx", level="error"}[1h])

This query will calculate how many errors occurred in the past hour for the nginx application.

Conclusion​

Understanding the core terminology in Grafana Loki—log streams, labels, and queries—is fundamental to managing and analyzing logs effectively. By leveraging these concepts, you can organize your logs efficiently and perform sophisticated queries for troubleshooting and monitoring purposes.

As you continue to work with Loki, these building blocks will enable you to tackle more complex logging scenarios, ensuring your system remains reliable and scalable.