Migrating to the v3 API

This guide helps you to migrate from the Cloud Monitoring API v2beta2 to the Stackdriver Monitoring API v3, by providing a side-by-side comparison of the corresponding API methods.

Introduction

The Stackdriver Monitoring API API v3 is not compatible with the previous Cloud Monitoring API v2beta2 (called v2). You might approach migrating your code to v3 in the following way:

  • Read the new metrics introduction, Metrics, Time Series, and Resources, for an overview of the new terminology and data types. (The v2 API provides only operations related to metrics.)
  • Review the comarisons of individual API methods in this document and the v3 API reference documentation.
  • Use the APIs Explorer to try out the v3 API. See APIs Explorer for instructions.
  • Review the new Client Libraries.
  • Review the sample code that demonstrates creating and retrieveing custom metrics using the v3 API.
  • Convert and test your code.

API comparison

The v2 and v3 API methods for metrics are compared in the following sections. The v3 API has some new methods for groups and monitored resource descriptors, which were not in the v2 API.

metricDescriptors.create

Creates a new custom metric descriptor.

HTTP request:

POST https://www.googleapis.com/cloudmonitoring /v2beta2 /projects/{project=*} /metricDescriptors
POST https://monitoring.googleapis.com          /v3      /{name=projects/*}    /metricDescriptors

Request body:

v2 v3
{
  "name": string,
  "project": string,
  "labels": [
    {
      "key": string,
      "description": string
    }
  ],
  "typeDescriptor": {
    "metricType": string,
    "valueType": string
  },
  "description": string
}
{
  "name": string,
  "type": string,
  "labels": [
    {
      LabelDescriptor
    }
  ],
  "metricKind": enum(MetricKind),
  "valueType": enum(ValueType),
  "unit": string,
  "description": string,
  "displayName": string
}

metricDescriptors.delete

Deletes a custom metric descriptor.

HTTP requests:

DELETE https://www.googleapis.com/cloudmonitoring /v2beta2 /projects/{project=*}/metricDescriptors/{metric=**}
DELETE https://monitoring.googleapis.com          /v3      /{name=projects/*/metricDescriptors/**}

Request body: none

metricDescriptors.list

Lists metric descriptors matching a filter. See v3 monitoring filters.

HTTP requests:

GET https://www.googleapis.com/cloudmonitoring /v2beta2 /projects/{project=*}/metricDescriptors
GET https://monitoring.googleapis.com          /v3      /{name=projects/*}/metricDescriptors

Query parameters:

v2 v3
  • count: integer
  • pageToken: string
  • query: string (space-separated keywords)

metricDescriptors.get

Retrieves the metric descriptor for a specified type. This method is not in the v2 API.

HTTP requests:

GET https://monitoring.googleapis.com          /v3      /{name=projects/*/metricDescriptors/**}

timeSeries.list

Lists one or more time series from a single metric type.

HTTP request:

GET https://www.googleapis.com/cloudmonitoring /v2beta2 /projects/{project=*}/timeSeries
GET https://monitoring.googleapis.com          /v3      /{name=projects/*}/timeseries/{metric=**}

Query parameters:

v2 v3
  • aggregator: string
  • count: integer
  • labels: string
  • oldest: string
  • pageToken: string
  • timespan: string
  • window: string

Response:

v2 v3
{
  "kind": "cloudmonitoring#listTimeseriesResponse",
  "youngest": datetime,
  "oldest": datetime,
  "timeseries": [
    timeseries Resource
  ],
  "nextPageToken": string
}
where timeseries is:
  "timeseriesDesc": timeseriesDescriptors Resource,
  "points": [
    {
      "start": datetime,
      "end": datetime,
      "boolValue": boolean,
      "int64Value": long,
      "doubleValue": double,
      "stringValue": string,
      "distributionValue": {
        "underflowBucket": {
          "upperBound": double,
          "count": long
        },
        "buckets": [
          {
            "lowerBound": double,
            "upperBound": double,
            "count": long
          }
        ],
        "overflowBucket": {
          "lowerBound": double,
          "count": long
        }
      }
    }
  ]
}
{
  "timeSeries": [
    {
      TimeSeries
    }
  ],
  "nextPageToken": string
}
where TimeSeries is:
{
  "metric": {
    Metric
  },
  "resource": {
    MonitoredResource
  },
  "metricKind": enum(MetricKind),
  "valueType": enum(ValueType),
  "points": [
    {
      Point
    }
  ]
}
and Point is:
{
  "interval": {
    TimeInterval
  },
  "value": {
    TypedValue
  }
}

timeSeries.create

Adds a single point to time series within a single metric type. The corresponding v2 method is called timeseries.write. If the time series do not exist, they are created before adding the data.

Note: Do not use the collectdTimeSeries.create method in the v3 API, even if you are sending data from your own collectd daemon. The API collectdTimeSeries.create method is only for the Stackdriver Monitoring agent.

HTTP request:

POST https://www.googleapis.com/cloudmonitoring /v2beta2 /projects/{project=*}/timeseries:write
POST https://monitoring.googleapis.com          /v3      /{name=projects/*}/timeSeries

Request body:

v2 v3
{
  "commonLabels": {
    (key): string
  },
  "timeseries": [
    {
      "timeseriesDesc": timeseriesDescriptors Resource,
      "point": {
        "start": datetime,
        "end": datetime,
        "boolValue": boolean,
        "int64Value": long,
        "doubleValue": double,
        "stringValue": string,
        "distributionValue": {
          "underflowBucket": {
            "upperBound": double,
            "count": long
          },
          "buckets": [
            {
              "lowerBound": double,
              "upperBound": double,
              "count": long
            }
          ],
          "overflowBucket": {
            "lowerBound": double,
            "count": long
          }
        }
      }
    }
  ]
}
{
  "timeSeries": [
    {
      TimeSeries
    }
  ]
}
where TimeSeries is:
{
  "metric": {
    Metric
  },
  "resource": {
    MonitoredResource
  },
  "metricKind": enum(MetricKind),
  "valueType": enum(ValueType),
  "points": [
    {
      Point
    }
  ]
}
and Point is:
{
  "interval": {
    TimeInterval
  },
  "value": {
    TypedValue
  }
}

timeseriesDecriptors.list

Lists the description of one or more time series in a single metric type that have data. Does not list the data points. This method is only present in the v2 API.

HTTP request (v2 only):

GET https://www.googleapis.com/cloudmonitoring /v2beta2 /projects/{project=*}/timeseriesDescriptors/{metric=**}

In the Stackdriver Monitoring API v3, get this effect by using timeSeries.list and set the fields parameter to timeSeries.metric or set the view parameter to HEADERS.

General changes

Resource names

In the v3 API, name parameters represent the resource name of objects, which can contain both project and object IDs. For example, using projects.metricDescriptors.delete:

  • In the v2 API there are two parameters:

    project: "my-project-id"
    metric: "custom.googleapis.com/my-custom-metric"
    
  • In the v3 API there is only one parameter:

    name: "projects/my-project-id/metrics/custom.googleapis.com%2Fmy-custom-metric"
    

Notice that the metric ID is URL-encoded in the resource name. Parameter components that might require URL encoding are denoted by ** in the HTTP request:

DELETE https://monitoring.googleapis.com/v3/{name=projects/*/metricDescriptors/**}

Pagination

v3 API methods that return a list of objects are now paginated. Your code should iterate making calls to those methods until the nextPageToken response parameter is empty.

If pageSize is not specified or is illegal, a large default value is used.

When making a follow-up request for more data, include as the pageToken parameter the value of nextPageToken returned by the previous request. All other parameters of the follow-up request must be the same as the previous request, including pageSize. Otherwise, the follow-up request will be rejected.

Filters

Several v3 API methods, including timeSeries.list, rely on montoring filters to specify what data to retrieve.

Spelling

The v2 Timeseries is spelled TimeSeries in v3.

Monitored resources

Monitored resources represent cloud entities that originate metrics and other monitoring, such as VM instances, databases, load balancers, and so on. Metric data includes monitored resource objects.

See Metrics, Time Series, and Resources for an introduction to these objects, which are new in the v3 API.

Detailed comparisons

The following is a detailed description of the differences between v2 and v3.

Overview of changes:

  • The v2 Timeseries is spelled TimeSeries in v3.

  • You describe metrics with the v3 MetricDescriptor object, which reorganizes the information that was in the v2 MetricDescriptor object.

  • The v3 TimeSeries object contains both a fully-specified instance of the metric descriptor—a Metric object—and a MonitoredResource object that specifies the cloud entity originating the time series. See Monitored Resources.

  • The information in the v2 TimeSeriesDescriptor used in the v2 Timeseries objects is divided between the v3 Metric and v3 MonitoredResource.

  • TimeSeries objects no longer contain a projectId field. Instead, their monitored resource objects can contain a project_id label that identifies the project to which they belong.

  • If a TimeSeries is an aggregation of time series from monitored resources in different projects, then the value of project_id is the Stackdriver account owning the aggregation.

Metric descriptors

See the side-by-side comparison of the request body for metricDescriptors.create.

Time series

For details of the changes to time series in the v3 API, see the side-by-side comparison of the request body for timeSeries.create and the response to timeSeries.list.

TimeseriesDescriptor

v2's TimeseriesDescriptor is a v3 Metric.

Custom metrics

When creating custom metrics using the v3 API, use the domain custom.googleapis.com, rather than the v2 API domain custom.cloudmonitoring.googleapis.com.

Send feedback about...

Stackdriver Monitoring