Observability scopes overview

This document describes how you can configure one Google Cloud project to monitor or display telemetry data from multiple Google Cloud projects. If you only want to monitor or view data that is stored in one Google Cloud project, then you don't need to perform any configuration, as the visualization and analysis tools are configured to use the data stored in the Google Cloud project selected by the project picker. However, if the telemetry data that you want to view or analyze is from multiple projects, then to have an aggregated view of that data, you must perform some configuration activities.

About observability scopes

The Google Cloud Observability analysis and visualization tools rely on data-type specific scopes to determine what data to display or analyze. You can configure the following scopes:

Observability scope

This is a wrapper which implicitly refers to the metrics scope. It also explicitly lists the default log scope and the default trace scope for a project. The default scopes are used by the respective explorer pages to determine which resources to search for data. You modify this scope by setting the default log scope and the default trace scope.

We recommend that you configure the observability scope in the following scenarios:

You register applications with App Hub. These might be applications you register yourself, or those you deployed by using the Application Design Center.
When you want a unified view of the telemetry data that is stored in different Google Cloud projects.

Log scopes

Lists projects, folders, organizations, and log views that store log data.

You can set one log scope as a default log scope. The Logs Explorer page automatically queries the resources listed in the default log scope when the page opens. After the page is open, you can also select a different log scope, which causes the page to search the resources listed in the selected scope, and then refresh the display.

We recommend that you configure the default log scope in the following scenarios:

You route log data to a centralized log bucket.
You route log data to other projects or to log buckets stored by another project.
You use log views for access management.

For more information, see Create and manage log scopes.

Metrics scope

Lists the Google Cloud projects whose metric data can be read by the current Google Cloud project.

Each Google Cloud project contains a single metrics scope. Charts, dashboards, and alerting policies query for metric data stored in all projects listed in the metrics scope. By default, the metrics scope for a project only lists the project.

We recommend that you configure the metrics scope when any of the following is true:

You want to chart data stored in different projects.
You want an alerting policy to monitor data stored in different projects.

For more information, see Metrics scopes overview.

Trace scopes

Lists the projects that store trace data.

You can set one trace scope as a default trace scope. The Trace Explorer page automatically queries the resources listed in the default trace scope when the page opens. After the page is open, you can also select a different trace scope, which causes the page to search the projects listed in the selected scope, and then refresh the display.

We recommend that you configure the trace scopes when you want a unified view of the trace data that is stored in different projects.

For more information, see Create and manage trace scopes.

A scope defines the resources that are searched for a particular type of data. Your Identity and Access Management (IAM) roles on those resources determine what data is returned. For example, a log scope, which defines the resources that are searched for log data, doesn't affect the data shown on charts or the data shown by the Trace Explorer page. Further, if a log scope lists a log view for which you don't have access, then you won't see any log entries from that log view.

Configure the observability scope

This section doesn't apply to folders or organizations.

When a project is created, an observability scope is created. This scope lists the following scopes:

The metrics scope, which lists only the current project.
The default log scope, which is set to the log scope named _Default.
The default trace scope, which is set to the trace scope named _Default.

The scopes named _Default list only the project and can't be modified.

If you don't modify the observability scope, then when you navigate to the explorer pages, only data that originates in your selected project is shown. For all data types, the retrieved data is filtered by time-range setting and your IAM roles on the searched resources.

Set or view default scopes

Make sure you have the required permissions. For more information, see the Roles and permissions section of this document.

Console

To view or set the default log scope or the default trace scope in your Google Cloud project, do the following:

Enable the Observability API.
Enable the API

Before you enable the API, ensure that the correct project is selected.
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.

The Settings page contains several tabs. Each tab displays the scope configuration for a particular telemetry type.
Select the Log Scopes tab or the Trace Scopes tab.

The selected tab displays a list of predefined and custom scopes for the data type specified by the tab. The entry with the "Default" icon, , is the default scope.
To change the default scope, in the table, find the entry that you want to designate as the default, click More, and then select Set as default.

REST

Not supported for setting the default trace scope.

To use the Observability API to get or set the default log scope, do the following:

Ensure that the Observability API is enabled:
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
2. Set the default project for Google Cloud CLI:
```
gcloud config set project PROJECT_ID
```
  Before you run the previous command, replace the following:
  - PROJECT_ID: The identifier of the project.
3. Enable the Observability API:
```
gcloud services enable observability.googleapis.com
```
Do one of the following:
- To get the default log 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.
- To update the default log 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.
  - 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 stores information about the default log scope and is automatically created.

Roles and permissions

To get the permissions that you need to create and view scopes, ask your administrator to grant you the following IAM roles:

To create and view log scopes and to get the default log scope: Logs Configuration Writer (roles/logging.configWriter) on your project
To modify a metrics scopes: Monitoring Admin (roles/monitoring.admin) on your project and on each project you want to add to the metrics scopes
To create and view trace scopes and to get the default trace scope: Cloud Trace User (roles/cloudtrace.user) on your project
To get and set default scopes: 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 scopes. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create and view scopes:

To configure log scopes: logging.logScopes.{create, delete, get, list, update}
To configure a metrics scope: monitoring.metricsscopes.{link, get, list}
To configure trace scopes: cloudtrace.traceScopes.{create, delete, get, list, update}
To get and set default scopes: observability.scopes.{get, update}

You might also be able to get these permissions with custom roles or other predefined roles.