This document describes how to create user-defined metrics and how to write this metric data by using the Cloud Monitoring API. User-defined metrics use the same elements that the built-in Cloud Monitoring metrics use:
- A set of data points.
- Metric-type information, which tells you what the data points represent.
- Monitored-resource information, which tells you where the data points originated.
User-defined metrics, sometimes called custom metrics, can be used in the same way as built-in metrics. That is, you can create charts and alerts for this metric data.
Log-based metrics are a class of user-defined metrics, but you can't create them by using the Cloud Monitoring API. Log-based metrics derive metric data from log entries, but the Monitoring API provides no way to specify how to extract metric data from log entries. Instead, use Cloud Logging to create log-based metrics. When you create a log-based metric, Logging creates the structures described in this document and sends the metric data to Cloud Monitoring for you. For information about creating log-based metrics, see the following documents:
To instrument your application, we recommend that you use an open-source, vendor-neutral instrumentation framework, such as OpenTelemetry, instead of vendor- and product-specific APIs or client libraries. For information about these frameworks, see Instrumentation and observability and Choose an instrumentation approach.
Before you begin
To learn about the structures that underlie all metrics, see Metrics, time series, and resources.
To use Cloud Monitoring, you must have a Google Cloud project with billing enabled. When necessary, do the following:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- Ensure the Monitoring API is enabled. For details, see Enabling the Monitoring API.
- For applications running outside of Google Cloud, your Google Cloud project must authenticate your application using local Application Default Credentials (ADC). For more information, see Set up ADC for on-premises or another cloud provider.
Create a user-defined metric type
To create a user-defined metric, you either define a
MetricDescriptor object
that specifies various information about the metric,
or you write metric data. When you write metric data,
Monitoring creates the metric descriptor for you based
on the structure of the data you provide.
For information about designing a metric descriptor, see
Metric descriptors for user-defined metrics.
Auto-creation of metric descriptors
If you write metric data when a metric descriptor for that user-defined metric doesn't yet exist, then a metric descriptor is created automatically. However, this new metric descriptor might not be exactly what you want; auto-creation of metric descriptors involves some assumptions and defaults.
Cloud Monitoring creates a new MetricDescriptor when
the TimeSeries object included in a call to
timeSeries.create references a
Metric object that specifies a nonexistent
metric-type name.
Cloud Monitoring uses the following rules to populate the
MetricDescriptor:
type: The type is copied from theMetricobject'stypefield.name: The name is created from the project ID in the method call and the value of thetypein theMetricobject.labels: The labels that appear in theMetricobject. Each label descriptor in the new metric descriptor has the following fields:key: the label key in theMetricobject.valueType:STRINGdescription: not set
metricKind: The metric kind is set toGAUGEunless you specify themetricKindparameter of theTimeSeriesobject. When you specify themetricKind, the new metric has that kind. You can specify onlyGAUGEandCUMULATIVEkinds.valueType: The value type is taken from the typed value of thePointbeing written. The value type must beBOOL,INT64,DOUBLE, orDISTRIBUTION. When you specify a value type in thevalueTypefield of theTimeSeries, that type must match the type of thePoint.unit: not setdescription:"Auto created custom metric.".displayName: not set
In a single timeSeries.create call, you can
include multiple TimeSeries
objects that refer to the same nonexistent metric type. In that case,
the labels in the new metric descriptor consist of the union of all the labels
in the Metric objects in all the time series in this call to
create.
Next step: See Write user-defined metrics.
Manual creation of metric descriptors
To create a metric descriptor, do the following:
Determine the structure of your metric descriptor. For help in making these choices, you can browse the built-in metrics and look at their time series data:
Choose a metric name for your user-defined metric.
Choose a display name and description for your metric. The display name is used in the Google Cloud console.
Choose a project or projects in which to define your user-defined metric and write its time series data. When you need the same metric in several projects, make identical definitions of the metric in each project.
Determine the metric's kind, value type, and (optionally) units. Not all value types and metric kinds are supported for user-defined metrics. For more information on these fields, see Value types and metric kinds.
Choose the metric's labels—their names, value types, and descriptions.
Determine the monitored resources against which the metric data is written. Choose from the following list:
aws_ec2_instance: Amazon EC2 instance.dataflow_job: Dataflow job.gae_instance: App Engine instance.gce_instance: Compute Engine instance.generic_node: User-specified computing node.generic_task: User-defined task.gke_container: GKE container instance.global: Use this resource when no other resource type is suitable. For most use cases,generic_nodeorgeneric_taskare better choices thanglobal.k8s_cluster: Kubernetes cluster.k8s_container: Kubernetes container.k8s_node: Kubernetes node.k8s_pod: Kubernetes pod.
Create a
MetricDescriptorobject, and then pass it as an argument to a call to themetricDescriptors.createmethod.
It is usually an error to call
metricDescriptors.create using the same type
name as an existing metric descriptor. However, if all the fields of the
new MetricDescriptor object match the fields of the
existing descriptor exactly, then it isn't an error but it has no effect.
In the following example, you create a gauge metric.