/ratel-observability-assessment — turn on native OTLP telemetry for an agent codebase

Mount observability on a customer's codebase the way the Ratel team would: detect the stack, map the agent's mental model, decide one consistent naming/tagging vocabulary, decide which dashboards prove value, turn on Ratel's native OTLP telemetry and pick the OTel backend the team already exports to, and write a proposal the customer can act on. The proposal is the deliverable. Do not edit the agent code, and do not call any backend API.

Ratel's telemetry is OpenTelemetry: the SDKs natively emit the retrieval + tool funnel as gen_ai.* spans (semconv v1.42.0) plus a ratel.* overlay, exported as stock OTLP. So the wiring is not vendor-shaped — you turn on native telemetry once and export those spans to whatever OTel backend the team already runs (Langfuse, LangSmith, your own collector, or Ratel Cloud — Coming Soon). This skill owns the whole decision: where tracing belongs, what agent-level spans to add alongside Ratel's funnel, which backend to export to, and which dashboards prove value. It is the entry point of the observability funnel, usually reached when /ratel-assessment flags the Observability dimension as Weak or Missing.

The vocabulary and dashboard set it lands on become the contract the team builds against in whichever backend they export to, so the span/attribute names defined here actually show up on the dashboards.

Philosophy: trace the mental model, not the call graph

A common failure mode is "wrap every function in a span." That produces data that matches the code's call graph but tells you nothing about what the agent was trying to do. The proposal must structure observability around the conceptual shape of a turn — units of work, steps, sessions — not the source-file layout. Read references/instrumentation-philosophy.md for the full guidance and the two anti-patterns (no session boundary; tool calls captured as untyped events) to call out whenever you see them.

Workflow

Step 1 — Detect the stack

Read manifest files to identify language and framework. Ratel's native telemetry ships for TypeScript and Python, so the stack profile mainly tells you which SDK (@ratel-ai/sdk vs ratel-ai) and which framework hooks the wiring uses.