Reporting Monitoring Metrics

This page describes how to use Service Infrastructure to enable managed services to generate monitoring data to send to service producer and service consumer projects. Monitoring provides visibility into the performance, uptime, and overall health of individual managed services.

The Service Control API accepts metrics, which it batches and forwards to Cloud Monitoring. Monitoring ingests these metrics and generates insights via dashboards, charts, and alerts.

Whereas Monitoring alone allows a managed service to generate monitoring data for use by you as a developer of the managed service, the Service Control API also lets you generate monitoring data which is intended for your users. This makes it possible for your users to understand and diagnose use of your managed service.

Note, this guide is for monitoring metrics defined by managed services. Monitoring Custom Metrics cannot be reported via Service Control API. To report Custom Metrics, you need to follow the Monitoring guide.

Configuring monitoring

Before you send monitoring data to the Service Control API, you need to specify three different bits of information in your service configuration:

  • Monitored resources: A monitored resource represents a cloud entity that producer some monitoring data. To define a monitored resource in the service configuration, see monitored_resource.proto for the technical specification. We strongly recommend you to use the same monitored resource for both monitoring and logging.

  • Metrics: You can report one or more metrics. Each metric represents a single piece of state whose value is tracked over time. See metric.proto for the technical specification to define a metric.

  • Monitoring configuration: Lets you specify the metrics associated with individual monitored resources and the service producer or service consumer project where each metric should be sent. See monitoring.proto for details.

The following example of service configuration defines a monitored resource and a metric.

# The definition of the monitored resource to be used.
monitored_resources:
- type: library.appspot.com/Branch
  description: A library branch.
  display_name: Library Branch
  launch_stage: ALPHA
  labels:
  - key: resource_container
    description: The Google Cloud resource container (ie. project id) for
    the branch.
  - key: location
    description: The Google Cloud region the branch is located.
  - key: branch_id
    description: The ID of the branch.

# The definition of the metrics to be used.
metrics:
- name: library.appspot.com/book/num_overdue
  display_name: Books Overdue
  description: The current number of overdue books.
  launch_stage: ALPHA
  metric_kind: GAUGE
  value_type: INT64
  unit: 1
- name: library.googleapis.com/book/returned_count
  display_name: Books Returned
  description: The count of books that have been returned.
  launch_stage: ALPHA
  metric_kind: DELTA
  value_type: INT64
  unit: 1

# The monitoring configuration.
monitoring:
  producer_destinations:
  - monitored_resource: library.appspot.com/Branch
    metrics:
    - library.googleapis.com/book/returned_count
  consumer_destinations:
  - monitored_resource: library.appspot.com/Branch
    metrics:
    - library.appspot.com/book/num_overdue

After you have authored such configuration, you will need to follow Managing Service Configurations and Managing Service Rollouts to push the service configuration to Service Management API, which will configure the monitored resource and metric definitions in Cloud Monitoring.

Reporting metrics

After the service configuration push finishes, you can call the Service Control API to report metrics. The following example uses the gcurl command to demonstrate the call. For information on how to set this up, see Getting Started with the Service Control API.

gcurl -d "{
  'operations': [ {
    'operationId': '8356d3c5-f9b5-4274-b4f9-079a3731e6e5',
    'operationName': 'Return books',
    'consumerId': 'projects/library-consumer',
    'startTime': '`date +%FT%T%:z`',
    'endTime': '`date +%FT%T%:z --date="5 seconds"`',
    'labels': {
      'location': 'us-east1',
      'branch_id': 'my-test-library-branch'
    },
    'metricValueSets': [ {
      'metricName': 'library.googleapis.com/book/returned_count',
      'metricValues': [ { 'int64Value': '23' } ]
    } ]
  } ]
}" https://servicecontrol.googleapis.com/v1/services/endpointsapis.appspot.com:report