Create and manage trace scopes

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.

This feature is supported only for Google Cloud projects. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.

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.

App Hub applications and trace scopes

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Your App Hub applications might write trace data to multiple projects. To get an aggregate view of this data, create a trace scope, configure it to list all projects that store your trace data, and then configure it as the default trace scope. When you complete those steps, the Trace Explorer page automatically displays the data written by your application, even when that data is stored in different projects.

Create the custom trace scope in the project from which you will view your log data. This project is either your App Hub host project or the management project of your app-enabled folder. For example, if the folder's display name is My Folder, then the management project's display name is My Folder-mp.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Enable the API

1. To get the permissions that you need to create and view trace scopes, ask your administrator to grant you the Observability Scopes Editor (roles/observability.scopesEditor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

   You might also be able to get the required permissions through custom roles or other predefined roles.

   The Observability Scopes Editor role includes private permissions that let you create and view trace scopes. These permissions aren't available for inclusion in custom IAM roles.

2. Select the tab for how you plan to use the samples on this page:

   Console

   When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

   gcloud

   In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   REST

   To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

   Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

   gcloud init

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

   For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

List trace scopes

Console

To list the trace scopes, do the following:

1. In the Google Cloud console, go to the  Settings page:

   Go to Settings

   If you use the search bar to find this page, then select the result whose subheading is Monitoring.

2. In the toolbar of the Google Cloud console, select your Google Cloud project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.

3. 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.

gcloud

Not supported.

REST

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To list all trace scopes in a Google Cloud project, use the projects.locations.traceScopes.list command. You must specify a path parameter.

The path parameter for this endpoint has the following syntax:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

The fields in the previous expression have the following meaning:

• PROJECT_ID: The identifier of the project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
• LOCATION_ID must be set to global.

The response is an array of TraceScope objects. Each object includes a name and a list of resources.

To get information about a specific trace scope, use the projects.locations.traceScopes.get command.

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.

Console

To create a trace scope, do the following:

1. In the Google Cloud console, go to the  Settings page:

   Go to Settings

   If you use the search bar to find this page, then select the result whose subheading is Monitoring.

2. In the toolbar of the Google Cloud console, select your Google Cloud project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
3. Select the Trace Scopes tab and then click Create trace scope.

4. Click Add projects and complete the dialog.

   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.

5. 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.

6. Click Create trace scope.

gcloud

Not supported.

REST

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To create a trace scope, use the projects.locations.traceScopes.create command. You must specify a path parameter and provide a TraceScope object. The response is a TraceScope object.

The path parameter for this endpoint has the following syntax:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

The fields in the previous expression have the following meaning:

• PROJECT_ID: The identifier of the project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
• LOCATION_ID must be set to global.

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:

1. Go to the legacy Trace Explorer page:

   Go to Legacy Trace explorer

2. In the toolbar of the Google Cloud console, select your Google Cloud project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.

3. Select a trace.

   You might try the following:

   • Viewing a trace by entering its ID into the Trace ID field.
   • Adding filters.

4. 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.

5. 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.

6. 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.

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.

Console

To modify or delete a trace scope, do the following:

1. In the Google Cloud console, go to the  Settings page:

   Go to Settings

   If you use the search bar to find this page, then select the result whose subheading is Monitoring.

2. In the toolbar of the Google Cloud console, select your Google Cloud project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
3. Select the Trace Scopes tab.

4. Find the trace scope that you want to modify or delete, click  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.

gcloud

Not supported.

REST

Modify a scope

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To modify a trace scope, use the projects.locations.traceScopes.patch command. You must specify a path parameter, query parameters, and provide a TraceScope object. The query parameters identify which fields are changed. The response is a TraceScope object.

The path parameter for this endpoint has the following syntax:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

The fields in the previous expression have the following meaning:

• PROJECT_ID: The identifier of the project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
• LOCATION_ID must be set to global.
• TRACE_SCOPE_NAME: The name of a trace scope. For example, my-trace-scope.

Delete a scope

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To delete a trace scope, use the projects.locations.traceScopes.delete command. You must specify a path parameter.

The path parameter for this endpoint has the following syntax:

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

The fields in the previous expression have the following meaning:

• PROJECT_ID: The identifier of the project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
• LOCATION_ID must be set to global.
• TRACE_SCOPE_NAME: The name of a trace scope. For example, my-trace-scope.

Configure 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.

Console

To set the default trace scope, do the following:

1. In the Google Cloud console, go to the  Settings page:

   Go to Settings

   If you use the search bar to find this page, then select the result whose subheading is Monitoring.

2. In the toolbar of the Google Cloud console, select your Google Cloud project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.

3. Select the Trace Scopes tab.

   The tab displays your trace scopes and it includes a button to create a custom trace scope. The trace scope that is shown with a "Default" icon, , is the current default trace scope.

4. To change the default trace scope, find the trace scope that you want to designate as the default trace scope, click its  More, and then select Set as default.

   The trace scope you selected is shown with a "Default" icon, .

gcloud

Not supported.

REST

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To get and set the default log scope or the default trace scope by using an API call, you configure the observability scope. The observability scope lists the default log scope and the default trace scope:

• To get the default observability scope for a project, send a request to the projects.locations.scopes.get endpoint. You must specify a path parameter. The response is a Scope object, which lists the default log scope and the default trace scope.

• To update the default observability scope for a project, send a request to the projects.locations.scopes.patch endpoint. You must specify a path parameter, query parameters, and provide a Scope object. The query parameters identify which fields are changed. The response is a Scope object.

The path parameter for both endpoints has the following form:

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

The fields in the previous expression have the following meaning:

• PROJECT_ID: The identifier of the project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
• LOCATION: The location field must be set to global.
• OBSERVABILITY_SCOPE_ID: The name of a Scope object. This field must be set to _Default. The Scope object with the name _Default, which is created automatically, stores information about the default log scope and the default trace scope.

To send a command to an API endpoint, you can use the APIs Explorer, which lets you issue a command from a reference page. For example, to get the current default scope, you can do the following:

1. Click projects.locations.scopes.get.

2. In the Try this method widget, enter the following in the name field:

   projects/PROJECT_ID/locations/global/scopes/_Default
   

   Before you copy the previous field, replace PROJECT_ID with the name of your project.

3. Select Execute.

4. In the authorization dialog, complete the required steps.

   The response is similar to the following:

   {
   "name": "projects/my-project/locations/global/scopes/_Default",
   "logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
   "traceScope": "projects/my-project/locations/global/traceScopes/_Default"
   }
   

Limits on trace scopes

Limits on trace scopes	Value
Maximum number of trace scopes per project	100
Maximum number of projects per trace scope	20

What's next

• Find and explore traces

• 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:

  • Observability scopes overview
  • Create and manage log scopes
  • Metrics scopes overview