Menu
DocumentationGrafana CloudInstrument and send dataTracesMetrics summary API
Grafana Cloud

Metrics summary API

Warning

The Metrics summary API is an experimental feature that is disabled by default. To enable it, contact Grafana Support. Grafana Labs offers support for this feature on a best-effort basis, and breaking changes might occur prior to the feature being made generally available.

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.

Request

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

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

Example:

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, see Create a Cloud Access Policy.

Example:

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 &.

NameExamplesDefinitionRequired?
q{ resource.service.name = "foo" && span.http.status_code != 200 }The TraceQL query with full syntax. All spans matching this query are included in the calculations. Any valid TraceQL query is supported.Yes
groupByname
.foo
resource.namespace
span.http.url,span.http.status_code
The TraceQL value(s) to group by. Any valid intrinsic or attribute with scope. To group by multiple values use a comma-delimited list.Yes
start1672549200Start of time range in unix seconds. If not specified, then all recent data is queried.No
end1672549200End of the time range in unix seconds. If not specified, then all recent data is queried.No

Example:

bash 
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:

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.

Note

The uint64 fields cannot be fully expressed by JSON numeric values so the fields are serialized as strings.

Example:

JavaScript 
{
   "summaries": [
       {
           "spanCount": "20",
           "series" : [
               {
                   "key": ".attr1",
                   "value": {
                       "type": 5,
                       "s": "foo"
                   },
               },
               ...
           ],
           "p99": "68719476736",
           "p95": "1073741824",
           "p90": "1017990479",
           "p50": "664499239"
       },
FieldNotes
summariesThe list of metrics per group.
.spanCountNumber of spans in this group.
.errorSpanCountNumber of spans with status=error. (This field will not be present if the value is 0.)
.seriesThe unique values for this group. A key/value pair will be returned for each entry in groupBy.
.keyKey name.
.valueValue with TraceQL underlying type.
.typeData type enum defined here (This field will not be present if the value is 0.)
0 = nil
3 = integer
4 = float
5 = string
6 = bool
7 = duration
8 = span status
9 = span kind
.nPopulated if this is an integer value.
.sPopulated if this is a string value.
.fPopulated if this is a float value.
.bPopulated if this is a boolean value.
.dPopulated if this is a duration value.
.statusPopulated if this is a span status value.
.kindPopulated if this is a span kind value.
.p99The p99 latency of this group in nanoseconds.
.p95The p95 latency of this group in nanoseconds.
.p90The p90 latency of this group in nanoseconds.
.p50The p50 latency of this group in nanoseconds.