This document describes how to save and share queries that you create in Log Analytics.
This document assumes that you are familiar with Log Analytics and how to use the Log Analytics page to query your log data. If you aren't familiar with these topics, see Query and analyze logs.
To learn how to chart your query results and how to save those charts to a custom dashboard, see Chart SQL query results.
Before you begin
Before you use Log Analytics, do the following:
-
To get the permissions that you need to use Log Analytics, ask your administrator to grant you the following IAM roles on your project:
-
To query the
_Required
and_Default
log buckets: Logs Viewer (roles/logging.viewer
) -
To query all log views in a project:
Logs View Accessor (
roles/logging.viewAccessor
)
You can restrict a principal to a specific log view either by adding an IAM condition to the Logs View Accessor role grant made at the project level, or by adding an IAM binding to the policy file of the log view. For more information, see Control access to a log view.
These are the same permissions that you need to view log entries on the Logs Explorer page. For information about additional roles that you need to query views on user-defined buckets or to query the
_AllLogs
view of the_Default
log bucket, see Cloud Logging roles. -
To query the
Ensure that your log buckets have been upgraded to use Log Analytics:
-
In the Google Cloud console, go to the Logs Storage page:
If you use the search bar to find this page, then select the result whose subheading is Logging.
- For each log bucket that has a log view that you want to query, ensure that the Log Analytics available column displays Open. If Upgrade is shown, then click Upgrade and complete the dialog.
-
Save a query
All queries that you run are automatically saved for 30 days and are accessible by selecting the Recent tab on the Log Analytics page. You can search, view, run, and share the queries that are listed on the Recent tab.
If you want to keep a query available for future use, annotate it with information that is useful to you, or let teammates view and run your query, then save the query. You can search and sort your saved queries by their name, their description, and their visibility label. You can also edit and delete these queries. Queries that you save are retained until you delete them.
You can save 10,000 queries per Google Cloud project.
Console
To save a query, do the following:
-
In the Google Cloud console, go to the Log Analytics page:
If you use the search bar to find this page, then select the result whose subheading is Logging.
Populate the Query pane with a query.
You can populate the Query pane by entering a new query, by selecting a query from the Recent tab, or by selecting a query from the Saved tab.
When the query in the Query pane is valid, the
Save is enabled.Click
Save and complete the Name and Description fields. The values you set for these fields are shown on the Saved tab.Optional: To let everyone with access to the Log Analytics page for the Google Cloud project view and run your saved query, enable the Share with project toggle.
By default, this toggle is disabled and the visibility is restricted to you.
Click Save query.
Optional: To view, sort, and run saved queries that are visible to you, select the Saved tab.
You can sort and filter your saved queries by their name, description, and visibility label. You can also filter by the contents of the query.
You can edit and delete queries that you created by using options on the Saved tab:
To edit a query, click more_vert More Options and select Edit. You can modify the values for the Name and Description fields; however, the query itself can't be modified.
To delete a saved query, click more_vert More Options and select Delete.
API
To save a query by using the Logging API, use the
savedQueries.create
method. For more information about this method, its
parameters, and the response data, see the reference page for
savedQueries.create
.
You can execute the savedQueries.create
method by using the
APIs Explorer widget on the method's reference page. For
Log Analytics queries, you must specify the opsAnalyticsQuery
field. The
following example illustrates a sample request body, which contains an
instance of SavedQuery
:
{ "parent": "projects/my-project/locations/global" "saved_query": { "ops_analytics_query": { "sql_query_text" : "SELECT timestamp, log_name, severity, json_payload, resource, labels FROM `TABLE_NAME_OF_LOG_VIEW` WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) ORDER BY timestamp ASC LIMIT 100" } "visibility": "PRIVATE" } }
Share a query
Console
When troubleshooting a problem, or when you see anomalous results, you might want to share a query and its results with a teammate. When you are viewing query results on the Log Analytics page, you can copy a URL that, when opened, displays the query you ran and its results.
To share a query and results with a teammate, do the following:
-
In the Google Cloud console, go to the Log Analytics page:
If you use the search bar to find this page, then select the result whose subheading is Logging.
Populate the Query pane with a query and then click Run query.
You can populate the Query pane by entering a new query, by selecting a query from the Recent tab, or by selecting a query from the Saved tab.
Click link Share link.
Send the link to your teammate.
When your teammate opens the link, the Log Analytics page is opened. This page displays the query that you ran and the results of the query.
To open the URL successfully, your teammate's Identity and Access Management role on the Google Cloud project must include the permissions required to view Logging pages.
API
You can use the Logging API to create a shared query by
using the savedQueries.Create
method, and specifying a value of SHARED
in
the visibility
field. For more information, see the reference page for
savedQueries.create
.
View and run recent or saved queries
To view or re-run a query, select the Recent tab on the Log Analytics page and find the query:
- To run the query, click Run.
- To view the query, use the options in the more_vert More Options menu.
To view, edit, or run a saved query, select the Saved tab on the Log Analytics page and find the query:
- To run the query, click Run.
- To edit, view, or delete the query, use the options in the more_vert More Options menu.