[asg017]

🤖 Claude-generated PR description

Stacked on the datasette_llm.prompt span PR (branch asg017/otel-v2).

This PR adds one OpenTelemetry histogram, datasette_llm.token.usage (unit {token}), so operators can chart token spend per feature. Its attributes are bounded:

• datasette_llm.purpose: the declared purpose, or "none"
• gen_ai.token.type: input or output
• gen_ai.request.model

llm's own metrics (in a separate PR) key by model and provider. Only datasette-llm knows the purpose.

How

• A small usage_recorder(purpose, model_id) callback is registered with PromptResult.on_response_done at the same three places the span is opened: chain, conversation prompt and model prompt. It records response.input_tokens / output_tokens whenever they are not None. It never forces a response.
• A chain records once per response. Errored or abandoned responses record nothing.
• It records regardless of whether the span is being recorded. Without an SDK the histogram is a no-op.
• Bucket boundaries follow the GenAI semconv token buckets (1, 4, 16, … 67108864).
• The README asks that purposes be fixed identifiers, since they become a metric attribute.

Tests
A session-scoped InMemoryMetricReader with delta temporality covers:

• a chain with a tool call records two points per token type, with exact attributes, for both a declared purpose and "none"
• model.prompt and conversation().prompt record one point per token type

uv run pytest: 67 passed.

🤖 Generated with Claude Code