View metrics for multiple projects

This page describes how to configure a metrics scope to access and monitor the metrics stored in multiple Google Cloud projects. This page is intended for developers and system administrators who need to manage metrics for services and resources that are associated with different projects.

Before you begin

  • If you aren't familiar with the terms metrics scope and scoping project, then see metrics scopes.

  • Ensure that your Identity and Access Management (IAM) role on the scoping project lets you modify the project's metrics scope. For information about the required IAM roles, see Metrics scope configurations.

  • For each project that you want to add as a monitored project, ensure that your IAM role lets you modify the project's metrics scope. For information about the required IAM roles, see Metrics scope configurations.

  • If you use VPC Service controls, then you need to consider the order in which you create your multi-project metrics scope and your VPC perimeters. Cloud Monitoring performs the VPC perimeter check when a project is added to a metrics scope:

    • When you create the VPC perimeter first and then try to add a project to the metrics scope, the perimeter validation process runs. This process verifies that the added project is in the same perimeter as the scoping project, or that it is connected to the scoping project by a perimeter bridge. If the perimeter validation fails, then the addition of the project to the metrics scope also fails.

    • When you create your multi-project metrics scope first and then create your perimeters, the perimeter validation process doesn't run. This approach lets you access metrics for projects that are in different perimeters.

  • If you configure IAM roles or grant access to projects, then you must consider the implications of permissions on a project that is a scoping project for a multi-project metrics scope. If you grant a user a role on a project, then that lets them read Monitoring data, then that user can view all metrics accessible to the metrics scope for that project. For example, if the Staging project monitors the Production project, then a user who can view the metrics of the Staging project can also view the metrics of the Production project.

  • If you want to view metrics for your Amazon Elastic Compute Cloud (Amazon EC2) instances, see View metrics for an AWS account.

Create a multi-project metrics scope

To manage the metrics for multiple projects, add those projects to a metrics scope. When you create a metrics scope that has access to metrics for multiple projects, then charts, for example, display metrics for all projects.

When you want to manage metrics for multiple projects, we recommend that you create a project to be the scoping project for that metrics scope. We also recommend that you don't create any resources in that scoping project. These recommendations ensure that your scoping project doesn't generate metrics, which are combined with the metrics of the other projects in the same metrics scope.

For the metrics of a project to be accessible in a metrics scope, that project must either be the scoping project or a monitored project of the metrics scope. If a project isn't explicitly listed as being in-scope, then its metrics aren't accessible.

Use a new project (recommended)

To use a new project to create a multi-project metrics scope, do the following:

  1. In the Google Cloud Console, create a Google Cloud project:

    Go to Cloud Console

    We recommend that you define a naming convention for projects that are scoping projects for multi-project metrics scopes.

    Don't use this project for any purpose other than as the scoping project for your multi-project metrics scopes. Because this project is new, it doesn't contain any resources, such as virtual machine (VM) instances, that generate metrics.

  2. Select your new project with the Cloud Console project picker.

  3. In the Cloud Console navigation pane, select Monitoring, and then select Settings.

  4. Click Add GCP Projects, and then select the projects whose metrics you want to access from this metrics scope.

  5. Click Add projects.

    After you add projects to a metrics scope, it takes about 60 seconds for changes to propagate through all Monitoring systems. If after 60 seconds, the metrics for the added projects aren't available to you when you create a chart or an alerting policy, then refresh the Google Cloud Console page.

For example, assume that you have two projects that contain Compute Engine VM instances, Staging and Production. Assume that both of these projects are only monitoring their own project data; that is, their metrics scopes don't include any monitored projects. You want to configure alerts for the VMs of each project individually, and you want to view dashboards that display metrics for both projects.

You follow the approach listed in this section and create the project AllEnvironments, and then you add the projects Staging and Production as monitored projects:

  • If you select AllEnvironments and then go to Monitoring, then you access the multi-project metrics scope, which includes the metrics for all three projects:

    List of projects in the metrics scope of the `AllEnvironments` project.

    The AllEnvironments project doesn't have any resources so it doesn't contain any metrics. Therefore, when you create a chart, you only see the metrics from the projects Staging and Production:

  • If you select the Staging (Production) project and then go to Monitoring, then you access the metrics scope for the Staging (Production) project. The following screenshot shows that the metrics scope for project Staging (Production) is only that project:

    List of projects in the metrics scope of the `Staging` project.

    The previous screenshot also shows that the metrics for the Staging project are accessible to the AllEnvironments project.

You've met your objectives with this configuration. When you select the Staging (or Production) project, you access only the metrics from that project. When you select the AllEnvironments project, you have access to the metrics for all projects. However, the AllEnvironments project doesn't contain resources so it doesn't generate metrics.

Use an existing project

To add the Production project to the metrics scope of the Staging project, do the following:

  1. In the Google Cloud Console, select Monitoring:

    Go to Monitoring

  2. Select Staging with the Cloud Console project picker.

  3. In the Monitoring navigation pane, select Settings.

  4. In the Google Cloud projects pane, click Add GCP Projects, and then select Production.

  5. If prompted to select a scoping project, then select the option Use this project as the Scoping project:

    Options for configuring a metrics scope.

    The previous dialog is shown when the scoping project, that is, the project selected by the Cloud Console project picker, contains at least one resource. The dialog provides you with options to create a new scoping project or to continue with the existing scoping project.

  6. Click Add Projects.

    After you add projects to a metrics scope, it takes about 60 seconds for changes to propagate through all Monitoring systems. If after 60 seconds, the metrics for the added projects aren't available to you when you create a chart or an alerting policy, then refresh the Google Cloud Console page.

Consider the previous example where the projects Staging and Production contain Compute Engine VM instances. Initially, assume both of these projects are only monitoring their own project data; that is, their metrics scopes don't include any monitored projects. As before, you want to configure alerts for the VMs of each project individually, and you want to view dashboards that display metrics for both projects.

If you follow the procedure in this section, then you modify the metrics scope for the Staging project to include the metrics of the Production project:

  • When you select the Staging project and then go to Monitoring, you access the multi-project metrics scope that includes the metrics for both projects. The following screenshot shows that the metrics scope for the Staging project includes the Staging and Production projects:

    Screenshot that shows the metrics scopes for the `Staging` project which includes the metrics for the `Production` project.

  • When you select theProduction project and then go to the Monitoring page, you access the metrics scope for the Production project. Because this project doesn't contain any monitored projects, you can only access the metrics for that project. The following screenshot shows that the metrics scope for project Production is only that project:

    Screenshot that shows the metrics scope of the `Production` project.

    The previous screenshot also shows that the metrics for the Production project are accessible to the Staging project.

When you add a project to a metrics scope, then that metrics scope lets you monitor the data for the scoping project and the monitored project. From that metrics scope, you can't easily access only the metrics for the scoping project or for the monitored project. Instead, you access the combined metrics of both projects.

When a scoping project contains its own metrics, you must use filters to separate the metrics of the scoping project from the metrics of the monitored projects. For example, you must use filters if you want to create an alerting policy that only monitors the VM instances of the Staging project. When the scoping project doesn't contain any metrics, for example when this project is new, then you can use the metrics scopes of the monitored projects to view only their metrics.

Add projects to a metrics scope

To add projects as monitored projects to a metrics scope, do the following:

  1. In the Google Cloud Console, select Monitoring:

    Go to Monitoring

  2. Ensure the project whose metrics scope you want to modify is selected.

  3. In the Cloud Monitoring navigation pane, select Settings.

  4. Click Add GCP Projects and then select the projects that you want to add.

  5. Click Add projects.

You can also add monitored projects from the Metrics scope page. To access this page, in the Cloud Monitoring navigation pane, click Expand in the Metrics scope field.

Remove projects from a metrics scope

If you remove a project from a metrics scope, then the metrics stored in that project aren't accessible to the metrics scope. Removing a project from a metrics scope doesn't change the configuration of charts, dashboards, alerting policies, uptime checks, or groups that you defined. However, the time series displayed on charts and the time series monitored by alerting policies might change.

To remove projects from a current metrics scope, do the following:

  1. In the Google Cloud Console, select Monitoring:

    Go to Monitoring

  2. Ensure the project whose metrics scope you want to modify is selected.

  3. In the Monitoring navigation pane, select Settings.

  4. In the GCP Projects in scope pane, select the projects that you want to remove and click Remove project.

What's next