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 produces 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