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 Stackdriver Logging API, see entries.list. To read log entries using the Google Cloud SDK, see Reading log entries.

Getting started

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

    Go to the Logs Viewer page

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

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

If you cannot see any logs, see the Troubleshooting section below.

Workspaces and Logging

You do not need a Workspace to use Stackdriver Logging, unless you want the ability to send logs from Amazon Web Services (AWS).

If you use Stackdriver Monitoring and a Workspace, 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.

Logs Viewer filter interfaces

There are two filtering interfaces in the Logs Viewer:

  • The default basic filter interface lets you select logs from menus and has a simple search capability.
  • The advanced filter interface replaces the basic filter interface 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 side of the search-filter box in either interface. The following screenshot shows the Logs Viewer's layout. Four log entries from Compute Engine VM instances are shown. The second entry has been expanded by clicking its expander arrow (▸):

Logs Viewer

The basic filter interface has the following major components—indicated by red numbers in the screenshot above—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 Logs ingestion.
  2. The search-filter box in the basic filter interface 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 filter interface.
  3. The basic selector menus lets you choose resources, logs, and severity levels to display.
  4. The time-range selector drop-down menus let you filter for specific dates and times 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 log-entry table contains the log entries available according to your current filters and custom fields.
  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.
  8. The View Options menu, at the far right, has additional display options.
  9. The Download logs menu, at the far right, lets you download a set of log entries. For details, see download log entries.

Scroll and stream logs

When you first look at the Logs Viewer, you see enough 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 time

You can filter your log entries by time and date using the time-range selector menus below the search filter box.

Time-range selector

The default selection is Last hour. You can use the drop-down menu to select other time ranges or define a Custom range. Select Jump to time to filter the logs to a particular date and time, or use the Jump to now menu to see current log entries. Once you have made your selection, you can scroll the logs to inspect entries around that time. 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.

Change time zone

You can select a time zone by which to filter your logs:

  1. As shown in the preceding screenshot of the drop-down menu, under Last hour, select Custom. Two new drop-down menus appear to the right of Custom.
  2. Click the expander arrow (▾) in either one of the new menus. A drop-down calendar menu appears.
  3. In the Time Zone section of the calendar menu, select your preferred country and time zone.
  4. Your Logs Viewer displays your updated time zone preference:

Customize time zone

Expand log entries

The log-entry table displays a summary line for each log entry by default. Following is a screenshot with one summary line called out in red:

Log entry summary line

The Logs Viewer highlights certain fields of the log entry in the summary line. Certain fields are shown by default if they meet these criteria:

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

You can also add other fields to the summary line; see Add custom fields for details.

To see the full details for one log entry, click the expander arrow (▸) at the front of the summary line. To see the full details in a structured view for all the log entries available with your current filter, click the View Options menu at the far right and then select Expand All:

View Options menu

You can select Collapse All to collapse any expanded log entry details.

When you expand a summary line for a log entry, you will see a structured (JSON) view for that log entry:

Structured request log entry

For a description of the fields in the entry, see the LogEntry type.

Add custom fields

Custom fields are fields within log entries that you can bring into to a summary line for the main log entry summary.

There are 2 ways you can add custom fields to your log-entry table summary lines:

  • In an expanded log entry, click on a field within the JSON representation. In the resulting panel, select Add field to summary line:

Add field to summary line

  • From the Viewing Options menu at the top far right of the Logs Viewer, select Add custom fields (if you have existing custom fields in this project, this option will be Modify custom fields). In the resulting panel, add the desired JSON key and click Save. You can add multiple keys by separating them with a comma. To reorder the appearance of your custom fields in your summary lines, reorder the text in this panel and click Save.

Add JSON field to summary line

Custom fields are populated whenever they are available in your log entries. Custom fields are added to your current URL and remain as long as you are using that URL or are within the same browser session. You cannot set them at a global level and they cannot be saved per user or per GCP project.

Custom fields are highlighted in blue in your log-entry table:

Custom fields in summary line

There are 2 ways you can remove custom fields from your log-entry table summary lines:

  • From any summary line that features the custom field that you wish to remove, click on the field and select Remove field from summary line.
  • From the Viewing Options menu at the top far right of the Logs Viewer, select Modify custom fields. In the resulting panel, delete the JSON keys that you wish to remove and click Save.

Default fields cannot be removed from the log-entry table.

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:

Show matching entries

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.

Additionally, you can correlate App Engine request log entries and then view them in a nested structure. For details, see Viewing related request log entries and select your runtime language.

Show latency details

New! For App Engine request logs, the Logs Viewer provides a link to Stackdriver Trace for easy viewing of the log entry's latency details.

To show the menu of latency-related options for a log entry, identify the protoPayload.latency field:

Show protoPayload.latency

Click on the latency value:

Show latency options

The first two options in the menu restrict the log entries shown to those with higher or lower latencies. The last option in the menu restricts the log entries to those that contain trace details viewable by Stackdriver Trace. Specifically, the last option restricts the log entries to those where View trace details is enabled.

Viewing latency details in Stackdriver Trace

For certain App Engine request logs, the option View trace details is enabled. When enabled, click this option to open Stackdriver Trace and display the latency details of the log entry:

Show trace timeline

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, G​C​E 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.

  • Select the time range you want to see from the fourth menu, or select Jump to now from the fifth menu.

As you change your menu selections, you will see the matching log entries.

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 filter interface, you can look at only log entries from one resource type at a time. The advanced filter interface permits multiple resource types.

  • You will not see any logs if you browse to a time before your current retention window. For more information, see Logs retention periods.

Download log entries

With a few clicks, you can download, in JSON or CSV format, all of the log entries stored in the Logs Viewer's working memory. For performance reasons, the Logs Viewer attempts to load 100 log entries at a time and retains no more than 300 log entries in its working memory. These values are not configurable.

To download log entries, click the Download logs menu, which is located at the top far right of the Logs Viewer. In the download dialog, select JSON or CSV for the Log entry format, then click Download:

Show Download Details

To view JSON- or CSV-formatted log entries in a web page, follow the same steps as for a download but select View In New Tab.

Searching with the Logs Viewer

You can further narrow your searches using filters in both the basic and advanced filter interfaces. The advanced filter interface contains most of the same features as the basic filter interface, but allows for more powerful search capabilities.

For more information on searching with the basic filter interface, see Basic Logs Filters. For more information on advanced searches, see Advanced Logs Filters.

Differences between basic and advanced filters

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

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 filter 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 filter Advanced 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 filter 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 filter interface.

AND and OR

In the basic filter 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 filter interfaces:

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

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 filter 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 filter 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 filter 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 information on performance, see Finding log entries quickly.

Troubleshooting

This section provides instructions for troubleshooting common issues found when interacting or searching with the Logs Viewer.

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.

  • Is the time range too narrow? You can use the drop-down menus below the search filter box to select other time ranges or define a Custom range. Select Jump to time to filter the logs to a particular date and time, or use the Jump to now menu to see current log entries.

My search isn't working!

If you are not sure why your search is not working in the basic filter 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 filter 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 timestamps 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.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Logging