Skip to main content

Filtering Traces

from v9.4status Work-in-Progress

Filtering hides spans without discarding the graph relationships that still explain the visible trace. The original normalized data stays immutable; filter state lives in TraceGraph.

Filter flow​

  1. Start from the loaded graph.
  2. Evaluate text filters and configured topology filters.
  3. Record filter provenance in row-aligned process tables.
  4. Build the visible graph projection used by layout and rendering.
  5. Contract parent and dependency paths onto surviving visible representatives.

spanFilter accepts literal prefixes and explicit regular expressions:

const filters = ['rpc.request_', 'packages/example_tracing/base.py', '/^executeRpc-\\d+$/'];

Filter families​

  • name and regexp filtering marks spans matched by text rules
  • source filtering marks spans matched by source metadata
  • topology filtering contracts structures such as overlapping parent spans or similar-duration chains
  • time-window hiding is separate from graph filtering and should come from application window metadata

Why refs matter​

Use SpanRef when checking filtered state. Source span IDs may collide across processes, while a ref identifies one exact loaded row.

Useful TraceGraph calls include:

  • spanIsFiltered(...)
  • spanFilterReason(...)
  • getTraceSpanFilteredParentRef(...)
  • getTraceSpanFilterNavigation(...)
  • searchSpans(...)

Invalidation​

Rebuild TraceGraph when source data or filter semantics change. Do not rebuild it for collapse toggles, timing-key changes, or pure render settings. Those belong to layout, geometry, or render updates.

Read TraceGraph for the runtime methods and TraceVisSettings for settings invalidation groups.