feat(metrics-llm): record llm interactions, time to first token and incomplete usage, with guarded attributes

[jfallows]

Description

Adds three metrics to the llm metric group and lets every llm.* metric label its series from telemetry.attributes.

Stacked on aklivity/zilla#2681, which is stacked on #2680 and #2679. This branch is rebased onto #2681's head (claude/gifted-cray-r71cze, currently 98044e968), so until those merge the "Files changed" tab also shows their commits. Only the 6 commits after 98044e968 belong to this PR; once they merge, the branch rebases onto develop and the diff reduces to those.

Metrics

• llm.interactions (counter): one per completed, aborted or rejected exchange.
• llm.time.to.first.token (histogram, ns): request BEGIN to the first reply DATA frame.
• llm.usage.incomplete (counter): an exchange whose reply ends with no usage reported, or aborts after the reply opened.

Attributes

• A binding's telemetry.attributes now apply to all llm.* metrics. The expressions are the existing guarded forms, ${guarded['<guard>'].identity} and ${guarded['<guard>'].attributes.<name>}, resolved against the named guard with the authorization carried on the request BEGIN. The guard is looked up through the binding's own name resolution, so a claim a guard exposes as an attribute can label usage per tenant.
• No llm-specific expression is added. The binding is already identified by the series' binding label.

Engine

• MetricContext.supply(recorder, attributes, resolveId) is a defaulted overload that also receives the binding's name resolver, so a context that evaluates attribute expressions naming other configuration (a guard) can resolve the name. It defaults to the existing attributes overload, so existing metric contexts are unaffected.
• The test binding relays FLUSH frames with the stream's authorization like every other frame it forwards. It sent them with authorization 0, so a stream accepted for a non-zero authorization was aborted when an advisory flush crossed it.

The llm.proxy example records the new metrics, the golden schema lists them, and the README documents the attribute expressions, including a JWT claim as a metric attribute.

How this differs from #2587 as filed

The issue was written before the usage shape and the first metrics landed, so the delivered scope differs in these ways:

• Usage source. The issue reads usage from a LlmFlushEx case. Usage is carried on LlmEndEx (a completed reply) and LlmAbortEx (an aborted one), so the partial-usage counter is driven by those frames.
• Token metrics. They already exist as per-exchange histograms from feat(metrics-llm): record llm token usage, duration and active requests #2611 (llm.tokens.*), not counters. A token count a dialect does not report is left unrecorded, never recorded as 0, so a dialect reporting no usage still produces an interaction count with absent token fields.
• Outcome dimension. The interaction counter is not split by outcome in the metric itself. Its series carry the labels a binding configures through guarded attributes, plus the binding label. An outcome split is not part of this change.
• Binding identity. There is no expression for it: the series' binding label already identifies the llm binding that served the request.
• Guard claims. They use the existing guarded expression form rather than a new one, which needed only the engine overload above.
• examples/llm.proxy/etc/test/verify.py does not assert the new metrics; I could not run the compose stack in this environment.

Fixes #2587

Testing

• Unit: MetricContextTest (the overload delegates), LlmMetricGroupTest (names, kinds, units, descriptions).
• LlmMetricsIT runs the binding-llm.spec application scripts through a type: test proxy (the llm binding is not loaded): usage (OpenAI and Anthropic, streaming and not), abort and rate-limit rejection, plus a guarded-attribute scenario. That scenario uses a test guard configured with credentials, so it resolves an identity only for a non-zero authorization; the openai.usage scripts take property authorization 0L and the IT overrides it to 1L. It fails if the request's authorization is not passed to the guard, and the exporter asserts the tenant and user labels on every series.
• On this rebase: the engine MetricContextTest and GuardFactoryTest, metrics-llm.spec (7) and metrics-llm (16, including the ITs) pass, with checkstyle, license headers and the JaCoCo gate on for metrics-llm. I have not re-run binding-llm; the example jobs run in CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JmtXgg57sb1dimx5No9hHF

[jfallows]

CI on adf900530d: 41 of 43 jobs passed, 1 skipped, and testing (tcp.echo.classify) failed.

The failure is not from this PR. The zilla-tcp-echo-classify-presidio-analyzer-1 container never became healthy (dependency failed to start: container ... is unhealthy after about 13 minutes), so the example never started. That example involves no llm binding or metrics, and nothing in this diff touches it. I've re-run the failed job once. I'll fix it in a follow-up push if it fails again for a reason that points at this change.

---

Generated by Claude Code

[jfallows]

The re-run of testing (tcp.echo.classify) failed the same way, and the analyzer log shows the same signature: gunicorn logs "Control socket listening" and never "Booting worker", so the health probe never gets an answer. It isn't caused by this PR.

The fix is in aklivity/zilla#2711 (--no-control-socket on the analyzer). I've ported that one commit, 1be8ba8f2b, onto this branch so CI can go green. It carries the same subject as in #2711 and drops out when this rebases after #2711 merges. It's the only commit here outside the metrics-llm change, besides the stacked PRs' commits.

---

Generated by Claude Code