[Eigenwise]

What

Tracing no longer depends on Phoenix or the OpenInference packages. AtomicAgentsInstrumentor runs on opentelemetry-api alone and emits OpenTelemetry GenAI semantic-convention spans that any backend reads: a plain OTLP collector, Grafana Tempo, Sentry, Datadog, Honeycomb, PostHog, Jaeger, Arize Phoenix, Langfuse.

• Spans: invoke_agent {name} (AGENT), execute_tool {tool_name} (TOOL) and one chat {model} CLIENT span per Instructor attempt, driven by Instructor hooks: per-attempt and total usage (input, output, cached, reasoning tokens) for both chat-completion and Responses shapes, gen_ai.response.model, attempt count, validation errors as events, error.type on failures. Spans always attach to the current context.
• Attributes: gen_ai.* primary; atomic_agents.* for framework detail; OpenInference keys only when openinference-instrumentation is importable (new phoenix extra) or TracingConfig(openinference_attributes=True).
• Config: TracingConfig(hide_inputs, hide_outputs, max_attribute_length=4096, openinference_attributes, llm_spans); env ATOMIC_AGENTS_TRACE_HIDE_INPUTS/_OUTPUTS (fallback OPENINFERENCE_HIDE_*), ATOMIC_AGENTS_TRACE_MAX_ATTRIBUTE_LENGTH, ATOMIC_AGENTS_TRACE_LLM_SPANS. Hide wins over truncation and is applied before serialization; under hide_outputs every exception is reduced to <Type>: <N> attempts (__REDACTED__).
• API: AgentConfig(name=...) for stable span names; using_conversation(conversation_id) sets gen_ai.conversation.id; a second instrument() with different explicit values replaces in place with a WARNING, None keeps the installed value; AtomicAgent.clear_hooks() removes only its own handlers; cancellation is recorded as atomic_agents.cancelled, never ERROR.
• Packaging: atomic-agents[observability] is now opentelemetry-api only; atomic-agents[phoenix] adds the OpenInference packages. Phoenix users on register(auto_instrument=True) keep working; set ATOMIC_AGENTS_TRACE_LLM_SPANS=false when a provider instrumentor also emits LLM spans.
• Package layout: observability/ split into tracing_config, span_payloads, span_attributes, agent_spans, tool_spans, installation, llm_attempt_spans, with tracing.py as a thin facade.
• Docs: guide rewritten OTLP-first with per-backend recipes (marked untested where nobody ran them); README section; phoenix-tracing example on the phoenix extra.

Design reviewed and probed by the Contractify consumer (Ada general chat instrumentation, Sentry and Grafana Tempo targets): verdict adoptable on d1c1bc8, 59 of 60 checks passing with real Instructor 1.17 + openai 2.53 and no OpenInference installed. Two should-fix items from that run (tool cancellation status, TraceConfig path honoring the env switch) land in the last commit before merge.

Verification

• Merged-tree gate: 800 tests passed, pyright 0 errors on the package, Black/Flake8 clean, Sphinx builds, no function above radon's A band.
• Observability suite: 176 tests including 24 real-Instructor cases over httpx.MockTransport across TOOLS, JSON, JSON_SCHEMA and RESPONSES_TOOLS, a two-thread registration race, suppression, redaction on retry exhaustion.
• CI: fresh-install job installs the wheel with [observability] + opentelemetry-sdk, proves openinference is absent, runs a real Instructor client over a mock transport and asserts GenAI keys and no OpenInference keys; lowest-versions job compiles both extras.
• Internal adversarial clean-code review (SQ-151) and the consumer's full-diff review (19 findings) both addressed with regression tests.

🤖 Generated with Claude Code