Get started with UQL log queries

Customize log queries to monitor performance and troubleshoot issues.

This page describes Cloud Observability’s Unified Query Language (UQL) for logs. You can also explore logs with Cloud Observability’s Unified Query Builder and logs tab.

Overview

Use UQL to explore and visualize logs in alerts, dashboards, and notebooks. UQL supports two kinds of log queries:

  • logs - Analyze individual logs matching certain conditions.
  • logs count - Analyze the number of logs matching certain conditions.

Basic logs queries

logs queries return individual logs matching certain conditions. Use logs queries to monitor systems and investigate issues in dashboards and notebooks.

logs queries use the syntax below, where filter expressions are optional.

1
logs | <filter-expression> 

Examples

This section shows several logs examples. To use the examples, paste the queries in the query editor and select the logs list visualization.

View all logs:

1
logs

View logs where the customer attribute is sweetpines:

1
logs | filter "customer" == "sweetpines"

View logs where the customer attribute is sweetpines and err appears in the body attribute:

1
logs | filter "customer" == "sweetpines" && phrase_match(body, "err")

Logs count queries

logs count queries return the number of logs matching certain conditions. Use logs count queries to monitor systems and investigate issues in alerts, dashboards, and notebooks.

logs count queries use the syntax below, where filter expressions are optional. Visit UQL reference for more syntax details.

1
logs count | <aligner> | <filter-expression> | group_by [], <reducer>

Examples

This section shows several logs count examples. To use the examples, paste the queries in the query editor.

View log volume grouped by Kubernetes application:

1
logs count | delta | group_by[kube_app], sum

View error frequency grouped by Kubernetes application:

1
logs count | filter severity == ErrorSeverity | delta | group_by[kube_app], sum

View log volume grouped by Kubernetes application and severity:

1
logs count | delta | group_by[kube_app, severity], sum

View the number of logs where invalid prof appears in the body attribute:

1
2
3
4
logs count
| filter phrase_match(body, "invalid prof")
| delta
| group_by [], sum

Full text searches

Use phrase_match to find specific words, phrases, or numbers in logs. phrase_match works with logs and logs count queries.

The example below returns logs where err appears in the body attribute. The search phrase (err) matches terms such as err, erroneous, and terroir, but not retry.

1
2
3
4
logs count
| filter phrase_match(body, "err")
| delta
| group_by [], sum

For search phrases with several terms, phrase_match treats the last term as a prefix. For example, the search phrase an err matches an error and had an error but not an terror:

1
2
3
4
logs count
| filter phrase_match(body, "an err")
| delta
| group_by [], sum

See also

UQL cheat sheet

UQL reference

Get started with distributions in UQL

Updated Mar 7, 2024