This document describes how you can create and manage a trace scope, which lets the Trace Explorer page find the trace spans that you want to view or analyze. If you only want to view and analyze the spans that originate in your Google Cloud project, then you don't need to configure any trace scopes. However, if your trace data is stored in multiple projects, as might occur when you use a microservices architecture, then you need to perform some configuration activities to view all spans from a single Google Cloud project.
This document doesn't describe how to view your traces and spans. For information about that topic, see Find and explore traces.
About trace scopes
Trace scopes are persistent, project-level resources that list a set of Google Cloud projects. You can configure the Trace Explorer page to search by trace scope, which means that the page searches the projects listed in the selected scope. Your Identity and Access Management (IAM) roles on the searched projects and the time-range setting determine what data is fetched from storage and then displayed.
When you create a Google Cloud project, a trace scope named _Default
is created. This scope only includes the Google Cloud project. You can't add
projects to this scope or delete this scope.
You can create trace scopes, and you can modify and delete any trace scopes that you create. You want to create a trace scope when you have a service that writes span data to multiple Google Cloud projects.
Unless you open the Trace Explorer page with a URL that includes a
trace scope or a trace and span ID,
the Trace Explorer page searches the
Google Cloud projects listed in the default trace scope for trace data.
When you create your project, the trace scope named _Default is
set as the default trace scope. However, you can select a different
trace scope to use as the default trace scope.
Before you begin
To get the permissions that you need to create and view trace scopes, and to set the default trace scope, ask your administrator to grant you the following IAM roles:
-
To create and view trace scopes and to get the default trace scope:
Cloud Trace User (
roles/cloudtrace.user) on your project -
To set the default trace scope:
Observability Editor (
roles/observability.editor) on your project
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 trace scopes, and to set the default trace 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 trace scopes, and to set the default trace scope:
-
To create and manage trace scopes:
cloudtrace.traceScopes.[create, delete, get, list, update] -
To set the default trace scope:
observability.scopes.[get, update]
You might also be able to get these permissions with custom roles or other predefined roles.
List trace scopes
To list the trace 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 Trace Scopes tab.
The table lists your trace scopes. When you've selected a Google Cloud project, one entry is shown with a "Default" icon,
,
which indicates that it is the default trace scope.
The Trace Explorer page searches the projects listed in the
default trace scope for trace data when the page opens.
Create a trace scope
The spans displayed by the Trace Explorer page depend on the searched projects, your IAM roles on those projects, the time-range setting, and the filters you apply.
You can create 100 trace scopes per project. A trace scope can include a total of 20 projects.
To create a trace 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 Trace Scopes tab and then click Create trace scope.
Click Add projects and complete the dialog.
When you add a project, spans stored in that project are included in the trace scope. If you don't know which projects to include in a scope, then you can use the legacy Trace Explorer page to help you identify them. For more information, see the Migrate to trace scopes section of this document.
In the Name trace scope section, enter the name and description that you want displayed on the Trace Scopes tab.
The name of a trace scope can't be modified and it must be unique within the project.
Click Create trace scope.
Migrate to trace scopes
The Trace Explorer page requires that you specify the Google Cloud projects to search for trace data, which is a change in behavior from the legacy Trace Explorer page. The legacy Trace Explorer page searches all projects in an organization. Due to these differences, the Trace Explorer page might not show spans that the legacy Trace Explorer pages shows.
You can use the Trace details pane section of the legacy Trace Explorer page to help you compile a list of Google Cloud projects that store your trace data:
Go to the legacy Trace Explorer page:
Select a trace.
You might try the following:
- Viewing a trace by entering its ID into the Trace ID field.
- Adding filters.
In the Trace details pane, select the trace and then go to the Projects tab.
This tab lists the projects that store spans for the trace.
To create a trace scope that contains the listed projects, to to the toolbar of the Projects tab and select Create scope with these projects, and then complete the dialog.
Repeat the previous steps until you've compiled a list of projects.
After you've compiled a list of projects, then create a trace scope. You might also set it as the default trace scope.
Set the default trace scope
When the Trace Explorer page opens, it searches the projects listed in the default trace scope for trace data. If that trace scope isn't accessible, then your project is searched for trace data.
When projects are created, the trace scope named _Default is created
and is designated as the default trace scope. However, you can create
your own trace scope and designate it as the default
trace scope.
To set the default trace 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 Trace Scopes tab.
Find the trace scope that you want to designate as the default trace scope, click its more_vert More, and then select Set as default.
The trace scope you selected is shown with a "Default" icon,
.
Modify or delete a trace scope
You can't delete or modify the
trace scope named _Default. You can modify or delete all other
trace scopes.
To modify or delete a trace 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 Trace Scopes tab.
Find the trace scope 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.
Limitations
There is no Cloud Trace API or Google Cloud CLI support for creating or managing trace scopes.
What's next
Cloud Logging and Cloud Monitoring contain similar constructs that let you control the log data or metric data that you can view or monitor. For information about those scopes, see the following documents: