Write a LogQL query using the Query Builder

Now that you’ve defined the requirements for your visualization, it’s time to write the query. A query is an expression that specifies the dataset used in the visualization.

LogQL generates two types of queries: log queries and metric queries. Log queries select and return log lines, while metric queries wrap a log query in a function to extract and return metrics.

Elements of a LogQL query

A LogQL query consists of the following basic elements, as shown in the query count_over_time({namespace="game-2048"} |= error [$__auto]), which selects logs from the game-app namespace, filters for lines containing “error”, and counts them over 5-minute intervals.

Log stream selector

The stream selector determines which log streams to include in a query’s results. A log stream is a unique source of log content, such as a file. A more granular log stream selector then reduces the number of searched streams to a manageable volume. This means that the labels passed to the log stream selector will affect the relative performance of the query’s execution.

The log stream selector is specified by one or more comma-separated key-value pairs. Each key is a log label and each value is that label’s value. Curly braces ({ and }) delimit the stream selector.

For example, the {namespace = game-app} is the log stream selector that uses a filter expression. This selector returns all logs associated with a game app that’s being monitored.

Other common examples of selectors include:

• service_name: Identifies the application or service generating the logs.
• pod: Specifies the name of the pod where the log originated.  
• filename: Denotes the source file of the logs.

Log pipeline (optional)

For example, |= "error" is the log pipeline, which uses a line filter expression to retrieve only those log lines that contain the word error. You can also use other expressions, such as parser expressions or line format expressions.

Operation (optional)

An operation creates a metric query.

Metric queries extend log queries by applying a function to log query results. This powerful feature creates metrics from logs.

Metric queries can be used to calculate the rate of error messages or the top N log sources with the greatest quantity of logs over the last 3 hours.

Combined with parsers, metric queries can also be used to calculate metrics from a sample value within the log line, such as latency or request size. All labels, including extracted ones, will be available for aggregations and generation of new series.

For example, the count_over_time operation calculates the number of error logs received for each time interval.

How to write a LogQL query

To write a LogQL query using the Query Builder, complete the following steps:

1. Select a key-value pair from the Label filter drop-down list.

   For example, select namespace, =, and game-app.

   Did you know?

   If you are unsure of the label name, you can click Label browser and search for the label.

2. Click Refresh located in the toolbar.

   The visualization should populate with data.

   Did you know?

   At this stage, you can save the dashboard and share it with others. The current dashboard includes a Logs panel displaying all logs within the selected namespace. However, this view offers limited utility for troubleshooting.

   In the next steps, you'll learn how to apply a filter expression and aggregation to the log data to monitor the count of error logs per time interval.

3. To define a log pipeline expression, select a line filter operator and enter a value.

   For example, if you select Line contains and enter error, the system returns all error logs. All other log types (warning, info) aren’t included in the Logs panel.

4. Click + Operations and select a function.

   For example, click Range function > Count over time.

5. From the Visualization drop-down list located in the upper-right of the page, select Time-series.

   Did you know?

   When you apply an operation to log data, you are creating a metrics LogQL query.

6. Click Refresh located on the toolbar.

   The visualization updates to show a time series graph.