This document describes how you can create and manage log scopes, which you can use to help you efficiently find the log entries that you want to view or analyze. If you only want to view and analyze the log entries that originate in a project, folder, or organization, then this document isn't for you. However, if you rely on log sinks to route logs to other projects or to user-defined log buckets, or if you use log views, then the information in this document might help you efficiently find specific log entries.
This document doesn't describe how to view your logs. For information about that topic, see View logs by using the Logs Explorer.
About log scopes
Log scopes are persistent, project-level resources that list a set of resources to search for log entries. A log scope can include projects, folders, organizations, and log views. For example, you could define a log scope that lists the projects that contain resources used for production, or one that lists the log views that include log entries for a specific resource type.
When you create a Google Cloud project, folder, or organization resource,
Logging creates a log scope named _Default.
This scope includes the project, folder, or organization that was created.
The results of a search of these resources includes the log entries that
originate in the resource and then are stored in a log bucket.
For projects, the search results also includes log entries
that are routed to the project by a sink in another project
and then stored in a log bucket.
You can create log scopes. You can also edit and delete the
log scopes that you create. However, you can't
edit or delete the log scope named _Default.
For projects, the default log scope determines the set of resources
that the Logs Explorer page searches when it opens. However,
your Identity and Access Management (IAM) roles on the searched resources and the
time-range setting determine which log entries are fetched from storage.
When projects are created, the log scope named _Default is designated
as the default log scope. You can set which log scope is the
default log scope.
Best practices
Because log scopes provide a way for you to define and save a configuration for future use, we recommend that you create log scopes for complex search configurations.
For example, suppose that you are troubleshooting an issue and want to view the log entries for all virtual machine (VM) instances owned by your team. To accomplish this task, you might do the following:
You determine that the log entries that you want to view are stored in multiple log buckets and in multiple projects. For most log buckets, a log view exists that includes the log entries that you want to analyze. Where a log view doesn't exist, you can create one.
You decide to create a log scope because you expect to have a similar troubleshooting task in the future.
You open the Logs Explorer page in the Google Cloud console and then use the Refine scope menu to select your new log scope.
You review the log entries and find the information you need to resolve the issue you were investigating.
After you resolve the issue, you share the failure cause with your colleagues. You also share that you expect to see similar failures in the future, so you created a log scope that will let you, or whomever is investigating the failure, quickly find relevant log entries.
Limitations
- You can't delete or modify the log scope named
_Default. - Only Google Cloud projects support a default log scope.
- You can't add folders or organizations to a user-defined log scope.
- There is no Cloud Logging API or Google Cloud CLI support for creating or managing log scopes.
Before you begin
To get the permissions that you need to create and view log scopes, and to set the default log scope, ask your administrator to grant you the following IAM roles:
-
To create and view log scopes or to get the default log scope:
Logs Configuration Writer (
roles/logging.configWriter) on your project, folder, or organization -
To set the default log scope:
Observability Editor (
roles/observability.editor) on your project, folder, or organization
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to create and view log scopes, and to set the default log scope. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create and view log scopes, and to set the default log scope:
-
To get and set the default log scope:
observability.scopes.[get, update]
You might also be able to get these permissions with custom roles or other predefined roles.
List log scopes
To list the log scopes, do the following:
-
In the Google Cloud console, go to the settings Settings page:
If you use the search bar to find this page, then select the result whose subheading is Monitoring.
Select the Log Scopes tab.
The table lists your log scopes. When you've selected a Google Cloud project, one entry in the table is annotated with an icon labeled
Default, which indicates that this log scope lists the resources that the Logs Explorer searches when that page is opened.
Set the default log scope
The default log scope lists the resources searched by the Logs Explorer page when that page opens. If a default log scope doesn't exist or isn't accessible, then that page automatically searches for log entries that originate in the selected project, folder, or organization. The log entries displayed by the Logs Explorer page depend on the searched resources, the time-range setting, and your IAM roles on the searched resources.
When projects are created, the log scope named _Default is created
and is designated as the default log scope. However, you can create
your own log scope and designate it as the default log scope.
To set the default log scope, do the following:
-
In the Google Cloud console, go to the settings Settings page:
If you use the search bar to find this page, then select the result whose subheading is Monitoring.
- Select the Log Scopes tab.
Find the log scope that you want to designate as the default log scope, click more_vert More, and then select Set as default.
The log scope you selected is annotated with an icon labeled
Default.
Create a log scope
You can create 100 log scopes per project. A log scope can include a total of 100 log views and projects; however, it can only include 50 projects. You can't add folders or organizations to a log scope.
To create a log scope, do the following:
-
In the Google Cloud console, go to the settings Settings page:
If you use the search bar to find this page, then select the result whose subheading is Monitoring.
- Select the Log Scopes tab and then click Create log scope.
To add one or more projects, click Add projects, and complete the dialog.
After you add a project, your IAM roles on that project determine which log entries that you can view. For example, your IAM role might let you view only those log entries that are accessible by a specific log view on a log bucket. For more information about roles, see Logging roles.
To add one or more log views, click Add log views, and complete the dialog.
The dialog lists all log views that have log entries that originate in the current project, or that were routed to the current project by a sink in another project. For example, if you haven't configured any sinks, then this dialog lists the log views in your current project.
To list log views stored in another Google Cloud project, click add_circle Import project, and then select the Google Cloud project.
After you add a log view, your IAM roles on either the log view or the project that stores the log view determine which log entries that you can access. For more information, see Control access to a log view.
In the Name log scope section, enter the name and description that you want displayed on the Log Scopes tab.
The name of a log scope can't be modified and it must be unique within the project.
Click Apply.
Modify or delete a log scope
To modify or delete a log scope that you or a colleague created, do the following:
-
In the Google Cloud console, go to the settings Settings page:
If you use the search bar to find this page, then select the result whose subheading is Monitoring.
- Select the Log Scopes tab.
Find the Log Scopes that you want to modify or delete, click more_vert More, and then do one of the following:
- To modify, select Edit scope, and then complete the dialog.
- To delete, select Delete scope, and then complete the dialog.