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