Cloud Monitoring collects metrics for your APIs and service and of the
Google Cloud resources that you use. This document describes how to configure
Cloud Monitoring and how to use it to monitor API usage, create dashboards,
and create alerts.

Cloud Monitoring has a large set of features and options. This document
introduces Cloud Monitoring and provides basic examples. For information on
all the features, including many more examples, see the [Cloud Monitoring](https://cloud.google.com/monitoring/docs/monitoring-overview)
documentation.

## Configure Cloud Monitoring

Monitoring lets you view and manage the metrics:

- For a single project
- For multiple projects within a single organization
- For multiple projects across multiple organizations

To ensure that the metrics for your projects are available, do the
following:

1. In the Google Cloud console, select **Monitoring** :

   [Go to Monitoring](https://console.cloud.google.com/monitoring)
2. Ensure that you have selected the correct project.
3. In the Monitoring navigation pane, click **\>** to the right of **Metrics Scope** . The following screenshot shows the page that is displayed when the AllEnvironments project is selected:

   ![Screenshot of the metrics monitored for the project. Each project,
   along with its project ID and role is listed.](https://cloud.google.com/monitoring/images/settings-metrics-scope-project-multiview.png)

The table labeled **Metrics monitored by this project** lists the projects whose metrics are
accessible to the current metrics scope. Each row in the table lists a project
and that project's role:

- **Scoping project**: This project stores the uptime checks, alerting policies, groups, and dashboards that you configure. There is a 1:1 relationship between a metrics scope and a scoping project. For this example, the AllEnvironments project is the scoping project.
- **Monitored project**: The metrics for the project are visible to the current metrics scope. For this example, the Staging and Production projects are monitored projects.

The table labeled**The projects listed below can view this
project's metrics** lists the projects whose metrics scope includes the
current project. The previous screenshot shows that no other projects can access
the metrics stored by the AllEnvironments project.

For more information, including how to add and remove projects, see [Configure Cloud Monitoring](https://cloud.google.com/monitoring/settings).

## Explore metrics

To explore metric data, build a chart by using the *Metrics Explorer*which is included with Cloud Monitoring. For example, if you want to
view the quota usage of an API, you can use the Metrics Explorer to
construct a chart that displays the most recent data.

The following image shows a chart detailing quota usage for Maps APIs:

![Screenshot of the Quota metrics data for all Maps API. It shows a bar chart
where each segment of hte bar corresponds to a different API.](https://developers.google.com/static/maps/reporting-and-monitoring/images/gmp-mon-quota.png)

This example shows a stacked bar chart where each API is represented by a
section of the bar. You can create different chart types, such as line charts,
bar charts, and heat maps. You can also create a single chart that displays up
to 10 different metrics.

In this image:

- The **Resource Type** and **Metric** fields to the left of the chart define the metric data displayed in the chart.
- The chart type drop-down above the chart lets you select the chart type. In this example, it is set to **Stacked bar chart**.
- The time interval above the chart is set to **1W** (one week).
- Below the chart is the list of **service** , **quota_metrics** , API **method** , and metric **value** that define the chart's data. Select **Add
  Filter** to use this information to refine the displayed data.

When you navigate away from the Metrics Explorer page, the chart is
discarded so you don't have any unwanted artifacts to delete. Alternatively, you
can save the chart to a custom dashboard, or share it. See
[Create dashboards](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#create-dashboards) below for more
information on adding a chart to a dashboard.

### Chart a single metric

To configure a chart by using Metrics Explorer, do the following:

1. In the Cloud console, select **Monitoring** :

   [Go to Monitoring](https://console.cloud.google.com/monitoring)
2. In the navigation pane, select **Metrics explorer**.
3. In the toolbar, select **Stacked bar chart** from the chart type drop-down to view the metrics data as a bar chart.
4. Select a time interval, such as **1W** (one week).
5. Specify the data to appear on the chart. To use a menu-driven interface or to enter a filter, select the **Configuration** tab. To use the Monitoring Query Language (MQL), select the **MQL** tab.

> [!NOTE]
> **Note:** MQL provides an expressive, text-based interface to Cloud Monitoring time-series data. The examples in this document all use the Cloud console. See [Introduction to Monitoring Query Language](https://cloud.google.com/monitoring/mql) for more information.

   1. To chart quota usage, select **Consumer Quota** as the **Resource type** . Alternatively, if you wanted to create a chart for API usage, select **Consumed API** or **Google Maps API** (see [Usage metrics](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-usage-metrics) section for more details on usage metrics available for Google Maps Platform APIs). Hover over each resource type to see its description.
   2. For the **metric** , select **Rate quota usage** . The chart automatically updates to display metric data.

      > [!NOTE]
      > **Note:**If no data appears in the chart, either extend the time interval or exit and make several API requests to generate metrics data.

      Notice that there are other quota options for the metric. Hover over each metric to see a description. For more information about Metrics Explorer fields, see [Selecting metrics](https://cloud.google.com/monitoring/charts/metrics-selector) and [Choosing how to display charted data](https://cloud.google.com/monitoring/charts/metrics-selector#select_display).
6. **(Optional)** Use the following options to refine the display:
   1. To specify a subset of data to display, add *filters* . To add a filter, select **Add filter** and complete the dialog. For more information, see [Filter charted data](https://cloud.google.com/monitoring/charts/metrics-selector#filter-option). For example, to view data for a single API:
      1. In the **Label** field select **method**.
      2. In the **Comparison** field select **= (equals)**.
      3. In the **Value** field select the name of a specific method. You will be prompted to select the name of a method with data to display.
      4. Select **Done**to update the chart.
   2. To group time series by a label, use the **Group by** field. Selecting a value for this field automatically selects a value for the **Aggregator** field.
   3. To specify how to combine time series, set the **Aggregator** field. For example, if the **Group by** field is empty and the **Aggregator** field is set to mean, then the chart displays the average of the time series.
   4. To configure how the individual time series are processed, select **Advanced Options** . See [Selecting
      metrics when using Metrics Explorer](https://cloud.google.com/monitoring/charts/metrics-selector#filter-option) for more information.
7. Optionally add to a dashboard.

   When you navigate away from the
   **Metrics Explorer** page, the chart is discarded. You can
   optionally select **Save Chart** to save the chart to a new or
   existing dashboard. See [Creating dashboards](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#create-dashboards)
   below for more information on adding a chart to a dashboard.

### Chart multiple metrics

In some situations, you might want to display multiple metrics on the same
chart. For example, you might want to show the quota limit on the same charts as
you show the quota usage. A chart can display a maximum of 10 metrics.

To add a metric to an existing chart, do the following:

1. In the existing chart, select **Add another metric** at the bottom of the screen.
2. Select the metric, and then specify how to display the time series for that metric in the same way as you configured the original metric above.

### Related resources

For more information on exploring metrics, see:

- [Create charts with Metrics Explorer](https://cloud.google.com/monitoring/charts/metrics-explorer)
- [Selecting metrics when using Metrics Explorer](https://cloud.google.com/monitoring/charts/metrics-selector)
- [Metrics available to all Google Cloud APIs](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-serviceruntime)
- [Metrics specific to Google Maps Platform APIs](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-maps)
- [Chart distribution metrics](https://cloud.google.com/monitoring/charts/charting-distribution-metrics)
- [View options](https://cloud.google.com/monitoring/charts/chart-view-options)

## Create dashboards

Dashboards let you view and monitor your time-series data as a collection of
charts. Cloud Monitoring supports predefined dashboards and custom
dashboards:

- **Predefined dashboards** are automatically installed for the Google Cloud services that you use. These dashboards aren't configurable.
- **Custom dashboards** are those dashboards that you create. Custom dashboards let you define the data you want to view and how to view that data. For example, you can display metric data, alerting policies, and logs stored in your project. You can display time-series data on a chart, with a gauge or scorecard, or in tabular form.

To create custom dashboards, you can use the Cloud console or the
Cloud Monitoring API. The following image shows a custom dashboard with two
charts:

- A quota chart on the left
- An API count chart on the right

![A screenshot of a custom dashboard, displaying two charts. The chart on
the left is a quota chart, while the chart on the right is a chart of API usage.
Both charts list time points on their horizontal axis.](https://developers.google.com/static/maps/reporting-and-monitoring/images/gmp-mon-dashboard.png)

Create a custom dashboard by creating metrics charts and then adding the
charts to the dashboard. You can create the chart in the **Metrics
explorer**, then add it to a new or existing dashboard. Or, you can
create the dashboard, and then edit the dashboard to add a chart.

If you choose to manage custom dashboards by using the
[Cloud Monitoring API](https://cloud.google.com/monitoring/docs/apis), the
Metrics explorer provides you two useful utilities:

- To generate the JSON representation for a chart that you plan to add to a dashboard, configure the chart with Metrics Explorer. You can then access the JSON representation from the **More options** menu item in the Metrics Explorer toolbar.
- To identify the syntax for a Monitoring filter, which is used with the Cloud Monitoring API, use the menu-driven interface of Metrics Explorer to configure the chart. After you select the metric and filters, switch to [direct filter mode](https://cloud.google.com/monitoring/charts/metrics-selector#metric-filter) to view the equivalent Monitoring filter.

### Create a custom dashboard

To create a custom dashboard, do the following:

1. In the Cloud console, select **Monitoring** :

   [Go to Monitoring](https://console.cloud.google.com/monitoring)
2. In the navigation pane, select **Dashboards**.
3. In the Dashboards Overview page, click **Create dashboard** .

   > [!NOTE]
   > **Note:** If you are editing an existing dashboard, ensure that you are in editing mode. In the upper-right, if **Editing** isn't shown, then click **Viewing** and select **Switch to Editing mode**.

4. For each chart that you want to add to the dashboard, do the following:
   1. Select a chart type from **Add chart**, or drag one from
      the library to the graph area.

      A preconfigured chart of the selected type is displayed. The following example shows a Line chart
      and its configuration pane:

      ![A screenshot of the metrics explorer which you use to create a chart to
      add to a dashboard.](https://developers.google.com/static/maps/reporting-and-monitoring/images/gmp-mon-dashboard-chart.png)

      > [!NOTE]
      > **Note:**If no data appears in the chart, either extend the time interval or exit and make several API requests to generate metrics data.

   2. Select the **Resource type** and **Metric** , and apply any filters just as you did above when creating a chart.

      For more information about your choices, see
      [Add dashboard widgets](https://cloud.google.com/monitoring/charts).
5. **(Optional)** In the dashboard toolbar, click **Add chart** to add another chart and then repeat the previous steps to customize the chart.
6. When you are done editing, select the left arrow to leave the dashboard, or select any other **Monitoring** menu item. Your dashboard is saved automatically.

### View a dashboard

To view a dashboard, do the following:

1. In the Cloud console, select **Monitoring** :

   [Go to Monitoring](https://console.cloud.google.com/monitoring)
2. In the navigation pane, select **Dashboards**.
3. Select your custom dashboard or a predefined dashboard from the list.

### Related resources

For more information on creating dashboards, see:

- [Dashboards and charts](https://cloud.google.com/monitoring/dashboards)
- [Manage custom dashboards in the Console](https://cloud.google.com/monitoring/charts/dashboards)
- [Manage dashboards by API](https://cloud.google.com/monitoring/dashboards/api-dashboard)

## Usage metrics

Two groups of metrics are available for monitoring usage of Google Maps Platform APIs: [Serviceruntime metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-serviceruntime)
(resource type [consumed_api](https://cloud.google.com/monitoring/api/resources#tag_consumed_api))
available to the most [Google Cloud APIs](https://console.cloud.google.com/apis/library)
and [Google Maps Platform metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-maps),
Google Maps Platform APIs specific metrics, (resource type
[maps.googleapis.com/Api](https://cloud.google.com/monitoring/api/resources#tag_maps.googleapis.com/Api)).

Both metrics supports same set of resource labels for splitting APIs usage traffic:
`project_id`, `service`, `method`, `version`,
`location` and `credential_id`. See descriptions of the resource labels
in the documentation for corresponding Metrics resource:

- [Serviceruntime metrics resource labels](https://cloud.google.com/monitoring/api/resources#tag_consumed_api)
- [Google Maps Platform resource labels](https://cloud.google.com/monitoring/api/resources#tag_maps.googleapis.com/Api)

Each group of metrics has two metric types for usage monitoring: **Request Count**
and **Request Latencies**.

In the **Request Count** metric you can split usage traffic by
`protocol`, `grpc_status_code`, `response_code`,
and `response_code_class` metric labels. Additionally, you can split by
`platform_type` in Google Maps Platform metrics.

In the **Request Latencies** metric you can split usage traffic by
`protocol`, `platform_type`, `response_code` and `response_code_class` metric labels in Google Maps Platform metrics only.

See more details on Metric types and labels in the documentation for corresponding
Metrics group:

- [Serviceruntime metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-serviceruntime)
- [Google Maps Platform metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-maps)

### Response status and Response code labels mapping

The table below shows the mapping between the Response status code and HTTP response
code returned in response to Google Maps Platform API requests and response code labels
available in Cloud Monitoring: HTTP response code, HTTP response code class,
[GRPC status code](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto).
The [GRPC status code](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto)
is a numeric gRPC response code for gRPC requests, or gRPC equivalent code for HTTP requests.

> [!NOTE]
> **Note:** For historical reasons, the HTTP response code returned in response to Google Maps Platform API requests can be different from the HTTP response code in Usage reports ([Google Maps Platform Metrics](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#google-maps-metrics)) and Cloud Monitoring ([Google Maps Platform Monitoring](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt)). The Usage Reports metrics use a set of response code values that are consistent with those used in newer APIs. This improves the observability of APIs usage in [Google Maps Platform Metrics](https://developers.google.com/maps/reporting-and-monitoring/reporting.md.txt#google-maps-metrics) and [Google Maps Platform Monitoring](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt).

| Response codes returned in API responses || Response codes reported to Monitoring |||
| Maps API status | HTTP response code | HTTP response code | HTTP response code class | GRPC status code |
|---|---|---|---|---|
| OK | 200, 204, 302 | 200, 204, 302 | 2xx, 3xx | 0 (OK) |
| DATA_NOT_AVAILABLE, NOT_FOUND, ZERO_RESULTS | 200 | 200, 404^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 2xx, 4xx^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 5 (NOT_FOUND)^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ |
| INVALID_REQUEST (invalid parameter value), MAX_ROUTE_LENGTH_EXCEEDED, MAX_WAYPOINTS_EXCEEDED, etc. | 200, 400 | 400 | 4xx | 3 (INVALID_ARGUMENT) |
| INVALID_REQUEST (invalid/missing parameter, request parsing error) | 200, 400 | 400 | 4xx | 3 (INVALID_ARGUMENT) |
| REQUEST_DENIED | 200, 403, 200, 400 | 403, 401^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 4xx^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 7 (PERMISSION_DENIED), 16 (UNAUTHENTICATED) |
| OVER_DAILY_LIMIT, OVER_QUERY_LIMIT, RESOURCE_EXHAUSTED, dailyLimitExceeded, rateLimitExceeded, userRateLimitExceeded | 200, 403, 429 | 429^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 4xx^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 8 (RESOURCE_EXHAUSTED) |
| UNKNOWN_ERROR | 200, 500, 503 | 500^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^, 503 | 5xx^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^ | 2 (UNKNOWN)/13 (INTERNAL)^([1](https://developers.google.com/maps/reporting-and-monitoring/monitoring.md.txt#monitoring-codes-reports-fn1))^, 14 (UNAVAILABLE) |

## Create alerts

[Alerting](https://cloud.google.com/monitoring/alerts) gives
timely awareness to problems in your applications so you can resolve the
problems quickly. In Cloud Monitoring, an alerting policy describes the
circumstances under which you want to be alerted and how you want to be
notified.

Alerting policies can be simple or complex. Alerting policies let you
configure whether a single time series can cause a condition to be met, or
whether multiple time series must satisfy the condition before it is met. For
example:

- Notify me when the request count for a specific API exceeds 1000 requests per 5-minute window.
- Notify the on-call team when the 90th percentile of HTTP 200 responses exceeds a latency of 100 ms for 3 or more APIs.

The following image shows an alert definition to generate a notification when
the request count for an API exceeds 20 requests in a 5 minute window:

![A screenshot of the alert definition showing API request counts for all
Maps APIs as individual lines, and the alert threshold as a horizontal line.](https://developers.google.com/static/maps/reporting-and-monitoring/images/gmp-mon-alert-20.png)

In this image:

- The chart show the number of API calls over time for different APIs.
- The red line shows the alert threshold. API calls that exceed this threshold for a 5-minute window trigger the alert. In this example, you can see that one API exceeded the limit.

When the conditions of an alerting policy are met, Cloud Monitoring opens
an incident and issues notifications:

- An incident is a persistent record that stores information about the monitored resources when the condition was met. When the condition stops being met, the incident is automatically closed. You can view all incidents, open and closed, by using the alerting dashboard.
- You specify who is to be notified when you configure an alerting policy. Monitoring supports common notifications channels, including email, Cloud Mobile App, and services such as PagerDuty or Slack. For a full list of notification channels, see [Notification options](https://cloud.google.com/monitoring/support/notification-options).

### Alert types

Cloud Monitoring supports many types of alerts. For example, you can
define:

- [Metric threshold alerts](https://cloud.google.com/monitoring/alerts/types-of-conditions#metric-threshold): Trigger an alert if a metric rises above or falls below a value for a specific [duration window](https://cloud.google.com/monitoring/alerts/concepts-indepth#duration) or a metric increases or decreases by a predefined percentage.
- [Budget alerts](https://cloud.google.com/billing/docs/how-to/budgets): Set threshold rules to trigger notifications when your costs (actual costs or forecasted costs) exceed a percentage of your budget (based on the rules you set). The alert does not cap API usage, it only alerts you when your spend amount gets near the specified amount.
- [Quota alerts](https://cloud.google.com/monitoring/alerts/using-quota-metrics): Google Cloud establishes various quotas that you can use to track and limit the resources consumed by a project or organization. Use alerts to send notifications when your usage approaches a quota limit.

See [Types of alerting policies](https://cloud.google.com/monitoring/alerts/types-of-conditions)
for more information.

### Manage alerting policies

You can add an alerting policy to your project by using the
Cloud console or the Cloud Monitoring API.
For information about how to view a list of your project's metric-based alerting
policies, and how to modify those policies, see the following:

- [Managing
  alerting policies by using the Cloud console](https://cloud.google.com/monitoring/alerts/using-alerting-ui)
- [Managing
  alerting policies by using the Cloud Monitoring API](https://cloud.google.com/monitoring/alerts/policies-in-api)

### Create an alert

When you create an alert, you:

- Define the conditions triggering your alerts, based on metrics data.
- Define notification channels to which alert notifications will be sent.

The example below shows how to set up an alert triggering when your
Google Maps Platform service usage rate for any API exceeds 2 requests
for a 5-minute window.

> [!NOTE]
> **Note:**This is a low number of API requests used only to help trigger the alert for this example.

To create the alert, do the following:

1. In the Cloud console, select **Monitoring** :

   [Go to Monitoring](https://console.cloud.google.com/monitoring)
2. Select **Alerting**.
3. Select **Edit Notifications Channel** to define how the alert issues its notification. In this example, you will use your email address.
   1. For the **Email channel** , select **Add
      New**.
   2. Enter an **Email Address** and **Display
      Name**.
   3. Select **Save**.
4. Select **Alerting**.
5. Select **Create Policy**.
6. Select a time interval, such as **7 days**.
7. Under **Alert Conditions** , select **New condition**:
   1. Click **Select a Metric** , and select **Consumed
      API** as the resource and **Request Count** as the metric and then select **Apply** .

      > [!NOTE]
      > **Note:** If **Request Count** does not appear in the list of metrics, exit and make several API requests. You cannot select a metric unless there is existing data for the metric.

   2. **(Optional)** Below the chart is the list of **service** , **quota_metrics** , API **method** , and metric **value** . Select **Add filter** to filter the data based on this information. For example, you can use the filter to specify that the **method** has to equal **google.places.Autocomplete.http** to trigger the alert.
   3. Under **Transform data** select **5 min** for the **Rolling window** and **mean** for the **Rolling window function**.
   4. Select **Next**.
8. Under **Configure alert trigger** , set the **Threshold
   value** to 2 to specify to trigger the alert when there are more than 2 requests in the 5 minute window. Notice that the chart now shows the red line indicating the alert limit for the selected time interval. From the chart, you can see where an alert would have been triggered. You can use this chart to help you adjust the limit as necessary.
9. Click **Next**.
10. On the **Configure notifications and finalize alert** page:
    1. Select the email address you created for the **Notification
       Channel**.
    2. Under **Name the alert** , enter **My Test
       Alert**.
    3. Select **Create Policy**.
11. Make some API requests. Ensure that you make more than two API requests within five minutes to generate the alert email notification.
12. After you get the email for the alert, go to the **Alerting** page.
    1. In the table listing alerts, click the alert to view more information.
    2. Click the alert name to see information about the alert, including a chart showing the event that triggered it.

### Related resources

For more information on alerts, see:

- [Introduction to alerting](https://cloud.google.com/monitoring/alerts)
- [Create, edit, or delete budgets and budget alerts](https://cloud.google.com/billing/docs/how-to/budgets)
- [Settings for common alerting policies](https://cloud.google.com/monitoring/alerts/target-configuration-library)
- [Chart and monitor quota metrics](https://cloud.google.com/monitoring/alerts/using-quota-metrics)