Introduction to the Cloud Monitoring API

This page describes some of the features of the Cloud Monitoring API v3.

For the API reference documentation, see either of the following pages:

Project names in the Monitoring API

All of the methods in the Monitoring API have a required name parameter. This parameter typically has a description like the following:

Required. The project on which to execute the request. The format is:
projects/[PROJECT_ID_OR_NUMBER]

In the Monitoring API, the value of PROJECT_ID_OR_NUMBER identifies one of the following:

Some methods in the Monitoring API require the project to be a scoping project of a metrics scope; others methods do not. A small number of methods can return different results, depending on the type of project.

To describe these classes of methods, this discussion uses the term metrics API to refer to the following resources in the Monitoring API:

scoping project of a metrics scope required

All Monitoring API methods that are not part of the metrics API require the name parameter to refer to a scoping project of a metrics scope.

scoping project of a metrics scope not required

None of the methods in the metrics API require the name parameter to refer to a scoping project of a metrics scope, but some methods behave differently when it is:

  • The following methods in the metrics API operate on the named Google Cloud project. These methods affect data only in the named project, regardless of whether the project is also a scoping project of a metrics scope.

    • timeSeries.create
    • metricDescriptors.create
    • metricDescriptors.delete
    • metricDescriptors.get
    • monitoredResourceDescriptors.get

  • The remaining methods in the metrics API behave as follows:

    • If the named project is not a scoping project of a metrics scope, then the methods retrieve data only from the named project.
    • If the named project is also a scoping project of a metrics scope, then the methods retrieve data from both the named project and any projects it monitors.

    The methods in this group are the following:

    • timeSeries.list
    • timeSeries.query
    • metricDescriptors.list
    • monitoredResourceDescriptors.list

For information on setting up a Google Cloud project as a scoping project of a metrics scope, see Metrics scopes overview.

API resources

Metrics

The Monitoring API gives you access to approximately 6,500 Cloud Monitoring metrics from Google Cloud and Amazon Web Services. You can create your own custom metrics and can organize your cloud resources using groups.

For an introduction to metric concepts and the data structures that represent them, see Metrics, time series, and resources.

To learn how to manage your custom metrics and the built-in metrics, see User-defined metrics overview.

For a complete list of available metrics, see Metrics list.

Monitored resources

A monitored resource is something about which metrics are collected. For example, you might be interested in the activity of a VM instance or a piece of hardware.

For a list of the available monitored resources, see the Monitored resource list.

Monitored-resource groups

A group is a dynamic collection of monitored resources. You have always been able to create groups manually in the Google Cloud console, and you can also use the Cloud Monitoring API to write code that creates and uses groups.

For more information, see the API reference for Group.

Alerting policies

An alerting policy is a configuration resource that describes the criteria for generating incidents and how to notify you when those incidents are created. Alerting concepts explains the basic concepts of alerting policies. For more information, see the API reference for AlertPolicy.

The API also lets you create alerting policies based on a ratio of two metrics. Ratios cannot currently be created by using Monitoring in the Google Cloud console. For more information, see MetricThreshold in the AlertPolicy reference.

Notification channels

A notification channel is a configuration resource that describes how to notify you when incidents occur. Notification channels can reference a variety of different kinds of communication services and endpoints; these are specified in descriptors. The descriptors determine the set of configuration parameters that are included in a channel object.

For more information, see the NotificationChannel reference and the NotificationChannelDescriptor reference.

Service monitoring

The service monitoring resources are used to set up service-level objectives that can be used to monitor the health of your services.

Service Monitoring adds the following resources to the Monitoring API:

For more information about these service-monitoring concepts and about using the API, see SLO monitoring.

Dashboards

You can programmatically create and manipulate both dashboards and charts using the Dashboards endpoint. For information on using this endpoint to manage dashboards and charts, see Managing dashboards by API.

Monitoring Query Language

Monitoring Query Language (MQL) provides a text-based interface for querying Cloud Monitoring time-series data. MQL uses a piped-query model and is more expressive than Monitoring filters. You can use MQL queries from the Monitoring API or from the code editor.

For general information on MQL, see Using Monitoring Query Language.

For information on using MQL to retrieve time-series data by using the Monitoring API, see the API reference for the timeSeries.query method.

Filters

The Monitoring API uses filters to select metrics, to fetch time-series data, and to collect monitored resources into groups. For more information, see Monitoring filters.

The Monitoring API also uses filters to restrict the result set of certain list operations. See Sorting and filtering for details on managing the results of the alertPolicies.list and notificationChannels.list methods.

Next steps