This guide explains how to create and manage Workspaces. Your Google Cloud Platform (GCP) projects and Amazon Web Service (AWS) accounts must be members of a Workspace before they can be monitored.
For an introduction to Workspaces and some best practices for using them, see Workspaces.
The current Workspace is displayed to the right of the Stackdriver logo at the top of the Stackdriver Monitoring console. If you don't have a current Workspace, Select workspace is displayed.
To change the current Workspace or to find out details about a Workspace, go to the Manage workspaces page of the Stackdriver Monitoring console:
To select a Workspace for use in Stackdriver Monitoring, click the Workspace name in the list.
To go to the Workspace settings page for a Workspace, click Edit next to the Workspace name in the list.
Creating a single-project Workspace
This section describes how to create a Workspace for an existing GCP project. If you don't have a GCP project, you must create one prior to creating a Workspace. For instructions on creating a GCP project, go to Before you begin.
Create a Workspace from the GCP Console
To create a Workspace for an existing GCP project, do the following:
Go to the GCP Console:
In the menu bar, click the drop-down list next to the Google Cloud Platform and select your GCP project.
If the Add your project to a Workspace dialog is displayed, create a new Workspace by selecting your GCP project under New Workspace and then clicking Add. In the following image, the GCP project name is
The Add your project to a Workspace dialog is displayed only when you have at least one existing Workspace available to you. The Workspaces listed under Existing Workspace are Workspaces you've created or Workspaces for GCP projects where you have editorial permission. Using this dialog, you can choose between creating a new Workspace and adding your project to an existing Workspace.
Next, Monitoring creates a new Workspace and adds your GCP project to the Workspace. During Workspace creation, Monitoring proceeds through the following phases:
- Building your Workspace
- Enabling Stackdriver APIs
- We're still collecting data for your new Workspace
These phases might take several minutes to complete. When this process is complete, the Stackdriver Monitoring console displays the Monitoring Overview pane and a welcome message:
Create a Workspace from the Manage Workspaces page
To create a Workspace for an existing GCP project:
Go to the Manage workspaces page:
From this page, start the create Workspace process by doing one of the following:
- Click Add workspace.
- If Select workspace if it is displayed next to the Stackdriver logo, scroll to the bottom of the list, and then click Create workspace.
- Click the drop-down list next to the the Stackdriver logo, scroll to the bottom of the list, and then click Create workspace.
In the Google Cloud Platform project box, do one of the following:
- If your project is displayed, click Create workspace.
If Select project is displayed or if the wrong project is displayed, click the box, scroll to your project name, select it, and then click Create workspace.
If your project isn't listed, it might already have a Workspace. Click Cancel and then follow the instructions in Selecting Workspaces.
In the Add Google Cloud Platform projects to monitor dialog, click Continue.
In the Monitor AWS accounts dialog, click Skip AWS Setup.
Click Continue to skip the instructions for installing the Monitoring agent and the Logging agent on a Linux system. These instructions are available from the Agent option in the Workspace settings page.
Select an email-reporting option:
- Daily Reports, including weekly summaries
- Weekly reports
- No Report
You can change this setting in Workspace settings page in the Stackdriver Monitoring console after the Workspace is created. Your email reporting options are:
It takes several minutes for Monitoring to create your Workspace.
When creation is complete, Monitoring displays Finished initial collection!
Click Launch Monitoring.
You see the Monitoring home page for your new Workspace.
Converting from single-project to multi-project
You can convert a single-project Workspace into a multi-project Workspace by merging the single project Workspace into a second, empty Workspace.
Creating a multi-project Workspace
A single Workspace can monitor any number of GCP projects or AWS accounts. The best-practice recommendation to create a multi-project Workspace is as follows:
- Create a new GCP project. For instructions on creating a a new GCP project, go to Before you begin.
- Create a new Workspace for that project. For detailed steps, go to Creating a single-project Workspace.
- Add GCP projects or AWS accounts to the Workspace. For details, go to Adding monitored projects.
Adding users to a Workspace
You can share your Workspace with other users by adding them as members to your Workspace project. You must have Project > Owner permission for the project to add more users.
To add users to your Workspace, do the following:
In the Google Cloud Platform Console, go to the IAM & admin page:
From the list of projects, select your Workspace's host project.
At the top of the page, click Add.
In the New members box, enter a user, group, service account, or domain.
Assign a Project role to the new member: Owner, Editor, Viewer, or Browser. Click Save.
Adding monitored projects
This procedure covers adding a GCP project or an AWS account to an existing Workspace. To create a Workspace to which you can add projects and accounts, see Creating a multi-project Workspace.
To determine if you have sufficient privileges to add a GCP project or an AWS account to a Workspace, go to Workspace permissions.
To add a GCP project or an AWS account, do the following:
In the Stackdriver Monitoring console, go to the Manage workspaces page:
This page lists all the Workspaces to which you have access. Next to your Workspace, click Edit.
On the Workspace settings page for the Workspace, click Monitored accounts. You see your project information in a page similar to the following:
To add a GCP project, click Add Google Cloud Platform projects. Select the checkboxes for the names of any GCP projects you want to add to this Workspace. You don't have to select any projects.
To add an AWS account, click Add AWS account:
Follow the instructions for connecting your AWS account.
Click Add AWS account. Monitoring connects to your AWS account.
During the connection, Stackdriver Monitoring creates an AWS connector projector project.
Repeat these steps to add another AWS account.
Removing a project or account from a Workspace
Before taking action, consider if removing a project or account is the right action for your situation:
You cannot remove the host project from the Workspace by using the following procedure. Instead, use merge to change your host project to be a regular monitored project, and then use the following procedure to remove the project from the merged Workspace.
If you remove a GCP project from a Workspace, then you can add that project to another Workspace. However, if changing a projects Workspace is what you want to do, follow these instructions but select Move project instead of Remove from workspace. For more information on the impact of moving a project to a different Workspace, see Moving a project.
If you remove an AWS account from a Workspace, you are removing the AWS connector project, which represents the AWS account. You cannot use the AWS connector project with another Workspace. You must delete the connector project. You can then add your AWS account to another Workspace, letting Monitoring create a new connector project. See Adding an AWS account.
If you want to disable Monitoring for a GCP project, you can either disable the Stackdriver Monitoring API for your GCP project or modify your application to stop sending metric data to Stackdriver. For information on how to disable the Stackdriver Monitoring API for your GCP project, go to Disabling Monitoring.
When you remove a GCP project or account from its Workspace, Stackdriver Monitoring no longer receives monitoring data from the GCP project or the account. However, removal from a Workspace doesn't prevent the GCP project or the account from receiving monitoring data from Stackdriver agents or other software modules. If you use Stackdriver Logging, then you can continue to access logs in the removed project. For AWS, the logs are in the removed AWS connector project.
To remove a GCP project or an AWS account from a Workspace, do the following:
Open the Stackdriver Monitoring console:
In the menu bar, click the drop-down list next to Stackdriver logo, and select the Workspace that contains the GCP project or the AWS account you want to remove.
After you complete this step, your Workspace is displayed next to the Stackdriver logo.
To go to your Workspace settings, click the drop-down list next to the your Workspace name, and select Workspace settings.
On the Workspace settings pane, click Monitored accounts:
On the Monitored accounts page, locate the GCP project or AWS account you want to remove, click More more_vert and then select Remove from workspace.
In the previous image, there are two projects associated with the Workspace. The host project,
MY-GCP-PROJECT-NAME, can't be removed from the Workspace. However,
ANOTHER-PROJECTcan be removed from the Workspace.
Moving a project to another Workspace
When you move a GCP project to a different Workspace, you move the project and its metrics:
- Alerting policies and uptime checks aren't moved.
- Group definitions aren't moved but group membership might decrease in the Workspace losing the project and increase in the Workspace gaining the project.
- Dashboards and charts aren't moved. However, the content of the dashboards and charts might change in both Workspaces due to the movement of metrics.
To move a non-host GCP project from one Workspace to another, follow the instructions for Removing a project and choose the Move project action instead of the Remove from workspace action.
To move the host project from a Workspace, follow the instructions in Merging Workspaces.
To move an AWS account from one Workspace to another Workspace, do the following:
- Remove the AWS connector project from its Workspace. For details, see Removing a project.
- Delete the AWS connector project.
- Add your AWS account to the desired Workspace and let Monitoring create a new connector project.
Merging Workspace A into Workspace B moves all the GCP projects except AWS connector projects from Workspace A to Workspace B. Specifically, here is the effect of merging A into B:
All GCP projects that were added to Workspace A are moved into Workspace B. Metrics for the projects are also moved into Workspace B. However, dashboards, resource groups, uptime checks, notification channels, and alerting policies aren't moved into Workspace B.
In Workspace B, existing dashboards and charts might have more data, and groups might have more members. These changes are due to the inclusion of additional metrics and are dependent on your configuration choices. In addition, uptime checks and alerting policies might be impacted.
The project that hosts Workspace A is added to Workspace B, even if the project is empty.
The host project is the project you use to create the Workspace. This project typically has resources in the case of a single-project Workspace but is empty for a multi-project Workspace. Merging is the only way to separate this project from its Workspace.
After the merge completes, Workspace A isn't accessible.
To merge Workspaces, do the following:
Open the Monitoring console:
Select the Workspace that you want to keep ("B" in this scenario) from the drop-down list at the top-right of the Monitoring console.
Click the drop-down list next to your Workspace and select Workspace settings.
Click Monitored accounts from the left-side menu.
Click Merge another workspace into this one.
Select the Workspace that you want merged ("A" in this scenario).
Review the information that is lost during the merge, and if you agree to that information loss, select the checkbox. Click Merge.
Deleting a Workspace
Before deleting a Workspace, check if the project you used to create the Workspace has resources you want to preserve, or if the Workspace is still linked to additional GCP projects or AWS accounts. If so, see Merging Workspaces for a way to move resources to another place before deleting the Workspace.
If your Workspace project has no resources you want to preserve, then delete the Workspace by deleting the Workspace's project in the GCP Console:
Go to the IAM & admin console:
Click Shut Down.
Restricting access to AWS accounts
To limit the AWS account permissions you give to Monitoring, see Minimal AWS permissions.
To revoke Monitoring's access to your AWS account,
Stackdriver IAM role from your AWS account.
Workspaces don't have any costs associated with them. All chargeable activity is recorded in GCP projects containing your resources—that is, in the billing accounts associated with those projects. Some details of GCP and AWS billing are described in the following sections.
Removing a project from its Workspace doesn't necessarily stop all Stackdriver charges for logs and metrics usage. If any Stackdriver agents or other software modules continue to send metrics or logs to Stackdriver, then charges continue to accrue. For information on how to disable the Stackdriver Monitoring API for your GCP project, go to Disabling Monitoring.
GCP project billing
When you create a resource in a GCP project, GCP begins to receive metrics and log entries from GCP services regarding that resource. Charges begin to accrue to your project's billing account right away, but much of the data isn't chargeable or has such low volume that it doesn't trigger any charges.
Stackdriver Logging has access to all your GCP project's logs even without creating a Workspace. Adding your project to a Workspace gives Stackdriver Monitoring access to the monitoring data already being received, but the Workspace doesn't itself trigger any additional charges. Similarly, removing a project from a Workspace doesn't stop charges.
If you have VM instances in your GCP project that contain software that sends monitoring data or logs to Stackdriver APIs, then you will be charged for that data as long as the software is running. This includes the Monitoring agents, Logging agents, and third party libraries like Prometheus that you might install. To stop charges, you must stop any software sending data to Stackdriver.
AWS account billing
When you add an AWS account to a Workspace, monitoring and logging data is sent by Stackdriver agents or other software to the AWS connector project, whose billing account receives any charges.
Much of the data sent from an AWS account comes from software agents running on VM instances and sending data to the AWS connector project created when you added your account to a Workspace. You are charged for that data as long as the software is sending data and the connector project still exists, regardless whether it remains connected to a Workspace.
If you want to disable Monitoring for a GCP project, you can either disable the Stackdriver Monitoring API for your GCP project or modify your application to stop sending metric data to Stackdriver. Removing a project from its Workspace doesn't prevent the ingestion of metric data into the GCP project. Instead, it removes your ability to view and manage the metric data using the Stackdriver Monitoring console.
To disable the collection of Monitoring data in your GCP project:
From the GCP Console, go to APIs & Services.
Select Stackdriver Monitoring API.
Click Disable API.
I can't log in to my Workspace
Stackdriver Monitoring relies on cookies from various Google sites to manage Workspaces. If these cookies are blocked, you may find that you:
Cannot get past the Log in with Google dialog, and you see a message saying “Cookies aren't enabled in current environment”.
Get stuck in an endless authentication loop.
Cookies can be blocked accidentally, or by automatic updates pushed out as part of changes in security policy at your location.
You must have third-party cookies enabled for the following:
For information on enabling cookies, see your browser's documentation:
My email address isn't accepted
Monitoring doesn't accept email addresses containing an apostrophe, although Google Cloud Platform does. Users with such email addresses are unrecognized when they attempt to use Monitoring.
I can't add a project to a Workspace because it's already in another Workspace
Projects can be associated with only one Workspace at a time:
- You can move monitored projects to another Workspace.
- You can move a Workspace's host project by merging Workspaces.
- You cannot move AWS accounts. You must remove the AWS account from its current Workspace and add it to a new Workspace, going through the AWS authorization process again. For more information, go to Removing a project from a Workspace.
Project resources are missing from Monitoring
It can take ten minutes or so before Monitoring notices new or removed resources, such as VM instances, in your projects.
If you start a service such as Compute Engine in a project that is associated with a Workspace, it can take a hour or more for Monitoring to notice the new service. Until that time, the service's resource types don't appear in any Monitoring menus.
How do I use Workspaces with Logging?
Stackdriver Logging doesn't use Workspaces. By using advanced log filters, you can view or manage log entries from multiple GCP projects or AWS accounts.
In the case of AWS accounts, you access logs through the AWS connector project that Monitoring creates when you add the account to a Workspace. Therefore, you do have to add your account to a Workspace and install the Stackdriver Logging agent on your VM instances in order to receive your logs.