Building log queries

This page describes how to build queries in the Google Cloud Console Logs Explorer to retrieve, refine, and analyze logs.

Before you begin

To view the logs for a specific Cloud project, select that Cloud project in the Google Cloud Console project picker and then use the Legacy Logs Viewer.

To view the logs that you are sending from an Amazon Web Services (AWS) account to Logging, select the AWS connector project in the Google Cloud Console project picker and then use the Legacy Logs Viewer. The AWS connector project stores the Amazon Resource Name (ARN) for your AWS account and links your AWS account to Google Cloud services. For more information, see Adding a project or account to a Workspace.

Getting started

To navigate to the Logs Explorer, do the following:

  1. Go to the Google Cloud navigation menu and select Logging > Logs Explorer:
    Go to the Logs Explorer
  2. Select a Google Cloud project.
  3. From the Upgrade menu, switch from Legacy Logs Viewer to Logs Explorer.

You're now in the Logs Explorer.

Building queries

The query-builder pane provides multiple ways to retrieve logs:

  1. Query builder drop-down menus.
  2. Queries using the Logging query language.
  3. Recent, Saved, and Suggested queries tabs.

query-builder-pane

The following sections describe how to build and run queries to retrieve your logs.

Query builder drop-down menus

The drop-down menus let you add query parameters to the Query builder. You can use the drop-down menus to select resources, log names, log severity, and time ranges. These options correspond to the LogEntry fields for all Logging logs.

Drop down menus for query builder

  • Resource: Lets you specify resource.type. You can select a single resource at a time to add to the Query builder. Entries use the logical operator AND.
  • Log name: Lets you specify logName. You can select multiple log names at once to add to the Query builder. When selecting multiple entries, the logical operator OR is used.
  • Severity: Lets you specify [severity][severity]. You can select multiple severity levels at once to add to the Query builder. When selecting multiple entries, the logical operator OR is used.

To use any of the search parameter menus, expand them and select a parameter, or multiple parameters, then click Add.

Once you've built your query, click Run Query to retrieve your desired log entries.

Queries with a time restriction

There are two ways to query logs based on time:

  1. Query using a timestamp expression
  2. Query using the time-range selector

    Logs Explorer is showing two ways to filter by time

If you have a query with a timestamp, the time-range selector is disabled, and the query uses the timestamp expression as its time-range restriction. If a query doesn't use a timestamp expression, then the query uses the time-range selector as its time-range restriction.

Queries using the Logging query language

You can use the Logging query language to build queries in the Cloud Logging query-builder pane, as well as in the Logging API, or the command-line interface.

For more details, see Logging query language.

Saved queries

The query-builder pane features a Saved tab, where you can access your saved queries.

List of Saved queries

Saved queries let you store query expressions to help you explore your logs more consistently and efficiently.

To save a query that you have built in the query-builder pane, do the following:

  1. Select Save in the query-builder pane. The Save query dialog opens, with your query expression in the Query field.

  2. Add a Name for your query.

    Names are limited to 64 characters.

  3. Optional: To add summary fields to your query, toggle Include summary fields.

  4. Optional: Add a Description for your query.

    Descriptions are limited to 1,000 characters. Don't include any sensitive information.

  5. Select Save query in the dialog.

Your saved queries appear in a list under the Saved tab in the query-builder pane.

To run a saved query, click Run query.

Shared queries

Shared queries let users of a project share their saved queries with each other.

For the roles and permissions needed to view and edit shared queries, see the Permissions and roles section on the Access control page.

Sharing a query

You can share queries that you have already saved, or you can share a new query.

To share a new query, do the following:

  1. Enter a query in the Query builder.

  2. Select Save from the query-builder pane.

  3. Complete the fields in the save-query dialog.

  4. Enable Share with project.

Your query is now shared with other users of the project.

To share an already saved query, do the following:

  1. Select Saved.

  2. Select More options > Edit , or select the query directly.

  3. In the edit-query dialog, enable Share with project, and then select Update query.

Your query is now shared with other users of the project.

Viewing shared queries

To quickly view all shared queries, sort the Visibility column to show shared queries first:

  1. Select the Saved tab.

  2. Select All.

  3. Sort the Visibility column.

Visibility column is sorted

The Visibility column distinguishes queries shared with you from queries you are sharing with other users of the project.

Suggested queries

Logging generates suggested queries based on its understanding of the Google Cloud products you're using. It proposes queries that can help you pinpoint issues and provide you with insights into the overall health of your systems. For instance, detecting that you're using Google Kubernetes Engine, Logging might suggest a query that finds all the error logs for your containers.

To view and run Suggested queries in the query-builder pane, do the following:

  1. Click on the Suggested tab.

    Suggested queries tab that show a set of queries

  2. Review the description of the Suggested query.

  3. To review the details of a Suggested query, do either of the following:

    a. Click on the row.

    b. Click More and select View.

  4. In the query-builder pane, you see the query and the options to Run or Save it.

    a. To save the query, click Save. The query shows up in your Saved list, where you can choose to run the query later.

    b. To run the query, click Run. The query shows up under Query preview in the query-builder pane.

  5. After you review the query, click Run query. The results of the suggested query are displayed under Query results.

Suggested queries are created dynamically based on the Google Cloud project context. Successive page loads might not show the same queries in the same order. This is expected behavior.

Recent queries

The query-builder pane features a Recent tab. When you run a query, the query is added to your Recent queries list, which contains the last 10,000 unique queries over a 30-day period.

The recent tab shows recent queries.

To view your recent queries, select the Recent tab in the query-builder pane. Within the Recent tab, you have the following options:

  • Stream. Streams logs based on the given query parameters.
  • Run. Runs the query.
  • More options . Lets you view the query parameters with the options to run the query or save it to your list of Saved queries. You can also select the query directly to get these options.

    To run the query, select Run.

    To save the query, select Save as, and complete the following fields:

    • Name (Required): Provide a name.
    • Description (Optional): Provide a description to help identify the purpose of the query.
    • Include summary fields (Optional): Enable Include summary fields and enter the fields you want displayed.
    • Truncate summary fields (Optional): Enable Truncate summary fields and select the number of characters to truncate to and whether truncation occurs at the beginning or end of the fields.

    Select Save query. The query is now available in your Saved queries list.

Note that you can also filter your recent queries; the filter matches on the text in your query's expression.