This document describes how you can create charts or view log data when thatdata is stored in multiple projects. By default, only the data that originatesin a project is available to the visualization tools. However, if you configurea scope, then visualization and analysis tools can query data that is stored inmultiple projects.

If you only want to monitor or view data that is stored in oneGoogle Cloud project, then you don't need to perform any configuration.

Scopes provide read-time aggregation

Scopes let visualization and analysis tools perform read-time aggregation ofdata that is stored in multiple locations. Scopes don't control where data isstored. Instead, query engines rely on scopes to determine where to searchfor data.

Metric and trace data is always stored in the Google Cloud project where thedata originates. To view metric data that is stored in multiple projects on asingle chart, configure a metrics scope to list those projects. After youconfigure this scope, when you create a chart or alerting policy, the queryissued by these services automatically returns metric data from the listedprojects. The behavior is similar for trace data.

By default, log data is stored in the Google Cloud project, billing account,folder, or organization where the data originates. However, you can configureLogging to route log data from the resource where it originatesto another location, like another project or a centralized log bucket.In all cases, configure a custom log scope. We recommend that yourlog scope listslog views instead of projects;alog view provides read-access to a subset of log entries in a log bucket.For example, if you havelog data stored in three projects, then you might configure the log view toinclude the_Default/_AllLogs view for each of those projects.

How scopes are used by Google Cloud Observability

Google Cloud Observability analysis and visualization tools rely on data-type specificscopes to determine what resources to query for the data that the tool isto display or analyze.

Examples:

• When theLogs Explorer page opens, the system queries the resourceslisted in the default log scope for log data. After this page isopen, you can use a toolbar option to query the resources in a differentscope.
• When theTrace Explorer page opens, the system queries theprojectslisted in the default trace scope for trace data. After this pageis open, you can use a toolbar option to query the resources in a differentscope.
• When you create an alerting policy, Monitoring queries theprojects listed in the metrics scope for metric data. It then analyzesthe query response and determines whether to create an incident.
• When you create a chart by using theMetrics Explorer page,you specify a metric to chart. Monitoring queries theprojects listed in the metrics scope for metric data, and then displaysthe query results.

Logging and Trace verify yourIdentity and Access Management (IAM) roles on a resource before a query returns data.For example, if a log scope specifies a project for which you haven'tbeen given the permissions to read log data, then a query to that projectdoesn't return data.

Monitoring verifies your IAM role on theproject from which the query is issued. Suppose the metrics scope for aproject namedAllEnv lists the following projects:AllEnv,Prod, andStaging. Also, assume that you've been granted the Monitoring Viewer roleon theAllEnv project. Charts you create with theMetrics Explorer page when using theAllEnv projectautomatically display metric data for the three projects.

Google Cloud Observability scopes

This section describes the scopes used by Google Cloud Observability.

Observability scope

The observability scope specifies the default log scope and thedefault trace scope. Pages like theLogs Explorer andTrace Explorer use the default scopes to determine what resourcesto query, when the page opens.For example, suppose you have an application that generates trace data inthree projects. You can configure theTrace Explorer page toautomatically query those three projects by setting thedefault trace scope.

If you don't configure the observability scope, then the following occur:

• TheLogs Explorer page queries your project for log data.
• TheTrace Explorer page queries your project for trace data.

The observability scope doesn't apply to metric data.

When to configure the observability scope

Configure the observability scope in the following scenarios:

• You create a custom log scope and you want the resources listedin that scope queried by default.

• You create a custom trace scope and you want the projects listedin that scope queried by default.

Limits associated with observability scopes

Log scopes

Log scopes are used by theLogs Explorer page and bydashboards that display log data:

• When theLogs Explorer page opens, the system automaticallyqueries the resources listed in the default log scope for log data.This page also provides controls that let you switch between scopes.

• For dashboards, the implementation determines whether the system queriesthe project or the resources listed in the default log scope.

A log scope can listlog views, projects, folders,and organizations.

If you don't configure a custom log scope, then theLogs Explorer page queries your project for log data.

When to create custom log scopes

Create custom log scopes for the following configurations:

• You route log data to acentralized log bucket.
• You store log data in multiple projects.
• You are usingApplication Monitoring, which is a service that generatesdashboards for yourApp Hub applications.

In all cases, configure your custom log scopes to list one or morelog views. Those log views might be on a centralized log bucket, or theymight be log views on different log buckets. If you use a centralizedlog bucket, then you might create multiple custom log scopes, each withtheir own set of log views.

If you create a custom log scopes, then consider updating thedefault log scope.

Best practices when configuring log scopes

• Include only log views.
• Don't configure a scope that lists both projects and log views.

Limits associated with log scopes

For more information, seeCreate and manage log scopes.

Metrics scope

The metrics scope is used by all queries issued by Cloud Monitoring.For example, alerting policies and charting tools like like theMetrics Explorer issue queries to the projects listed in themetrics scope.

If you don't configure the metrics scope, then Monitoringservices query your project for metric data.

When to configure the metrics scopes

Configure the metrics scope when any of the following are true:

• You want to chart data stored in different projects.
• You want an alerting policy to monitor data stored in different projects.
• You register applications withApp Hub. For informationabout this scenario, seeApp Hub applications and metrics scopes.

Limits associated with metrics scopes

For more information, seeMetrics scopes overview.

Trace scopes

Trace scopes are used by theTrace Explorer page.When this page opens, the system automatically queries the projects listedin the default trace scope for trace data.This page also provides controls that let you switch between scopes.

If you don't configure a custom trace scope, then theTrace Explorer page queries your project for trace data.

When to create custom trace scopes

Create custom trace scopes when you have applicationsthat rely on resources in different Google Cloud projects.

Best practices when configuring trace scopes

Limits associated with trace scopes

For more information, seeCreate and manage trace scopes.

Configure the observability scope

This section doesn't apply to folders or organizations.

For log and trace data, your Identity and Access Management (IAM) roles on thethe project you are viewing, and any searched projects and log views, affectwhat data is returned by the query. If you issue a query to view log data thatyou don't have permission to view, then the query doesn't return any log data.

For metric data, when a project's metrics scope is configured, the projectis granted read-access to the metric data stored by the projects listed inits metrics scope. When a user is granted an Identity and Access Management role that letsthem view metric data in a project, they can view metric data available to theproject.

To configure the observability scope, you set the default log scopeand the default trace scope. The remainder of this section describeshow to complete these actions.

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

1. 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 and set default scopes:Observability Scopes Editor (roles/observability.scopesEditor) on your project

   For more information about granting roles, seeManage access to projects, folders, and organizations.

   You might also be able to get the required permissions throughcustom roles or otherpredefined 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, aCloud 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:

   gcloudinit

   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, seeAuthenticate for using REST in the Google Cloud authentication documentation.

View and set the default scope

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

Learn more about scopes

For more information about scopes, see the following documents:

• Create and manage log scopes.
• Metrics scopes overview.
• Create and manage trace scopes.