Skip to main content
A score records how well a run went. Attaching it through the SDK puts quality next to latency and cost on the same trace, so you can query all three together instead of joining an external evaluation store.

Score a trace or a span

score_trace / scoreTrace attaches the score to the trace’s root span. Use it for a judgement about the whole run. score attaches to the span you call it on. Use it when the judgement is about one step — a retrieval’s precision, a single tool call’s correctness.
score_trace targets the root span only when the SDK opened that root in the current context. Otherwise it falls back to the span it was called on, so the score is never silently dropped.

The three data types

Pass comment on any score to record why the value was assigned.

Invalid scores are dropped, not raised

Scoring never breaks the run. A score is dropped with a warning when the name is empty or not a string, the data type is unrecognized, a NUMERIC value is not numeric, a CATEGORICAL score has no string_value, or a BOOLEAN score has no value at all. That means a typo in a data type produces a missing score rather than an exception. If a score you expect is absent, enable ATLAN_DEBUG=true and check the warnings.

How a score is stored

Each score writes two things to the span:
  • an atlan.score span event carrying the name, numeric value, data type, and the optional string value and comment
  • a rollup attribute atlan.score.{name} holding the numeric value
The rollup attribute is what makes scores queryable from the Gateway’s trace statistics without expanding every event. Use a stable, lowercase name with underscores so the attribute stays consistent across runs.

Next steps

Trace your agent

Spans, observation types, usage and cost.

Reporting

Where scores surface alongside cost and latency.