Updated the tag values v2 docs (#2787)

* Updated the tag values v2 docs Clarified that a feature flag must be enabled for this `q` parameter to be accepted * Update _index.md * Apply suggestions from code review Adding Kim's suggestions Co-authored-by: Kim Nylander <[email protected]> * Update docs/sources/tempo/api_docs/_index.md --------- Co-authored-by: Kim Nylander <[email protected]>
grafana · Aug 22, 2023 · 7752ae3 · 7752ae3
1 parent 8357aff
commit 7752ae3
Showing 1 changed file with 19 additions and 16 deletions.
diff --git a/docs/sources/tempo/api_docs/_index.md b/docs/sources/tempo/api_docs/_index.md
@@ -374,22 +374,6 @@ This endpoint retrieves all discovered values and their data types for the given
 The endpoint is available in the query frontend service in a microservices deployment, or the Tempo endpoint in a monolithic mode deployment. This endpoint is similar to `/api/search/tag/<tag>/values` but operates on TraceQL identifiers and types. 
 See [TraceQL]({{< relref "../traceql" >}}) documentation for more information.
 
-The URL query parameters support the following values:
-
-- `q = (TraceQL query)`: Url encoded [TraceQL query]({{< relref "../traceql" >}}).
-  - If a query is provided, results are filtered down to only those traces that match the query.
-  - Queries can be incomplete (eg. `{ .cluster = }`).
-    Tempo will extract only the valid matchers and build a valid query.
-  - Only queries with a single selector `{}` and AND `&&` operators are supported.
-    - Example supported: `{ .cluster = "us-east-1" && .service = "frontend" }`
-    - Example unsupported: `{ .cluster = "us-east-1" || .service = "frontend" } && { .cluster = "us-east-2" }`
-
-The following request returns all discovered service names.
-
-```
-GET /api/v2/search/tag/.service.name/values?q="{span.http.method='GET'}"
-```
-
 #### Example
 
 This example queries Tempo using curl and returns all discovered values for the tag `service.name`.
@@ -422,6 +406,25 @@ $ curl http://localhost:3200/api/v2/search/tag/.service.name/values | jq .
 }
 ```
 
+#### Filtered tag values
+If you set Tempo's `autocomplete_filtering_enabled` configuration parameter to `true` (default value is `false`), you can provide an optional URL query parameter, `q` to your request.
+The `q` parameter is a URL-encoded [TraceQL query]({{< relref "../traceql" >}}.
+If provided, the tag values returned by the API are filtered to only return values seen on spans matching your filter parameters. 
+
+Queries can be incomplete: for example, `{ .cluster = }`. Tempo extracts only the valid matchers and build a valid query. 
+
+Only queries with a single selector `{}` and AND `&&` operators are supported.
+  - Example supported: `{ .cluster = "us-east-1" && .service = "frontend" }`
+  - Example unsupported: `{ .cluster = "us-east-1" || .service = "frontend" } && { .cluster = "us-east-2" }`
+
+The following request returns all discovered service names on spans with `span.http.method=GET`:
+
+```
+GET /api/v2/search/tag/.service.name/values?q="{span.http.method='GET'}"
+```
+
+If a particular service name (for example, `shopping-cart`) is only present on spans with `span.http.method=POST`, it would not be included in the list of values returned. 
+
 ### Query Echo Endpoint
 
 ```