Annotations

st.annotate attaches numeric scores, category labels, or boolean flags to traces for analytics and eval. Use it to record latency, quality, pass/fail, or any metric you want to slice traces by later.

import staso as st

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	Type	Default	Description
`trace_id`	`str`	required	Trace to annotate.
`name`	`str`	required	Annotation key, e.g. `"latency_ms"`.
`value`	`float \| str \| bool`	required	The value. Type must match `data_type`.
`data_type`	`str \| AnnotationDataType`	`NUMERIC`	One of `numeric`, `categorical`, `boolean`.
`span_id`	`str \| None`	`None`	Optional — scope the annotation to a specific span inside the trace.
`comment`	`str \| None`	`None`	Optional free-text note.

Data types

AnnotationDataType accepts three values:

Type	Python value	Example
`NUMERIC`	`int` or `float`	`842.0`
`CATEGORICAL`	`str`	`"good"`
`BOOLEAN`	`bool`	`True`

Mismatched value and type raise ValueError.

Canonical examples

# Numeric score
st.annotate(trace_id=tid, name="latency_ms", value=842.0, data_type="numeric")

# Categorical label
st.annotate(trace_id=tid, name="model_quality", value="good", data_type="categorical")

# Boolean flag
st.annotate(trace_id=tid, name="passed", value=True, data_type="boolean")

From within a span

Inside a manual span, call span.annotate(...) — it is wired to the current span and trace automatically.

with st.span("rerank", kind="chain") as s:
    scores = rerank(candidates)
    s.annotate(
        name="top_score",
        value=max(scores),
        data_type="numeric",
        comment="higher is better",
    )

Behavior

Fire-and-forget. Network errors are logged, never raised.
No-op when the SDK has not been initialized — safe to leave in code paths that run outside instrumented environments.
Annotations are delivered out-of-band from span batches, so they may arrive slightly after the trace they describe.