Get started with UQL log queries

Query logs 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.

Access to Cloud Observability Logging is available on request. Reach out to your Account Manager to get started.

Overview

Use UQL to explore and visualize logs in alerts, dashboards, and notebooks.

logs count queries analyze the number of logs matching certain conditions. The sections below describe the syntax and phrase_match, a filter predicate for finding logs with specific letters or words.

Syntax

logs count queries use the following syntax, where each query stage is separated by a pipe (|). The list below describes the stages in more detail.

1

logs count | <aligner> | <filter> | <group_by [], reducer>
  • logs count outputs a float with the number of logs.

  • aligner groups logs into a time series with points at regular intervals.

    For logs UQL, the aligner options are delta, rate, and reduce.

  • filter matches logs using filter expressions to narrow down your data.

    filter is the only optional query stage. All filter expressions are available except defined and undefined.

  • group_by [], reducer aggregates data with the same timestamp and [] value using the specified reducer.

Filter with phrase_match

phrase_match is a filter predicate for logs count queries. Use phrase_match to find logs containing specific letters or words.

phrase_match accepts two parameters: body and a search phrase. For example, the following search phrase of err matches err, error, or erroneous but not ferrous or terrestrial.

1
2
3
4

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

For search phrases with more than 1 token, the first N-1 phrase tokens must match sequential body tokens. The last phrase token only needs to match a prefix of the next body token. For example, the search phrase below matches an error and had an error but not san error.

1
2
3
4

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

Sample queries

This section shows several logs count examples. To use the examples, paste and edit the queries in Cloud Observability’s query editor.

Log volume grouped by Kubernetes application

Query syntax

1

logs count | delta | group_by[kube_app], sum

Sample output Line chart

Expandable end

Error frequency grouped by Kubernetes application

Query syntax

1

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

Sample output Line chart

Expandable end

Log volume grouped by Kubernetes application and severity

Query syntax

1

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

Sample output Table

Expandable end

See also

UQL cheat sheet

UQL reference

Get started with distributions in UQL

Updated Sep 13, 2023