Documentation Grafana Cloud Instrument and send data Traces Metrics summary API

Metrics summary API

This document explains how to use the metrics summary API in Grafana Cloud Traces. This API returns RED metrics (span count, erroring span count, and latency information) for kind=server spans sent to Grafana Cloud Traces in the last hour, grouped by a user-specified attribute.

Activate metrics summary

The Metrics summary API is an experimental feature that is disabled by default. To enable it, contact Grafana Support.

Request

To make a request to this API, use the following URL:

Copy

https://$URL/api/metrics/summary

Example:

Copy

GET https://tempo-dedicated-02-prod-us-central-0.grafana.net/tempo/api/metrics/summary

To get the value of $URL:

1. Go to grafana.com.
2. Select Details for your stack.
3. Select Details for your Tempo tracing service.
4. Use the value under URL in the Grafana Data Source settings.

Authentication

The API uses HTTP basic authentication.

For your username, use the User value in the Grafana Data Source settings.

For your password, use a Cloud Access Policy token. Create an access policy with the traces:read scope and then create a token for that access policy. Use the token as your password. For more information on how to do this, refer to Create a Cloud Access Policy.

Example:

Copy

GET -u "$USER:$PASSWORD" "$URL/api/metrics/summary"

Replace $USER, $PASSWORD, and $URL with the values for your username, password, and URL.

Query parameters

All query parameters must be URL-encoded to preserve non-URL-safe characters in the query such as &.

Example:

bash Copy

curl -u "$USER:$PASSWORD" "$URL/api/metrics/summary" --data-urlencode 'q={resource.service.name="checkout-service"}' --data-urlencode 'groupBy=name'

Response

The Tempo response is a SpanMetricsSummary object defined in tempo.proto, relevant section pasted below:

Copy

message SpanMetricsSummaryResponse {
  repeated SpanMetricsSummary summaries = 1;
}

message SpanMetricsSummary {
  uint64 spanCount = 1;
  uint64 errorSpanCount = 2;
  TraceQLStatic static = 3;
  uint64 p99 = 4;
  uint64 p95 = 5;
  uint64 p90 = 6;
  uint64 p50 = 7;
}

message TraceQLStatic {
  int32 type = 1;
  int64 n = 2;
  double f = 3;
  string s = 4;
  bool b = 5;
  uint64 d = 6;
  int32 status = 7;
  int32 kind = 8;
}

The response is returned as JSON following standard protobuf->JSON mapping rules.

Example:

JavaScript Copy

{
   "summaries": [
       {
           "spanCount": "20",
           "series" : [
               {
                   "key": ".attr1",
                   "value": {
                       "type": 5,
                       "s": "foo"
                   },
               },
               ...
           ],
           "p99": "68719476736",
           "p95": "1073741824",
           "p90": "1017990479",
           "p50": "664499239"
       },