Browsing Metrics

This page explains how to use the Stackdriver Monitoring API to do the following:

  • Get a list or description of your custom metric types.
  • Get a list or description of built-in metric types, which can help you design your custom metrics. This list also appears in the documentation; see Metrics List.
  • Get a list or description of the available monitored resource types, which you can use to label your custom metrics' time series data. This list also appears in the documentation; see Monitored Resource Types.

For an introduction to metric types, metric descriptors, and monitored resource types, see Metrics, Time Series, and Resources.

Listing metrics

Metric descriptors are the schemas that define built-in and custom metrics. By browsing the available metric descriptors, you can find out details about the metrics you're interested in. There are presently over 900 built-in metrics. For more information on how metric types are named, see Metric names.

To get a current list of metric types, use the metricDescriptors.list method. Use a filter to narrow the set of metric types that are returned. See Metric names for help deciding which metric type names to search for.

Protocol

The following are sample parameters to metricDescriptors.list for returning Compute Engine metrics:

  • name: projects/{your-project-id}
  • filter: metric.type = starts_with("compute.googleapis.com")
  • fields: metricDescriptors.type,metricDescriptors.displayName

The following sample output shows three of the many Compute Engine metrics that match the filter:

"metricDescriptors": [
  {
   "displayName": "Dropped bytes",
   "type": "compute.googleapis.com/firewall/dropped_bytes_count"
  },
  {
   "displayName": "Dropped packets",
   "type": "compute.googleapis.com/firewall/dropped_packets_count"
  },
  {
   "displayName": "Reserved cores.",
   "type": "compute.googleapis.com/instance/cpu/reserved_cores"
  },
  ...
]

Try It!

C#

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

public static object ListMetrics(string projectId)
{
    MetricServiceClient client = MetricServiceClient.Create();
    ProjectName projectName = new ProjectName(projectId);
    PagedEnumerable<ListMetricDescriptorsResponse, MetricDescriptor> metrics = client.ListMetricDescriptors(projectName);
    foreach (MetricDescriptor metric in metrics)
    {
        Console.WriteLine($"{metric.Name}: {metric.DisplayName}");
    }
    return 0;
}

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const Monitoring = require('@google-cloud/monitoring');

// Instantiates a client
const client = Monitoring.v3().metricServiceClient();

// The Google Cloud Platform project on which to execute the request
// const projectId = 'YOUR_PROJECT_ID';

const request = {
  name: client.projectPath(projectId)
};

// Lists metric descriptors
client.listMetricDescriptors(request)
  .then((results) => {
    const descriptors = results[0];

    console.log('Metric Descriptors:');
    descriptors.forEach((descriptor) => console.log(descriptor.name));
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

PHP

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

use Google\Cloud\Monitoring\V3\MetricServiceClient;

/**
 * Adds a new column to the Albums table in the example database.
 * Example:
 * ```
 * list_descriptors($projectId);
 * ```
 *
 * @param string $projectId Your project ID
 */
function list_descriptors($projectId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $projectName = $metrics->formatProjectName($projectId);
    $descriptors = $metrics->listMetricDescriptors($projectName);

    printf('Metric Descriptors:' . PHP_EOL);
    foreach ($descriptors->iterateAllElements() as $descriptor) {
        printf($descriptor->getName() . PHP_EOL);
    }
}

Python

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

client = monitoring.Client()
for descriptor in client.list_metric_descriptors():
    print(descriptor.type)

Java

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Your Google Cloud Platform project ID
String projectId = System.getProperty("projectId");

final MetricServiceClient client = MetricServiceClient.create();
ProjectName name = ProjectName.create(projectId);

ListMetricDescriptorsRequest request = ListMetricDescriptorsRequest
    .newBuilder()
    .setNameWithProjectName(name)
    .build();
PagedResponseWrappers.ListMetricDescriptorsPagedResponse response =
    client.listMetricDescriptors(request);

System.out.println("Listing descriptors: ");

for (MetricDescriptor d : response.iterateAll()) {
  System.out.println(d.getName() + " " + d.getDisplayName());
}

See Troubleshooting API calls if you have difficulty.

Use any project

Except when listing custom metrics, you can use any existing project in metricDescriptors.list, even if the project is not in a Stackdriver account. If you are listing custom metrics, then you must specify the project where the custom metrics are defined.

Getting metric details

To get more details about a metric type, use the metricDescriptors.get method.

Protocol

To get the details of Compute Engine's /firewall/dropped_packets_count metric, use the following parameter to metricDescriptors.get:

  • name: projects/{your-project-id}/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count

The following sample response shows the metric's descriptor:

{
  "type": "compute.googleapis.com/firewall/dropped_packets_count",
  "name": "projects/{your-project-id}/metricDescriptors/compute.googleapis.com/firewall/dropped_packets_count",
  "description": "Delta count of incoming packets dropped by the firewall.",
  "displayName": "Dropped packets",
  "labels": [
   {
    "key": "instance_name",
    "description": "The name of the VM instance."
   }
  ],
  "metricKind": "DELTA",
  "valueType": "INT64",
  "unit": "1"
}

Try It!

C#

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

public static object GetMetricDetails(string projectId, string metricType)
{
    MetricServiceClient client = MetricServiceClient.Create();
    MetricDescriptorName name = new MetricDescriptorName(projectId, metricType);
    try
    {
        var response = client.GetMetricDescriptor(name);
        string metric = JObject.Parse($"{response}").ToString();
        Console.WriteLine($"{ metric }");
    }
    catch (Grpc.Core.RpcException ex)
        when (ex.Status.StatusCode == Grpc.Core.StatusCode.NotFound)
    { }
    return 0;
}

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const Monitoring = require('@google-cloud/monitoring');

// Instantiates a client
const client = Monitoring.v3().metricServiceClient();

// The Google Cloud Platform project on which to execute the request
// const projectId = 'YOUR_PROJECT_ID';

// An example of "metricId" is "logging.googleapis.com/log_entry_count"
// const metricId = 'some/metric/id';

const request = {
  name: client.metricDescriptorPath(projectId, metricId)
};

// Retrieves a metric descriptor
client.getMetricDescriptor(request)
  .then((results) => {
    const descriptor = results[0];

    console.log(`Name: ${descriptor.displayName}`);
    console.log(`Description: ${descriptor.description}`);
    console.log(`Type: ${descriptor.type}`);
    console.log(`Kind: ${descriptor.metricKind}`);
    console.log(`Value Type: ${descriptor.valueType}`);
    console.log(`Unit: ${descriptor.unit}`);
    console.log('Labels:');
    descriptor.labels.forEach((label) => {
      console.log(`  ${label.key} (${label.valueType}) - ${label.description}`);
    });
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

PHP

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

use Google\Cloud\Monitoring\V3\MetricServiceClient;

/**
 * Adds a new column to the Albums table in the example database.
 * Example:
 * ```
 * get_descriptor($projectId);
 * ```
 *
 * @param string $projectId Your project ID
 * @param string $metricId  The ID of the Metric Descriptor to get
 */
function get_descriptor($projectId, $metricId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $metricName = $metrics->formatMetricDescriptorName($projectId, $metricId);
    $descriptor = $metrics->getMetricDescriptor($metricName);

    printf('Name: ' . $descriptor->getDisplayName() . PHP_EOL);
    printf('Description: ' . $descriptor->getDescription() . PHP_EOL);
    printf('Type: ' . $descriptor->getType() . PHP_EOL);
    printf('Metric Kind: ' . $descriptor->getMetricKind() . PHP_EOL);
    printf('Value Type: ' . $descriptor->getValueType() . PHP_EOL);
    printf('Unit: ' . $descriptor->getUnit() . PHP_EOL);
    printf('Labels:' . PHP_EOL);
    foreach ($descriptor->getLabels() as $labels) {
        printf('  %s (%s) - %s' . PHP_EOL,
            $labels->getKey(),
            $labels->getValueType(),
            $labels->getDescription());
    }
}

Python

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

client = monitoring.Client()
print(client.fetch_metric_descriptor(type_))

Java

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Your Google Cloud Platform project ID
String projectId = System.getProperty("projectId");

final MetricServiceClient client = MetricServiceClient.create();
MonitoredResourceDescriptorName name = MonitoredResourceDescriptorName.create(projectId, type);
MonitoredResourceDescriptor response = client.getMonitoredResourceDescriptor(name);

System.out.println("Printing monitored resource descriptor: ");
System.out.println(response);

See Troubleshooting API calls if you have difficulty.

Listing monitored resources

Monitored resource represent cloud entities that can be monitored. By browsing the existing monitored resource types, you can find the kinds of entities that have metrics. There are presently about 30 different monitored resource descriptors.

For an introduction to metric descriptors and monitored resources, see Metrics, Time Series, and Resources.

Protocol

To get a current list of monitored resource types from the Stackdriver Monitoring API, use monitoredResourceDescriptors.list with the following sample parameters:

  • name: projects/{your-project-id}
  • fields: resourceDescriptors.type

The following sample response shows some of the returned monitored resource types:

{
 "resourceDescriptors": [
  {
   "type": "api"
  },
  {
   "type": "aws_cloudfront_distribution"
  },
  {
   "type": "aws_dynamodb_table"
  },
  {
   "type": "aws_ebs_volume"
  },
  ...
}

Try It!

C#

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

        public static object ListMonitoredResources(string projectId)
        {
            Console.WriteLine("Starting to List Monitored Resources...");
            MetricServiceClient client = MetricServiceClient.Create();
            ProjectName projectName = new ProjectName(projectId);

            PagedEnumerable<ListMonitoredResourceDescriptorsResponse, MonitoredResourceDescriptor>
                resources = client.ListMonitoredResourceDescriptors(projectName);
            if (resources != null)
            {
                foreach (MonitoredResourceDescriptor resource in resources.Take(10))
                {
                    Console.WriteLine($"{resource.Name}: {resource.DisplayName}");
                }
            }
            else { Console.WriteLine("No resources found."); }
            return 0;
        }

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const Monitoring = require('@google-cloud/monitoring');

// Instantiates a client
const client = Monitoring.v3().metricServiceClient();

// The Google Cloud Platform project on which to execute the request
// const projectId = 'YOUR_PROJECT_ID';

const request = {
  name: client.projectPath(projectId)
};

// Lists monitored resource descriptors
client.listMonitoredResourceDescriptors(request)
  .then((results) => {
    const descriptors = results[0];

    console.log('Monitored Resource Descriptors:');
    descriptors.forEach((descriptor) => console.log(descriptor.name));
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

Python

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

client = monitoring.Client()
for descriptor in client.list_resource_descriptors():
    print(descriptor.type)

Java

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Your Google Cloud Platform project ID
String projectId = System.getProperty("projectId");

final MetricServiceClient client = MetricServiceClient.create();
ProjectName name = ProjectName.create(projectId);

ListMonitoredResourceDescriptorsRequest request = ListMonitoredResourceDescriptorsRequest
    .newBuilder()
    .setNameWithProjectName(name)
    .build();

System.out.println("Listing monitored resource descriptors: ");

PagedResponseWrappers.ListMonitoredResourceDescriptorsPagedResponse response = client
    .listMonitoredResourceDescriptors(request);

for (MonitoredResourceDescriptor d : response.iterateAll()) {
  System.out.println(d.getType());
}

See Troubleshooting API calls if you have difficulty.

Getting resource details

To get more details about monitored resource types, use the monitoredResourceDescriptors.get method.

Protocol

To get the details of the gce_instance resource type, use the following parameter to monitoredResourceDescriptors.get method:

  • name: projects/{your-project-id}/monitoredResourceDescriptors/gce_instance

The following sample response shows the monitored resource descriptor object:

{
 "type": "gce_instance",
 "name": "projects/{your-project-id}/monitoredResourceDescriptors/gce_instance"
 "displayName": "GCE Instance",
 "description": "A virtual machine instance hosted in Google Compute Engine (GCE).",
 "labels": [
  {
   "key": "project_id",
   "description": "The identifier of the GCP project associated with this resource (e.g., {your-project-id})."
  },
  {
   "key": "instance_id",
   "description": "The VM instance identifier assigned by GCE."
  },
  {
   "key": "zone",
   "description": "The GCE zone in which the VM is running."
  }
 ],
}

Try It!

C#

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

public static object GetMonitoredResource(string projectId, string resourceId)
{
    MetricServiceClient client = MetricServiceClient.Create();
    MonitoredResourceDescriptorName name = new MonitoredResourceDescriptorName(projectId, resourceId);
    var response = client.GetMonitoredResourceDescriptor(name);
    string resource = JObject.Parse($"{response}").ToString();
    Console.WriteLine($"{ resource }");
    return 0;
}

Node.js

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Imports the Google Cloud client library
const Monitoring = require('@google-cloud/monitoring');

// Instantiates a client
const client = Monitoring.v3().metricServiceClient();

// The Google Cloud Platform project on which to execute the request
// const projectId = 'YOUR_PROJECT_ID';

// "resourceType" should be a predefined type, such as "cloudsql_database"
// const resourceType = 'some_resource_type';

const request = {
  name: client.monitoredResourceDescriptorPath(projectId, resourceType)
};

// Lists monitored resource descriptors
client.getMonitoredResourceDescriptor(request)
  .then((results) => {
    const descriptor = results[0];

    console.log(`Name: ${descriptor.displayName}`);
    console.log(`Description: ${descriptor.description}`);
    console.log(`Type: ${descriptor.type}`);
    console.log('Labels:');
    descriptor.labels.forEach((label) => {
      console.log(`  ${label.key} (${label.valueType}) - ${label.description}`);
    });
  })
  .catch((err) => {
    console.error('ERROR:', err);
  });

Python

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

client = monitoring.Client()
print(client.fetch_resource_descriptor(type_))

Java

For more on installing and creating a Stackdriver Monitoring client, refer to Stackdriver Monitoring Client Libraries.

// Your Google Cloud Platform project ID
String projectId = System.getProperty("projectId");

final MetricServiceClient client = MetricServiceClient.create();
MonitoredResourceDescriptorName name = MonitoredResourceDescriptorName.create(projectId, type);
MonitoredResourceDescriptor response = client.getMonitoredResourceDescriptor(name);

System.out.println("Printing monitored resource descriptor: ");
System.out.println(response);

See Troubleshooting API calls if you have difficulty.

Finding resources

Monitored resource objects are included in time series data. You can usually guess which metrics include monitored resources of specific types. For example, if you want to see a gce_instance monitored resource, look at time series data from a metric like compute.googleapils.com/instance/cpu/utilization. After you've identified a likely metric time series, see Reading time series data.

Monitor your resources on the go

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

Send feedback about...

Stackdriver Monitoring