feat(telemetry): add sampling and validator tracing spans via hooks

[ajbozarth]

Pull Request

Issue

Fixes #1050

Description

Adds sampling and validation tracing spans, emitted by two new plugins (SamplingTracingPlugin, ValidationTracingPlugin) that subscribe to the sampling and validation lifecycle hooks already dispatched by BaseSamplingStrategy.sample() and avalidate().

#1050 also named the formatter, which is intentionally left out: it's a synchronous render step with no duration or place in the trace tree of its own, so it isn't a meaningful span. The data worth capturing from that path — the prompt template and its variables — is component-level information the formatter merely renders, and it belongs as attributes on the backend chat span, which is #1067's scope (llm.prompt_template.*).

Two new plugins in mellea/telemetry/tracing_plugins.py:

• SamplingTracingPlugin — emits a sampling application span per sampling loop, opened on sampling_loop_start and closed on sampling_loop_end. Each attempt and repair is recorded as a span event (iteration / repair) rather than a child span, so the markers stay on the one span alongside the backend chat spans the same calls emit.
• ValidationTracingPlugin — emits a validation application span per requirement-validation batch, opened on validation_pre_check and closed on validation_post_check.

Supporting changes:

• Correlation ids: added observe-only sampling_id / validation_id fields to the sampling and validation hook payloads, minted once at each dispatch site (sample() and avalidate()) so the paired open/close hooks correlate.
• Span helpers in tracing.py: start/finish_sampling_span, start/finish_validation_span, and a generic add_span_event (renamed from the streaming-specific add_streaming_event, now shared).
• Error-path span closure: sample() and avalidate() fire their end hook from a try/finally with an optional exception field, so a raised loop/check still closes its span. ERROR status is driven only by an exception — a routine budget-exhausted loop or failing check closes with default status. The metrics and builtin_debug plugins skip the outcome on the exception path.
• Docs: documented the sampling and validation spans and corrected the span-hierarchy diagrams in tracing.md / telemetry.md (they referenced a requirement_validation span that never existed — the real span is validation).

Notes for reviewers

• Nesting is session → action → sampling → {chat, validation} on Python 3.12+; on ≤3.11 hook-attached spans collapse to session (same documented degradation as all existing tracing plugins).
• The add_streaming_event → add_span_event rename updates StreamingTracingPlugin's call sites; no compat shim.
• The sampling span covers strategies that use the BaseSamplingStrategy loop. Strategies that override sample() with a custom loop (SOFAI, budget-forcing, majority-voting) don't emit it — that coupling is tracked as a follow-up in fix(sampling): sampling span missing for strategies that override sample() #1487, out of scope here.
• Telemetry plugin priorities moved from the 40s/50s into the 1040s/1050s so they run after user hooks and observe the final post-hook payload state (fixes sampling/validation spans reporting pre-mutation loop_budget/requirement_count). Relative order is unchanged: tracing (1040–1045) still precedes metrics (1050–1057).

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool