From abdea807ad78b52d96bae084c8c857700c83781f Mon Sep 17 00:00:00 2001 From: Brandon Bellero Date: Mon, 1 Jun 2026 05:11:45 -0400 Subject: [PATCH] Document trace filtering behavior across span hierarchy --- running-requests/traces.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/running-requests/traces.mdx b/running-requests/traces.mdx index 10364da..5e67d99 100644 --- a/running-requests/traces.mdx +++ b/running-requests/traces.mdx @@ -222,3 +222,13 @@ if __name__ == "__main__": ``` ![Group nests spans](/images/traces/nested-spans.png) + +## Filtering Traces by Span Attributes + +The trace list can be filtered by metadata and resource attribute values. Filters search across the **entire span hierarchy** — a trace appears in results if any span within it (root or child) carries a matching attribute. + +For example, if only a nested LLM call span has `{"environment": "production"}` in its attributes, filtering the trace list by `environment = production` will still surface the parent trace in results, even if the root span itself does not carry that attribute. + +### Adding Filters from the Span Detail Panel + +When you open a span in the trace detail view, hovering over a scalar metadata or resource value reveals a filter button. Clicking it adds the key-value pair as an active filter on the trace list. The filter button appears only for top-level scalar values (string, number, or boolean). Nested objects and arrays are displayed for inspection but cannot be used as direct filter targets.