Migrating to the v3 API

This guide helps you migrate from the deprecated Cloud Monitoring API v2beta2 and v2beta1 to the Stackdriver Monitoring API v3.

Are you affected?

If you do any of the following, you might be using the deprecated APIs:

  • You run applications that use the Cloud Monitoring API (cloudmonitoring.googleapis.com).

    For more information and migration instructions, see Cloud Monitoring users on this page.

  • You run Kubernetes on Google Compute Engine VM instances and you use Stackdriver Monitoring—formerly Google Cloud Monitoring—as your monitoring solution.

    For more information and migration instructions, see Kubernetes users on this page.

  • You use Autoscaling controlled by custom metrics in the Cloud Monitoring API v2beta2.

    For more information and migration instructions, see Autoscaling users on this page.

If you are not sure whether or not you are using the deprecated API:

  • The APIs & services dashboard shows you which APIs your project is using. If you see any traffic for the Google Cloud Monitoring API, then something in your project is using the deprecated APIs.

    Go to APIs & services

  • Google is notifying all owners of projects that are using the deprecated APIs. This usage data comes from the same source as the API Dashboard.

Cloud Monitoring API users

You must migrate any applications that use the Cloud Monitoring API (cloudmonitoring.googleapis.com). The API version can be v2beta1 or v2beta2—that API does not have any other versions.

It does not matter whether the applications are running in containers, in Compute Engine, on your local workstation, or in some other fashion—they still must be migrated.

If your applications use only the Stackdriver Monitoring API v3 (monitoring.googleapis.com), then you do not have to migrate your applications. This API has no other versions than v3.

Application migration procedure

See the following section, Migrating applications to the v3 API. That section, and the ones that follow it, help you migrate your applications off the deprecated APIs.

Kubernetes users

You need to migrate if you are running Kubernetes on Google Compute Engine VM instances, and both of the following are true:

  • You are running a Kubernetes version prior to 1.6.
  • You are using Stackdriver Monitoring—formerly known as Google Cloud Monitoring—as your monitoring solution. This is not the default for Kubernetes.

You do not need to migrate if you only use Kubernetes as part of Google Container Engine.

Kubernetes migration procedure

  1. Upgrade your Kubernetes master machine to Kubernetes version 1.6 or later.

  2. Ensure that you are running Heapster version 1.3 or later. If you don’t deploy Heapster on your own, then using Kubernetes version 1.6 or later should ensure that you have the correct version of Heapster. Otherwise, do the following:

    1. Determine your version of Heapster by running the following command on the Kubernetes master machine:

      kubectl get pods --all-namespaces -o yaml | grep image | grep heapster
      
    2. If you are not running version 1.3 or later, then update your version of Heapster.

Autoscaling users

If you use the autoscaling feature in Compute Engine and your autoscaling policy is based on v2beta2 custom metrics, then you will have to create a new v3 metric and update your autoscaler policy to use the new metric.

For more information about autoscaling, see Autoscaling Groups of Instances. For information on using custom metrics in your autoscaler policy, see Scaling Based on Stackdriver Monitoring Metrics.

Autoscaler migration procedure

In the following procedure, you create a v3 custom metric in parallel with your v2beta2 custom metric. If something prevents you from having both metrics active at the same time, then see the following section, Suspending and resuming the autoscaler.

  1. To determine if you are autoscaling based on a v2beta2 custom metric, examine your autoscaler policy. You can identify metrics in the v2beta2 API from the following prefix to their names:

    custom.cloudmonitoring.googleapis.com/
    

    You can identify metrics in the v3 API from this prefix:

    custom.googleapis.com/
    

    If you are only using v3 custom metrics, then migration is not required. Otherwise, if you are using v2beta2 custom metrics, then continue with these instructions.

  2. Create a v3 custom metric:

    1. Create a v3 custom metric with the same name as the v2beta2 custom metric. For information, see Creating custom metrics.
    2. Find the application that writes your v2beta2 custom metric time series.
    3. Change the application's code to write time series data to both your new v3 custom metric and your old v2beta2 custom metric. This lets you smoothly switch over to the v3 custom metric.

    When you complete the previous steps, you will be exporting the same time series to both v2beta2 and v3 custom metrics.

  3. Update your autoscaling policy to switch from the v2beta2 custom metric to the v3 custom metric. For instructions, see Managing Autoscalers.

    If you used the same name for your new v3 custom metrics, updating the policy involves replacing the v2beta2 custom metric prefix:

    custom.cloudmonitoring.googleapis.com/
    

    with the v3 prefix:

    custom.googleapis.com/
    
  4. The autoscaler begins to use your new v3 metric time series within 10 minutes after you update the autoscaling policy. Then, you can stop writing the v2beta2 custom metric data and remove the code using the deprecated API.

Suspending and resuming the autoscaler

If something prevents you from exporting both v2beta2 and v3 metrics data at the same time, then you will have to pause the autoscaler while you switch the metrics. For details about enabling and disabling autoscalers, see Managing Autoscalers. Follow this procedure:

  1. Disable your autoscaler.
  2. Stop writing your v2beta2 custom metric time series data.
  3. Create a v3 custom metric and begin writing its time series data. For details, see Creating custom metrics.
  4. Change the autoscaler policy to use the v3 metric rather than the v2beta2 metric.
  5. Reenable your autoscaler.

Migrating applications to the v3 API

The rest of this page is devoted to manually converting applications that use the v2beta1 or v2beta2 API to instead use the v3 API. For simplicity in what follows, the deprecated APIs will be referred to as "the v2 API."

The Stackdriver Monitoring API v3 is not compatible with the previous Cloud Monitoring API 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.

  • Review the comparisons of individual API methods in this document and the v3 API reference documentation.

  • Use the APIs Explorer to try out the v3 API. For instructions, see APIs Explorer.

  • Review the new Client Libraries. The "Google Cloud Client Libraries" are preferred over the former "Google API Client Libraries."

  • Review the sample code that demonstrates creating and retrieving custom metrics using the v3 API.

When you are ready, do the following:

  1. Convert and test your code.

  2. Visit the APIs & services dashboard and verify that you are no longer using the Google Cloud Monitoring API (the v2 API).

    Go to APIs & services

API comparison

The following sections compare the v2 and v3 API methods for metrics. The v3 API has other features that are not in the v2 API, but they are not relevant to migration.

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 monitoring 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.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Monitoring