Build queries in the Logs Explorer

Stay organized with collections Save and categorize content based on your preferences.
This document describes how to build queries in the Google Cloud console Logs Explorer to retrieve and analyze logs.

For more information about querying in the Logs Explorer, see Using the Logs Explorer.

Before you begin

To view the logs that you're sending from an Amazon Web Services (AWS) account to Logging, select the AWS connector project in the Google Cloud console resource picker and then use the Logs Explorer. 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 Viewing metrics for AWS accounts.

Ensure that you have the correct Identity and Access Management permissions or role for building queries using the Logs Explorer. For details on the necessary IAM permissions, see Access control with IAM: Google Cloud console permissions.

Get started

To begin using the Google Cloud console to build queries, navigate to the Logs Explorer:

Go to the Logs Explorer

Select the appropriate Cloud project or other Google Cloud resource for which you want to view logs.

Build queries

When building queries in the Logs Explorer, you primarily use the Query pane:

The Logs Explorer query pane

The Query pane provides multiple ways to build and run query expressions:

  • Search for text across all log fields.
  • Select options from filter menus.
  • Write advanced queries using the Logging query language.
  • View, edit, or run the queries in the Recent, Saved, Suggested and Library tabs.

The following sections describe these features in more detail.

Search for text across log fields

To search for text across all log fields and find all matching log entries, enter your search terms in the search field:

The Logs Explorer search field in the query pane.

To find log entries that contain a phrase, surround your search terms in quotation marks; you can also use Boolean operators in your search expressions. To see your search terms within the query expression, enable Show query.

After you enter your search terms, click Run query or press the Enter key. The results of the query are displayed in the Query results pane.

Boolean operators

Your search-field entries are converted into Boolean expressions that specify a subset of all the log entries in your selected Google Cloud resource.

The search field supports the usage of the Boolean operators AND, OR, and NOT. When using Boolean operators in your search expressions, note the following:

  • You can't use parentheses to nest rules. Any parentheses in the search expression are parsed as search terms.
  • You must capitalize Boolean operators. Lowercase and, or, and not are parsed as search terms, not as operators.

If you don't include any operators, all search terms and phrases are joined by AND. You can omit the AND operator between search terms.

The AND and OR operators are short-circuit operators. You can combineAND and OR rules in the same expression. For example, when the two operators are mixed, the expression a AND b OR c AND d turns into the following Logging query language expression:

"a"
"b" OR "c"
"d"

The NOT operator has the highest precedence, followed by OR and AND in that order.

The NOT operator performs a negation of the subsequent term. For example, NOT error returns log entries that don't contain error. You can also replace the NOT operator with the - (minus) operator. For example, the following two queries are the same:

response AND successful AND NOT error
response successful -error

This logic also works with a phrase, if the - (minus) operator is outside the quotation marks. For example, the following two queries are the same:

-"response successful"
NOT "response successful"

Use filter menus

You can use the filter menus in the Query pane to add resource, log name, and log severity parameters to the query-editor field. These options correspond to the LogEntry fields for all logs in Logging.

Filter menus for query editor

  • Resource: Lets you specify the resource.type and associated resource.labels. You can select a single resource type using this filter menu, and zero or more resource labels to apply to your query. The resource parameters are joined by the logical operator AND.
  • Log name: Lets you specify the logName. You can select multiple log names to apply to your query. When selecting multiple log names, the logical operator OR is used.
  • Severity: Lets you specify the severity. You can select multiple severity levels at the same time to add to apply to your query. When selecting multiple severity levels, the logical operator OR is used.

To use any of the filter menus, do the following:

  1. Expand any of the filter menus in the Query pane.

  2. Refine the filter parameters.

  3. Click Apply. You see the parameters in the query-editor field.

    To see your search terms within the query expression, enable Show query.

  4. After you review the query, click Run query. The results of the query are displayed in the Query results pane.

For certain Compute Engine resource types, such as gce_instance and gce_network, you see the resource name with the resource ID as subtext. For example, for the gce_instance resource type, you see the VM name alongside the VM ID. The resource names help you identify the correct resource ID, on which you can build queries.

Write queries with time restrictions

There are two ways to query logs based on time:

  1. Query using the time-range selector.
  2. Query using a timestamp expression in the query-editor field.

To quickly query over seconds, minutes, hours, or days, use the preset values or enter a custom time range using the time-range selector.

To add a timestamp expression directly to the query-editor field, use the Logging query language.

If the query-editor field contains an expression with a timestamp, then 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.

Use the time-range selector

The time-range selector lets you restrict query results by time range:

Time-range selector in the query pane.

To use the time-range selector, do the following:

  1. Click the time-range selector in the Query pane.

  2. Select the appropriate time range for which you want to see logs.

  3. Click Apply. You see the parameters in the query-editor field.

    The Query results pane adjusts according to the time range that you selected.

The default time range is one hour. You can use the Jump to time option to restrict and center the time range around a specific timestamp.

You can set your regional preferences, including date and time formatting, from the time-range selector:

  1. Select Enter custom range.
  2. Select Change date & time format.
  3. Update your preferences in the Language & region menu.
  4. Click Save.

    After you refresh your browser, your preferred date and time format appears in the Logs Explorer.

Write advanced queries using the Logging query language

You can use the Logging query language to build more advanced queries in the Logs Explorer query-editor field:

  1. If you don't see the query-editor field in the Query pane, enable Show query.

  2. Enter your query expressions directly into the query-editor field.

    If you added any search terms in the search field or selected any parameters in the filter menus, then those also appear in the query-editor field and are evaluated as part of your query expression.

  3. After you review your query, click Run query.

    Logs that match your query are listed under the Query results pane. The Histogram and Log fields panes also adjust according to the query expression.

For examples of common queries you might want to use, see Sample queries using the Logs Explorer.

Use recent queries

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

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

  • Stream: To run the query and stream the results, choose this option.
  • Run: To run the query, choose this option.
  • More options : Lets you view the query expression 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 save the query, do the following:

    1. Click Save as. The Save query dialog opens.
    2. Complete the following fields:

      • Name (Required): Provide a name for your query. Names are limited to 64 characters.
      • Description (Optional): Provide a description to help identify the purpose of the query.
      • Include summary fields (Optional): Enable Include summary fields and enter the summary fields that you want to display.
      • 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.
    3. Click Save query. The query is now available in your Saved queries list.

You can also sort and filter your recent queries; the filter matches on the text in your query expression.

Save queries

The Query pane features a Saved tab, where you can access your saved queries. Saved queries let you store query expressions to help you explore your logs more consistently and efficiently.

To save a query expression that you've built in the query-editor field, do the following:

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

  2. Complete the following fields:

    • Name (Required): Provide a name for your query. Names are limited to 64 characters.
    • Description (Optional): Provide a description to help identify the purpose of the query.
    • Include summary fields (Optional): Enable Include summary fields and enter the summary fields that you want to display.
    • 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.
    1. Click Save query. Your saved queries appear in a list under the Saved tab.

To run a saved query, click Run. To run the query and stream the results, click Stream.

You can also sort and filter your saved queries; the filter matches the text in your query expression.

Share queries

Shared queries let users of a Cloud project share their saved queries with each other. You can view shared queries within the Saved tab.

For the roles and permissions needed to view and edit shared queries, see Google Cloud console permissions. Note that users who have the IAM role roles/logging.admin or roles/editor can edit other users' shared queries.

Create a shared query

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

To create and share a query, do the following:

  1. Enter a query in the query-editor field.

  2. Click Save.

  3. Complete the fields in the Save query dialog.

  4. Enable Share with project.

  5. Click Save query.

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

To share an already-saved query, do the following:

  1. Select the Saved tab.

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

  3. In the Edit query dialog, enable Share with project, and then click Update query.

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

View shared queries

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

  1. Select the Saved tab.

  2. Click All.

  3. Sort the Visibility column.

The Visibility column indicates if and how the queries are shared:

  • Shared by me: Queries that you have saved and shared with other users of the Cloud project.
  • Shared: Queries that other users of the Cloud project have shared.
  • Private: Queries that you have saved and didn't share with other users of the Cloud project.

View only your queries

To view saved queries that you created or shared, click Mine. You now see a list of queries that you've created and saved. In the Visibility column, you can see your unshared Private queries. Queries that you've shared are denoted by Shared by me.

Use suggested queries

Logging generates suggested queries based on the context of your Cloud project, such as the Google Cloud products you're using. Suggested queries can help you identify issues and provide you with insights into the overall health of your systems. For example, 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, select the Suggested tab in the Query pane. The Suggested tab shows you a list of queries, each with descriptions and the following options:

  • Stream: To run the query and stream the results, choose this option.
  • Run: To run the query, choose this option.
  • More options : Lets you view the details of the query expression with the options to run the query or save it. You can also select the query directly to get these options.

    To review the details of a suggested query, do either of the following:

    • Select the query's row.

    • Click More and select View. The Query details dialog opens.

    In the Query details dialog, you see the query and the options to Run, Stream or Save As:

    • To save the query, do the following:

      1. Click Save As.
      2. Complete the fields in the Save query dialog.

      The edited query shows up in your Saved list, where you can choose to run the query later.

    • To run the query now, click Run. The query runs and appears in the query-editor field.

    • To run the query now and stream the results, click Stream.

    • To close the dialog and return to the suggested queries list, click Close.

Note the following expected behaviors:

  • Successive page loads might not show the same queries in the same order.
  • You might see zero suggested queries.
  • Sometimes running a suggested query returns zero logs.

Select queries from the library

Logging provides a library of queries based on common use cases and Google Cloud products. These queries can help you efficiently find logs during time-critical troubleshooting sessions and explore your logs to better understand what logging data is available.

To view and run the library's queries, do the following:

  1. Select the Library tab in the Query pane.

  2. In the All queries column, you see broad categories of available queries and subsets of queries based on Google Cloud products. To narrow the selection of queries that you see, click on any of the products.

    You can also use the search field to search the available queries by category, description, or the contents of the query expression.

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

    a. Click on the query's row.

    b. Click More and select View.

  4. In the Query details dialog, you see the query and the options to Run, Stream or Save As:

    • To save the query, do the following:

      1. Click Save As.
      2. Complete the fields in the Save query dialog.

      The edited query shows up in your Saved list, where you can choose to run the query later.

    • To run the query now, click Run. The query runs and appears in the query-editor field.

    • To run the query now and stream the results, click Stream.

    • To close the dialog and return to the suggested queries list, click Close.