Trace and usage artifacts
The protocol-owned observability model emitted around routing and execution.
role-model treats observability as protocol-owned data, not as leftover implementation logs.
The three artifact types
| Artifact | Purpose |
|---|---|
TraceSpan | timed phases such as eligibility, scoring, selection, provider decode, fallback, or retry |
TraceEvent | point events that announce things such as a decision being created, a span opening or closing, or a profile update |
UsageEvent | accounting and execution outcome data such as tokens, latency, provider, endpoint, and cost estimate |
TraceSpan
TraceSpan captures duration and status. The schema includes baseline span types such as:
router.eligibilityrouter.scoringrouter.selectionrouter.fallbackrouter.retryprovider.loadprovider.queueprovider.prefillprovider.decodetool.executionrequest.failure
This lets routing and execution be described as phases instead of opaque wall-clock time.
TraceEvent
TraceEvent is the lighter-weight lifecycle signal. Baseline event_type values include:
router.decision.createdtrace.span.openedtrace.span.closedusage.event.createdprofile.sample.recordedprofile.updated
These events connect the decision, trace, usage, and profile-update layers together.
UsageEvent
UsageEvent records execution/accounting facts such as:
endpoint_idprovider_kindtokens_intokens_outlatency_ms- optional
cost_estimate - optional
error_class - optional
sample_source
This is how routing decisions become durable usage evidence.
Linking semantics
All three artifact families use shared identifiers to remain joinable:
request_idrouting_decision_idtrace_idspan_idendpoint_id
That joinability is the key reason these artifacts belong in the protocol model rather than in custom log formats that every host invents independently.