From 0ae2a8cb23037b46056d9d7372fe339794398841 Mon Sep 17 00:00:00 2001 From: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com> Date: Wed, 13 Nov 2024 12:30:40 -0500 Subject: [PATCH] [DOC] Add clarification for metrics summary and traceQL metrics (#4316) * Add clarification for metrics summary and traceQL metrics * Apply suggestions from code review Co-authored-by: Jennifer Villa * Update docs/sources/tempo/api_docs/metrics-summary.md --------- Co-authored-by: Jennifer Villa (cherry picked from commit d730dfc91f3ccb57cca7b9637687a18392b85305) --- .../sources/tempo/api_docs/metrics-summary.md | 31 +++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/sources/tempo/api_docs/metrics-summary.md b/docs/sources/tempo/api_docs/metrics-summary.md index 03b0701103b..4fac045d58c 100644 --- a/docs/sources/tempo/api_docs/metrics-summary.md +++ b/docs/sources/tempo/api_docs/metrics-summary.md @@ -10,8 +10,8 @@ weight: 600 # Metrics summary API {{< admonition type="warning" >}} -The metrics summary API is deprecated as of Tempo 2.7. Features powered by the metrics summary API, like the Aggregate by table, are also deprecated in Grafana Cloud and Grafana 11.3 and later. -It will be removed in a future release. +The metrics summary API is deprecated as of Tempo 2.7. Features powered by the metrics summary API, like the [Aggregate by table](https://grafana.com/docs/grafana//datasources/tempo/query-editor/traceql-search/#optional-use-aggregate-by), are also deprecated in Grafana Cloud and Grafana 11.3 and later. +It will be removed in a future release. {{% /admonition %}} This document explains how to use the metrics summary API in Tempo. @@ -19,6 +19,33 @@ This API returns RED metrics (span count, erroring span count, and latency infor {{< youtube id="g97CjKOZqT4" >}} +## Deprecation in favor of TraceQL metrics + +The metrics summary API is now redundant given the release of TraceQL metrics. +This API is therefore being deprecated to reduce our maintenance burden. + +TraceQL metrics queries are significantly more powerful than what metrics summary API provides. +TraceQL metrics can look at arbitrary time windows (not just the last hour), return time series information (rather than just a single instant value over the past hour), and can look at all spans (not just `kind=server`). + +To provide an example, if you were to aggregate by the attribute `resource.cloud.region` with the metrics summary API, you could get the same results with a couple TraceQL queries: + +Rate of requests by `resource.cloud.region` +``` +{ } | rate() by (resource.cloud.region) +``` + +Error rate by `resource.cloud.region` +``` +{ status=error } | rate() by (resource.cloud.region) +``` + +The 50th, 90th, and 99th percentile latencies (for example, p99, p90, and p50) by `resource.cloud.region`: +``` +{ } | quantile_over_time(duration, .99, .9, .5) by (resource.cloud.region) +``` + +If you want something faster than typing these queries out in Explore's code mode, use [Explore Traces](https://grafana.com/docs/grafana//explore/simplified-exploration/traces/), a queryless experience for navigating your trace data stored in Tempo and powered by TraceQL metrics queries under the hood. + ## Activate metrics summary To enable the (deprecated) metrics summary API, you must turn on the local blocks processor in the metrics generator.