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.
Go to the Stackdriver > Logging page in the GCP Console:
Select an existing GCP project at the top of the page, or create a new project.
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.
Stackdriver accounts and Logging
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.
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 (▸):
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:
- The window tabs let you choose Logs, Metrics (see Logs-based metrics), Exports (see Exporting logs), and Resource Usage.
- 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.
- The basic selector menus lets you choose resources, logs, and severity levels to display.
- The time-range selector drop-down menus let you filter for specific dates and times in the logs.
- The streaming selector, at the top of the page, controls whether new log entries are displayed as they arrive.
- The log-entry table contains the log entries available according to your current filters and custom fields.
- 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.
- The View Options menu, at the far right, has additional display options.
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.
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.
You can select a time zone by which to filter your logs:
- 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.
- Click the expander arrow (▾) in either one of the new menus. A drop-down calendar menu appears.
- In the Time Zone section of the calendar menu, select your preferred country and time zone.
- Your Logs Viewer displays your updated time zone preference:
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:
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
- Otherwise, when the log entry has a payload containing a field named
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:
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:
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:
- 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.
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:
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:
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.
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.
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.
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.
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 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.
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: 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|
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|
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.
In the basic filter interface, all searches are case-insensitive substring
matches. That is, the searches
somefieldname:abc will match log
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 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
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|
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.
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:
- Select Convert to advanced filter in the ▾ menu at the end of the search box.
- Look at the advanced filter to see if it is what you intended.
- 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.