This guide shows you how to search logs and view log entries with the Logs Viewer.
- To read log entries through the Stackdriver Logging API, see entries.list.
- To read log entries using the Cloud SDK, see Reading log entries.
Before you begin
You don't need a Workspace to use Logging, unless you are sending logs from Amazon Web Services (AWS) to Logging.
The Logs Viewer displays logs for a single Google Cloud Platform project. If you are using a Workspace, Logging doesn't combine the logs from the monitored projects. You must select a specific project to view its logs.
If you are using a Workspace and AWS, select the AWS connector project to see the AWS logs.
Go to the Stackdriver Logging > Logs (Logs Viewer) 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.
Logs Viewer query interfaces
There are two querying interfaces in the Logs Viewer:
- The basic query interface lets you select logs from menus and has a simple search capability.
- The advanced query interface lets you view log entries from multiple logs and has a more sophisticated search capability.
You can switch between these interfaces using the drop-down arrow (▾) at the far right of the search-query box in either interface.
The following screenshot shows the Logs Viewer's layout with the basic query interface. The screenshot displays log entries from a App Engine application:
The basic query interface has the following major components—indicated by red numbers in the screenshot above—some of which are shared with the advanced query interface:
- The window tabs let you stay on Logs (the Logs Viewer page), or choose between other Stackdriver Logging features: Metrics (see Logs-based metrics), Exports (see Exporting with the Logs Viewer), and Logs ingestion (see Logs exclusions).
- The search-query box in the basic query interface lets you query log entries by label or text search. The basic query is shown, and the drop-down arrow (▾) at the far right lets you switch to the advanced query interface or get a link to your query. Log queries are labelled as "filters" in the user interface, since they let you select a particular set of log entries.
- The basic selector menu lets you choose resources, logs, and severity levels to display.
- The time-range selector drop-down menus let you query 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 queries 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.
- The Download logs menu, at the far right, lets you download a set of log entries. For details, see download log entries.
- The More (⋮) option, displayed with each log entry, lets you place a pin on the log entry, show the log entry in its resource context, and copy a URL for the log entry to the clipboard.
Lastly, the Logs Viewer uses the cursor position to highlight the associated log entry and to display a pin (📌) symbol next to the More (⋮) icon.
Scroll and stream logs
When you first open 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.
The icons at the top of the screen control when the logs are refreshed:
- Click the refresh icon ( ) to retrieve the latest logs; scroll downwards to display them.
- Click the play icon ( ) to stream the latest logs. Streaming stops when you select a log entry or scroll through the logs display.
- Click the pause icon ( ) to stop streaming.
Scroll to a time
You can query your log entries by time and date using the time-range selector menus below the search-query box.
The default selection is Last hour. You can use the drop-down menu to select other time ranges or define a range:
- Select Jump to time to query the logs to a particular date and time.
- Select Custom to specify a custom range or a time zone.
To show the current log entries, click Jump to now.
In all cases, a selection causes the Logs Viewer to refresh the display. You can then scroll through, and inspect, the displayed log entries.
To reset the date and time to correspond to the most recently received log entry, click the Refresh or the Play icon.
Change time zone
You can select a time zone for your log entries:
- From the Last hour drop-down menu, select Custom.
- Click the expander arrow (▾) in either one of the new menus to open a drop-down calendar.
- In the Time Zone pane, select your preferred country and time zone.
Your selection causes the Logs Viewer to refresh the display and update the time zone for each log entry:
Expand log entries
The log-entry table displays a summary line for each log entry by default.
The log entry summary line might contain highlighted fields. For example, custom fields are highlighted.
The fields included in the summary line are selected as subsets of the log entry fields. Certain fields are shown by default if they meet one or more of these criteria:
- The log entry has a well-known type such as an App Engine request log.
- The log entry contains the
- The log entry has a payload containing a field named
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 query, click the View Options menu at the far right and then select Expand All:
You can select Collapse All to collapse all expanded log entry details.
When you expand a summary line for a log entry, the Logs Viewer displays a structured (JSON) representation:
For a description of the fields in a log entry, see the LogEntry type.
Add custom fields
Custom fields are fields within log entries that you can specify to be included in the summary line. These fields are populated, and highlighted in blue, whenever they are available in your log entries.
There are two 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 is 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.
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.
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.
Default fields cannot be removed from the log-entry table.
Pin a log entry
If you have identified an interesting log entry and want to investigate nearby entries, you can place a pin on the log entry. After the log entry is pinned, you can change the query and the Logs Viewer automatically centers the search around the pinned entry. Pinning gives you the ability to examine a log entry in the context specified by a query you define. After a log is pinned, its background is changed and a pin is shown:
To pin a log entry, click its pin or click More (⋮) and select Pin this log entry.
When you place a pin on a log entry, that pin is visible only to you. Any other users viewing the same log entries won't see your pin or have their view modified in any way.
Pinning a log entry doesn't change the query interface, the query settings, or refresh the displayed contents. You determine the query settings and when to refresh the Logs Viewer display. You can modify the query settings and refresh the display as many times as you want without affecting the pin.
Pinning a log entry stops streaming if it is currently enabled.
If a log entry is pinned, you can move or remove the pin:
To move the pin to a different log entry, on the new log entry click its pin icon or click More (⋮) and select Move pin to this log entry.
To remove the pin from a log entry, click its pin symbol or click More (⋮) and select Remove pin from this log entry.
If you enable streaming while a log entry is pinned, the Logs Viewer removes the pin.
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 query interface. To modify the search, edit the query and click Submit Filter. For more information, see the Advanced query 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
Click on the latency value:
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 in resource context
If you have identified an interesting log entry and want to identify other log entries associated with the same resource type, click More (⋮) at the far right of the line and select the option Show in resource context:
In response to your action, the Logs Viewer:
- Pins the log entry.
- Switches to the advanced query interface and replaces the query contents with a query on the resource type.
- Refreshes the display. The pinned log entry is shown towards the bottom of the display.
Share a log entry
To share a log entry, click More (⋮) and select Copy link to log entry to clipboard. This action causes the Logs Viewer to generate a unique URL for the log entry and copy the URL into the clipboard.
Use the menus and search-query 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 also shows 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 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 might 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 query interface, you can look at only log entries from one resource type at a time. The advanced query interface permits multiple resource types.
You won't 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 aren't 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:
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 queries in both the basic and advanced query interfaces. The advanced query interface contains most of the same features as the basic query interface, but has more sophisticated search capabilities.
- For detailed information on querying by label or text, see Basic logs queries.
- For detailed information on querying by expression, see Advanced logs queries.
Differences between basic and advanced queries
The syntax for the basic and advanced query interfaces is different. The basic query interface is built with assumptions, for example, all searches are case insensitive, that are invalid for the advanced query interface.
The next few sections highlight key differences in the syntax between these two interfaces.
The Logs Viewer shows text searches in the basic query by prefixing the text
with the label
Don't use the
text: label with advanced queries.
The following table shows equivalent text searches:
|Logs Viewer basic query||Advanced logs query with the same meaning|
If you accidentally use
text: in the advanced query, you search
for a match in a field called
text, which doesn't exist.
The basic query interface has built-in field names for certain logs, including the App Engine request log. Those field names don't exist in advanced queries.
The following table shows an equivalent field search for an App Engine request log:
|Basic query||Advanced query|
If you use
querystring:var=3 in the advanced filter, you
search for a field named
querystring, which doesn't exist. Therefore,
the Logs Viewer doesn't find any matching log entries.
In the basic query interface, all searches are case-insensitive substring
matches. That is, the searches
somefieldname:abc matches log
ABc. In advanced log queries, 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 query interface.
AND and OR
In the basic query interface, two comparisons using the same field name
text:) are implicitly joined with
OR, whereas comparisons with different
labels are joined by
AND. In advanced logs queries, all comparisons are
OR is specified explicitly. You can also use
parentheses to group comparisons. The following table shows equivalent searches
in the two query interfaces:
|Basic query search||Advanced query 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 query interface, you do this with menu selections. In the advanced query interface, use conditions like the following:
resource.type = "gce_instance" logName = "projects/[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 query interface, all text searches are partial matches. In the advanced query interface, favor tests using equality operator (
=) rather than using "has" (
Shorten the time period searched. You cannot do this in the basic query interface, but in the advanced query 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.
You can save a basic or advanced logs filter search to a Saved Searches library and give the search a name and description. Basic filters are converted to advanced filters when saved to the Saved Searches library. You can name, manage, and share saved searches in your library. You are limited to 100 saved searches per user, per Google Cloud Platform project.
Create a saved search
To create a saved search, complete the following steps:
Filter for the logs you want to save by creating an advanced logs filter.
Click Save Search.
Name and describe the filter you created and then click Save to library.
The Filter Preview pane displays the filter criteria for the saved search.
View saved searches
To view your saved searches, click Show Library.
Edit saved searches
To apply your saved filter, delete the filter, or preview its notation, complete the following steps:
View your saved searches by clicking Show Library.
To preview or delete a saved search, click More more_vert.
You cannot change the filter criteria for a saved search once it's created. If you want to change the filter criteria of a saved search, delete the saved search and then create a new saved search with your desired criteria.
Share saved searches
You can share your saved searches with users who have Cloud Identity and Access Management permissions on your project.
To share a saved search, complete the following steps:
View your saved searches by clicking Show Library.
Click More more_vert and then Preview.
Click Copy link to Filter.
This section provides instructions for troubleshooting common issues found when interacting or searching with the Logs Viewer.
GCP project selection
To select a GCP project from anywhere in the Google Cloud Platform Console, including from the Logs Viewer, use the project selector at the top of the page:
GCP project ID
To retrieve the GCP project's ID from from anywhere in the Google Cloud Platform Console, including from the Logs Viewer, expand your list of projects at the top of the page and look in the ID column:
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-query box to select other time ranges or define a Custom range. Select Jump to time to query the logs to a particular date and time, or use the Jump to now menu to see current log entries.
Is the time range incorrect? If you are writing a query that includes a timestamp, you must select No limit from the time-range selector below the search-query box.
My search isn't working!
If you aren't sure why your search isn't working in the basic query interface, briefly switch to the advanced query interface:
- Select Convert to advanced filter in the ▾ menu at the end of the search-query box.
- Look at the advanced query to see if it is what you intended.
- Return to the basic query 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 Logging retention period. See Logs retention periods for the logs retention period in effect.
During periods of heavy load there could be delays in sending logs to Logging or in receiving and displaying the logs.
The Logs Viewer doesn't 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.