This page describes how to useAPI metrics to track and understand your usageof Google APIs and Google Cloud APIs.

Google APIs produce detailed usage metrics that can help you:

• Track and understand your usage of Google APIs.
• Monitor performance of your applications and Google APIs.
• Discover problems between your applications and Google APIs.

It can dramatically speed up resolution times when you troubleshoot problemsor need technical support from Google.

The metrics that Google APIs produce are the standard signals that Google'sown Site Reliability Engineers use to assess the health of a service.These metrics covers request counts, error rates, total latencies, backendlatencies, request sizes, and response sizes. For the API metric definitions,seeCloud Monitoring documentation.

You can view API metrics in two places:API Dashboard andCloud Monitoring. The metrics you see are specific toyour project, and they don't reflect the overall service status.

Using the API Dashboard

The simplest way to view your API metrics is to use the Google Cloudconsole'sAPI Dashboard. You can see anoverview of all your API usage, or you can drill down to your usage of aspecific API.

To see an overview of your API usage:

1. Visit Cloud console'sAPIs and Services section.The main API Dashboard is displayed by default. In this page you cansee all the APIs you currently have enabled for your project,as well as overview charts for the following metrics:

   • Traffic: the number of requests per second made by or about yourproject to enabled APIs
   • Errors: the percentage of requests to enabled APIs thatresulted in errors
   • Median latency: the median latency for requests to enabled APIs,if available".

To see API metrics in Metrics Explorer, selectConsumed API as the resourcetype, then select one of theserviceruntime metrics. Then use the filter andaggregation options to refine your data.After you've found the API usage information you want, you can useCloud Monitoring to create custom dashboards and alerts that will help youcontinue to monitor and maintain a robust application. You can find out how todo this in the following pages:

• Building charts
• Introduction to alerting
• Managing alerting policies

For more information, seeMetrics Explorer.

Troubleshooting with API metrics

API metrics can be particularly useful if you need to contact Google whensomething goes wrong, and may even show you that you don't need to contactsupport at all. For example:

• If all of your calls to a service are failing for a single credential ID, butnot any other, chances are there is something wrong with that account that youcan easily fix yourself without opening a ticket.
• You’re troubleshooting a problem with your app, and notice a correlationbetween your application’s degraded performance and a sustained increase inthe 50th percentile latency of a critical GCP service. Definitely call us andpoint us to this data so we can start working on the problem as quickly aspossible.
• The latencies for a GCP service report look good and unchanged from before,but your in-app metrics report that the latency on calls to the service isabnormally high. That tells you that there is some trouble in the network.Call your network provider (in some cases, Google) to get the debuggingprocess started.

Best practices

While API metrics are an extremely useful tool, there are issues you need toconsider to make sure they provide useful information, particularly when settingup alerts based on metric values. The following best practices will help you getthe most from API metrics data.

Is latency causing a problem?

While some services are quite latency-sensitive, for others scale andreliability matter more. Some APIs,Cloud Storage orBigQuery for example, can have a couple of seconds of highlatency without customers noticing. With data from API metrics, you can learnwhat your users need from a given service.

Look for changes from the norm

Before you decide to alert on a particular metric value, consider what actuallycounts as unusual behavior. Looking at your API metrics can show you thatlatency results for most services fall within a normal distribution: a big humpin the middle, and outliers on either side. The metrics will help you understandthe normal distribution so that you can engineer your app to work well withinthe distribution curve. Metrics can also help you correlate distribution changeswith times where your app is not working as intended, to help you find the rootcause of an issue. We expect the 99th percentile to look very different than themedian — what we don’t expect are dramatic changes in those percentilesover time.

Also you may see that some kinds of requests take longer than others. If themedian size of a photo uploaded to Google Photos is 4 MB, but you normallyupload 20 MB RAW files, your average time to upload 20 photos is likely to besubstantially worse than that of most users, but is stillyour normalbehavior.

All this means that it's not particularly useful to alert the first time asecond-long RPC or 5xx HTTP call is detected. Instead, when investigating aGoogle service as a possible cause for an issue your application isexperiencing, compare the return codes and latency rates over time andlook for sustained changes from the norm that are correlated with observed issues in your application.

Traffic rate

API metrics are most useful where you have a high volume of traffic going to theAPI. If you call a service only intermittently, your API metrics won’t bestatistically valid and won’t give you meaningful triage information.

For example, if you want to track the 99.5th percentile latency for a service,and you only do 100 calls an hour, watching the measurement over a two hourperiod would only give you one data point to represent the 99.5th percentile,which won't tell you much about the normal behavior of the API or yourapplication. Make sure the traffic rate, the percentile you are tracking,and the time window you are considering generate many data points of interestor the monitoring data will not be helpful to you.

Supported APIs

All Google APIs and Google Cloud APIs, as well as APIs built on top of CloudEndpoints and API Gateway, support API metrics. If you are an API consumer,you can view the Consumed API metrics in theAPI Dashboard. If youare an API producer, you can view the Produced API metrics in theEndpoints Dashboard.