Python SDK
Annotations
Attach metrics to a trace for analytics, eval, and slicing. Latency, quality, pass/fail — anything you want to filter by later.
st.annotate(
trace_id=trace_id,
name="latency_ms",
value=842.0,
data_type="numeric",
)Signature
st.annotate(
*,
trace_id: str,
name: str,
value: float | str | bool,
data_type: str | AnnotationDataType = AnnotationDataType.NUMERIC,
span_id: str | None = None,
comment: str | None = None,
) -> None| Parameter | Default | Description |
|---|---|---|
trace_id | required | Trace to annotate. |
name | required | Annotation key. |
value | required | Type must match data_type. |
data_type | NUMERIC | numeric, categorical, or boolean. |
span_id | None | Scope to a specific span. |
comment | None | Free-text note. |
Data types
| Type | Python | Example |
|---|---|---|
NUMERIC | int / float | 842.0 |
CATEGORICAL | str | "good" |
BOOLEAN | bool | True |
Mismatched value/type raises ValueError.
From within a span
with st.span("rerank", kind="chain") as s:
scores = rerank(candidates)
s.annotate(name="top_score", value=max(scores), data_type="numeric")Behavior
- Fire-and-forget — network errors are logged, never raised.
- No-op when the SDK is uninitialized.
- Delivered out-of-band, so they may arrive slightly after the trace.