Viewing Logs

This guide shows you how to search logs and view log entries with the Logs Viewer. To export your log entries, see Exporting Logs. To read log entries through the API, see entries.list. To read log entries using the SDK, see Reading log entries.

Getting started

  1. Go to the Stackdriver > Logging page in the Cloud Platform Console:

  2. Go to the Logs Viewer page

  3. Select an existing GCP project at the top of the page, or create a new project.

  4. Using the drop-down menus, select the resource whose logs you want to view.

There aren't any logs!

If you don't see any logs, then check the following:

  • Is the correct project selected at the top of the page? If not, use the drop-down menu at the top of the page to select a project. You must select the project whose logs you want to see.

  • Does your project have any activity? Even if the project is new, it should have activity or audit logs recording the fact that it was created. You can get more logs by going through the Quickstart.

Stackdriver accounts and Logging

You do not need a Stackdriver account to use Stackdriver Logging, unless you want Premium Tier features such as a longer log retention period and the ability to use Amazon Web Services (AWS).

If you use Stackdriver Monitoring and a Stackdriver account, note that Stackdriver Logging does not combine logs from monitored projects into the account project. You must select the project whose logs you want to see. For logs from an Amazon Web Services account, you must select the AWS connector project to see the AWS logs.

The user interfaces

There are two viewing interfaces in the Logs Viewer:

  • the default basic interface lets you select logs from menus and has a simple search capability.
  • the advanced filter interface replaces the menus with a more powerful search capability that you can use to view log entries from multiple logs

You can switch between the interfaces using the ▾ menu at the right size of the search filter box in either interface. The following screenshot shows the Logs Viewer's basic viewing interface. Four log entries from Compute Engine VM instances are shown. The third entry has been expanded by clicking its expander arrow (▸):

Logs Viewer

The basic viewing interface has the following major components, some of which are shared with the advanced filter interface:

  1. The window tabs let you choose Logs, Metrics (see Logs-based metrics), Exports (see Exporting logs), and Resource Usage.
  2. The basic search bar lets you filter log entries by label or text search. The basic filter is shown, and the menu at the end (▾) switches to the advanced logs filter interface.
  3. The basic selector menus lets you choose resources, logs, and severity levels to display.
  4. The Jump to date menu lets you scroll to a specific date and time in the logs.
  5. The streaming selector, at the top of the page, controls whether new log entries are displayed as they arrive.
  6. The View Options menu, at the far right, has additional display options.
  7. The expander arrow (▸) in front of each log entry lets you look at the full contents of the entry. For more information, see Expand log entries.

Scroll and stream logs

When you first look at the Logs Viewer, you see enough of the a most recent log entries to fill the screen. When you scroll through your log entries, the Logs Viewer tries to fetch additional entries. The yellow bar above and below the logs lets you know if more log entries might be available. Using the View Options menu, you can select the order in which to display log entries.

Icons at the top of the screen control when the logs are refreshed:

  • The "refresh" icon ("Jump to newest logs") will retrieve the latest logs and scroll the display to them.
  • The "play" icon (▶) will start streaming the latest logs. It stops if you select a log entry or scroll the logs display.
  • The "pause" icon (▐▐ ) will stop streaming the latest logs.

Scroll to a date

Use the Jump to date menu to scroll the logs to a particular date and time. You can scroll the logs to inspect entries around that date. Clicking the Refresh or Play icons at the top of the page will reset the date and time in that menu to the most recently received log entry.

Expand log entries

The Logs Viewer displays a summary line for each log entry by default. To see the full log entry, click the expander arrow (▸) for a structured view of the log entry. For a description of the fields in the entry, see the LogEntry type.

The following screenshot shows the structured view of a log entry. The log entry's payload is the textPayload field:

Structured request log entry

The Logs Viewer creates custom summary lines for log entries in the following circumstances:

  • If the log entry has a well-known type such as an App Engine request log.
  • Otherwise, if the log entry contains the httpRequest field.
  • Otherwise, if the log entry has a payload containing a field named message.

Show similar logs

You can click the value of an individual field in the expanded log entry view and then either show or hide all log entries with the same value. When you do this, the Logs Viewer changes to the advanced filter interface. To modify the search, edit the filter and click Submit Filter. For more information, see the Advanced filter interface.

Basic viewing interface

This section explains how to select and filter your logs in the basic viewing interface. For the other interface, see advanced filter interface. The basic viewing interface is shown below. You can recognize it by the presence of the resource, log, and severity selection menus:

Logs Viewer basic viewing interface

Selecting logs

Use the menus and filter box to find the logs you want to see:

  • Select a resource type and instance whose logs you want to see. You can look at all instances of this resource type, or select a particular instance. In the screenshot above, GCE VM instance (all instances) is selected. For a list of resource types, see Monitored Resource List

  • Select the named logs you want to see from the second menu, or select All logs. The menu shows the logs that are in use by the selected resource instances.

  • Select the lowest severity level you want to see in the third menu. Selecting Any log level will also show log entries that have no assigned severity.

As you change your menu selections, you will see the matching log entries. The following sections discuss how to use text filtering to further narrow your search.

Menu notes:

  • Only the resource types, instances, and log names that are present in your project are shown in the menus. It may take a short time for the menus to be updated after adding a new resource type or instance, or writing to a new log.

  • In the basic viewing interface, you can look at only log entries from one resource type at a time. The advanced filter interface permits multiple resource types.

  • Your log entries have a retention period based on your Stackdriver service tier. You will not see any logs if you browse to a time before your current retention window. For more information, see Stackdriver pricing.

Searching all fields

In the basic viewing interface, enter your text in the filter box above the menus and press ENTER. The search returns all log entries that include your search term(s) anywhere, in any field (except timestamp), and in any letter case. The word text: that the Logs Viewer adds before your search term(s) indicates that this is an "all fields" search.

Following are some common searches, and some that don't do what you expect.

Basic searches

Unicorn (text:Unicorn)

Finds all log entries containing unicorn, in any field and in any letter case.

unicorn phoenix (text:unicorn text:phoenix)

Finds all log entries containing unicorn or phoenix, in the same or different field(s). If you want log entries that contain both terms, use the advanced filter interface.

"unicorn phoenix" (text:"unicorn phoenix")

Finds all log entries containing unicorn and phoenix in the same field, in any letter case, separated by exactly one space. The basic viewing interface does not support searching for "unicorn and phoenix anywhere in the same field," but the advanced filter interface does.

2345 (text:2345)

Finds all log entries containing the string 2345. Numbers within log entries are generally represented as strings, so this will match, for example, 123456.

Searches that don't do what you expect

uni* (text:uni*)
This is not a wildcard search. This search finds all log entries containing the 4-character string "uni*". The Logs Viewer does not support regular expression searches and there are no special wildcard characters such as * or ?, in either the basic or advanced interface.
2017-02-05 (text:2017-02-05)
This does not match log entry time stamps. This search finds all log entries containing the string 2017-02-05 in any field except timestamp. If your log entries contain date strings in their payload or in other fields, then you can search for them. You can also use the Jump to date menu below the search box. The advanced filter interface lets you use searches that specify a range of time stamps.
200..299 (text:200..299)
This does not match 250. This basic interface search finds log entries containing the 8-character string "200..299". This range notation is only allowed in searches restricted to integer fields. See Searching specific fields.

Searching specific fields

You can restrict your search to a specific field by adding the field name and a colon in front of your search terms. The field name replaces text: in all-field searches. As you type in the search box, you will see a list of matching fields:

Basic field search

In the following examples, status: is the integer HTTP status code and path: is the HTTP path in the request:

path:query
Finds log entries whose HTTP path contains query in any letter case; for example, /query or /App/Query/17.
path:*
Finds log entries that have a path field. This is a special use of the asterisk (*) character; it is not generally treated as a special character.
status:200
View log entries with a status of (exactly) 200. The search will not match, for example, a status of 2000. Since status is known to be an integer field, the comparison is numeric.
status:abc
Illegal, because status is known to contain an integer.
status:400..499
Finds log entries with an HTTP status of 400 through 499. Ranges are only available for fields known to contain integers. If you use a range for other fields, the range is interpreted as a single string containing . characters.
path:query unicorn
Finds log entries whose path fields contain query and that contain unicorn in any field. Because unicorn is not preceded by a field name, it is as if you wrote text:unicorn. When you include search terms for different fields, or for fields and text:, the terms are implicitly connected with and.
path:query path:status
Finds log entries whose path field contains query or status. When you include multiple search terms for the same field, the terms are implicitly connected with or.
path:query status:200 path:status status:500..502
Finds log entries that have paths containing query or status, and that have status values of 200, 500, 501, or 502. In other words, or binds more tightly than and, and the order of search terms does not matter.

Troubleshooting

If you are not sure why your search is not working in the basic viewing interface, briefly switch to the advanced filter interface:

  1. Select Convert to advanced filter in the ▾ menu at the end of the search box.
  2. Look at the advanced filter to see if it is what you intended.
  3. Return to the basic interface by using the browser's Back button.

Here are some other reasons you might not see all the log entries you expect:

  • You cannot see log entries that are older than the Stackdriver Logging retention period. See Quota Policy for the logs retention period in effect.

  • During periods of heavy load there could be delays in sending logs to Stackdriver Logging or in receiving and displaying the logs.

  • The Logs Viewer does not show log entries that have time stamps in the future until the current time has "caught up" with them. This is an unusual situation, probably caused by a time skew in the application sending the logs.

Advanced filter interface

This section describes how to use the advanced filter interface in the Logs Viewer. You can recognize this interface by the absence of the log selection menus and presence of the Submit Filter button:

Advanced filter interface

Searching examples

The log entries shown are the ones that match the advanced logs filter in the text box. If the Jump to date menu contains a value, then the display will scroll to that point in time. Here are some filter examples:

resource.type=gae_app

Finds the same log entries as the basic viewing interface would show if you selected GAE Application (All module IDs) from the resource log menu and All logs from the log name menu. For a list of resource types, see Monitored Resource List.

resource.type=gae_app AND logName:request_log

Finds log entries for GAE Applications from log names containing request_log. Note several things:

  • The = operator is exact equality. The resource type must be exactly "gae_app" except for letter case.
  • The : operator means "has". The logName field must contain request_log, in any letter case. The actual log name is much longer. Using : might result in slower searches.
  • The two comparisons are joined by AND. You can also use OR, but AND is assumed if you leave out the operator.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Finds log entries with either of two resource types: GCE VM Instance or AWS EC2 VM Instance. The log entries must have severity of at least ERROR, which is equivalent to selecting ERROR in the basic interface's severity menu. You cannot view logs from multiple resource types in the basic viewing interface.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Finds all the Admin Activity audit log entries in the project [PROJECT_ID]. Audit logs all use the same log name in a project, but have different resource types. The log ID, cloudaudit.googleapis.com/activity must be URL-encoded in the log name. Using equality in the comparison speeds up the search. For more information, see Retrieving audit logs.

unicorn

Finds log entries containing unicorn in any field, in any letter case. A search term that is not part of a field comparison is an "all fields" query.

unicorn phoenix

Finds log entries that contain unicorn in some field and phoenix in some field.

textPayload:(unicorn phoenix)

Finds log entries whose textPayload field contains both unicorn and phoenix in any order—the AND is implicit between the two words.

textPayload:"unicorn phoenix"

Finds log entries whose textPayload field contains the string "unicorn phoenix". This is the same as in the basic viewer interface.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Finds log entries within a 30-minute period.

For more examples, details, and troubleshooting, see Advanced logs filters.

Searching by time

In the advanced filter interface, you can set specific limits on the dates of log entries to show. For example, if you add the following conditions to your filter, the Logs Viewer will show exactly the log entries in the indicated 30-minute period and you will not be able to scroll outside of that date range:

timestamp >= "2016-11-29T23:00:00Z"
timestamp <= "2016-11-29T23:30:00Z"

When writing timestamp filters, you must use dates and times in the format shown above.

Search performance

Here are some tips to increase your search performance:

  • Search for specific values of indexed fields, like the log entry's name, resource type, and resource labels. In the basic viewing interface, you do this with menu selections. In the advanced filter interface, use conditions like the following:

    resource.type = "gce_instance"
    logName = "project/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"
    resource.labels.module_id="default"
    resource.labels.instance_id="1234567890"
    
  • Choose exact matches over substring searches. Especially on index fields, partial matches are slower. In the basic interface, all text searches are partial matches. In the advanced filter interface, favor tests using equality operator (=) rather than using "has" (:).

  • Shorten the time period searched. You cannot do this in the basic interface, but in the advanced filter interface you can specify a time range:

    timestamp >= "2016-11-29T23:00:00Z" AND timestamp <= "2016-11-29T23:30:00Z"
    

For more informaiton on performance, see Finding log entries quickly.

Differences in basic and advanced filters

If you are familiar with the basic viewing interface's text and field searches, here are some hints to get you going with the advanced logs filters.

For more information about filters, see Advanced Logs Filters. You can return to the basic viewing menu by using the ▾ menu at the end of the search or filter box.

Don't use "text:"

The Logs Viewer shows text searches in the basic filter by prefixing the text with the label text:. The text: label must not be used with advanced filters. The following table shows equivalent text searches:

Logs Viewer basic filter Advanced logs filter with the same meaning
text:"one two" "one two"
text:three three
text:n=5 "n=5" (quotations required)

If you accidentally use text: in the advanced filter, you will be searching for a match in a field called text, which doesn't exist.

Check field names

The basic viewing interface has built-in field names for certain logs, including the App Engine request log. Those field names do not exist in advanced filters. For example, the following table shows an equivalent field search for an App Engine request log:

Basic interface filter Advanced logs filter
querystring:var=3 protoPayload.resource:"var=3"
status:400..405 protoPayload.status >= 400 AND protoPayload.status <= 405

If the first sample, if you accidentally use the basic filter field name, you will be searching for a field named querystring, which doesn't exist, so the Logs Viewer will find no logs.

Substring matches

In the basic viewing interface, all searches are case-insensitive substring matches. That is, the searches text:abc or somefieldname:abc will match log entries containing abc, xyabcyx, and ABc. In advanced log filters, you must use the "has" search operator (:) for the same behavior.

For an exact match, use the equals operator (=). The comparison field=abc requires that field contain exactly abc, in any letter case. That search cannot be expressed in the basic viewing interface.

AND and OR

In the basic viewer interface, two comparisons using the same field name (or text:) are implicitly joined with OR, whereas comparisons with different labels are joined by AND. In advanced logs filters, all comparisons are joined by AND unless OR is specified explicitly. You can also use parentheses to group comparisons. The following table shows equivalent searches in the two interfaces:

Basic interface search Advanced filter search
text:abc querystring:def text:xyz protoPayload.resource:"def" AND ("abc" OR "xyz")

What's next

Send feedback about...

Stackdriver Logging