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