Skip to content

Building AI agents, atomically

Add standard OpenTelemetry auto-discovery (#319)

Kenny Vaneetvelde609bacb46417
diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json
index 8cd7700..2222861 100644
--- a/.claude/.codebase-info/.map-state.json
+++ b/.claude/.codebase-info/.map-state.json
@@ -2,8 +2,8 @@
"schemaVersion": 1,
"tool": "codebase-mapper",
"version": "2.15.10",
- "mappedAt": "2026-10-19",
- "gitCommit": "3fe4b3bd5b52a4291ff90b99a0275efd27eb5439",
+ "mappedAt": "2026-10-20",
+ "gitCommit": "ed1cb19b6b94696aa3685803fcc02f8306bbbd8c",
"documents": [
"architecture.md",
"coding-style.md",
@@ -20,13 +20,13 @@
"INDEX.md": "d9cca4a80c1f3e7be5b90aed54191ec5a6ec3b95106e132603cbd0e78a911b57",
"architecture.md": "59d1265c89d3b42671b7c47165408625018537c016a72df421113cae3f80bb70",
"coding-style.md": "b63e8dff06d16a2d882f02624c62f490291317aec8b3032f6d79b3ee035e8567",
- "communication.md": "70fbeedf239b130cfd3d7a92f27d56e96b207d85117b2f83cc9eef8ec6d6c6b3",
- "dependencies.md": "35b8ff6cdf4342969a1f29e8e1dde23332e6040c9a128b166aa541650ed65f6f",
+ "communication.md": "4c49f01a99b25a2f56b2b3ab77464f05c7d70d057aa8e998deffe845afc3e7e6",
+ "dependencies.md": "22b8d208df66c973659a34cea10011a7ac315ddaa65b243c8aaa3adc4eed1a9e",
"directory-structure.md": "4efb931cdefecf2c733f0ffb905ad519aff3a81e245a978c0b62b2c5cf0ad49a",
- "entry-points.md": "3c94fd8a821fc76789794b6d3f4d89cc88a7903055755d97437f9f3ca6193cb6",
+ "entry-points.md": "e03c248c63823276c21dbbe894b98488643ee401c2db136ad2467a00ba57bc9a",
"modules.md": "cd4f81f8ce74dfc4a7bab15ba91dc569245bc342ddf494845d658b51a0a1dc51",
"onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e",
"patterns.md": "09d04b9b8d079ac4ce9e1f5ddafabb6f3faf53b5ef48dca1c2d62d0875e149b0",
- "tech-landscape.md": "ecb344a05ea1577b1ed24d98e8cb0606053f9dd0bec10af1d211863d251ca6de"
+ "tech-landscape.md": "919d254fae6fa5212a18072ee0d26a1165ce2aeef861faace6c34b8804c025b1"
}
}
diff --git a/.claude/.codebase-info/communication.md b/.claude/.codebase-info/communication.md
index 6bc2d48..7325f5e 100644
--- a/.claude/.codebase-info/communication.md
+++ b/.claude/.codebase-info/communication.md
@@ -1,6 +1,6 @@
# Communication & Integrations
-*Last Updated: 2026-10-15*
+*Last Updated: 2026-10-19*
The framework exposes no HTTP API of its own; "communication" here means how it talks to LLM
providers and external tools.
@@ -39,9 +39,13 @@ providers and external tools.
`token:counted`. See the `hooks-example` example and `docs/guides/hooks.md`.
- OpenInference tracing (`atomic_agents.observability`, optional `observability` extra): an AGENT span per
`AtomicAgent` run and a TOOL span per `BaseTool` run, auto-activated by `phoenix.otel.register(auto_instrument=True)`
- through the `openinference_instrumentor` entry point, or by `AtomicAgentsInstrumentor().instrument(tracer_provider=...)`
- for any OTLP backend. LLM spans come from the provider's own OpenInference instrumentor and nest under the agent
- span. See `docs/guides/observability.md` and the `phoenix-tracing` example.
+ through `openinference_instrumentor`, by the standard `opentelemetry-instrument` launcher through
+ `opentelemetry_instrumentor`, or by `AtomicAgentsInstrumentor().instrument(tracer_provider=...)`
+ for an explicitly configured backend. Both discovery paths share the first installation's provider/config.
+ Missing optional tracing dependencies are DEBUG-skipped when the launcher passes `skip_dep_check=True`;
+ manual setup retains its import error and install hint. Choose one configuration path or share the
+ provider explicitly. LLM spans come from one provider-level OpenInference instrumentor and nest under
+ the agent span. See `docs/guides/observability.md` and the `phoenix-tracing` example.
- Forge tools that run their async body through a `ThreadPoolExecutor` submit via
`contextvars.copy_context().run` so the caller's OpenTelemetry context (and the tracing re-entrancy guard)
survives in the pool thread.
diff --git a/.claude/.codebase-info/dependencies.md b/.claude/.codebase-info/dependencies.md
index 3a638cb..ec1ab3c 100644
--- a/.claude/.codebase-info/dependencies.md
+++ b/.claude/.codebase-info/dependencies.md
@@ -40,6 +40,7 @@ already brings the two OpenInference packages, so the Phoenix auto path works wi
| pre-commit (≥4,<5) | Git hook runner |
| pytest / pytest-cov / pytest-asyncio | Tests, coverage, async tests |
| openai (≥2,<3) | Example/test provider client |
+| opentelemetry-instrumentation (≥0.51b0,<1) | Real auto-loader and launcher tests; dev-only, not a runtime dependency |
## Docs
`sphinx`, `sphinx-rtd-theme`, `myst-parser`, `sphinx-copybutton`, `sphinx-design`,
diff --git a/.claude/.codebase-info/entry-points.md b/.claude/.codebase-info/entry-points.md
index 4d15221..a1037d4 100644
--- a/.claude/.codebase-info/entry-points.md
+++ b/.claude/.codebase-info/entry-points.md
@@ -1,6 +1,6 @@
# Entry Points
-*Last Updated: 2026-10-15*
+*Last Updated: 2026-10-19*
## 1. Library API (the primary entry point)
@@ -55,6 +55,15 @@ MCP server tools/resources/prompts become agent components via `atomic_agents.co
| `youtube-summarizer` / `youtube-to-recipe` | transcript → summary / structured recipe |
| `dspy-integration` | combining DSPy with Atomic Agents |
+## 5. OpenTelemetry discovery
+
+`atomic_agents.observability:AtomicAgentsInstrumentor` is registered as `atomic_agents` in both
+`openinference_instrumentor` (Phoenix) and `opentelemetry_instrumentor` (the standard
+`opentelemetry-instrument` launcher). Both use the same installation state. The launcher needs
+its own SDK/exporter setup and the optional OpenInference dependencies; it does not install them
+through `opentelemetry-bootstrap`. Set `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=atomic_agents` to
+disable launcher discovery. See `docs/guides/observability.md`.
+
## Representative Flow
`agent.run(input)` → `SystemPromptGenerator.generate_prompt()` (+ context providers) → serialize
diff --git a/.claude/.codebase-info/tech-landscape.md b/.claude/.codebase-info/tech-landscape.md
index 7212db5..fe1776d 100644
--- a/.claude/.codebase-info/tech-landscape.md
+++ b/.claude/.codebase-info/tech-landscape.md
@@ -42,8 +42,10 @@
`pytest --cov=atomic_agents` for the core); `fresh-install` (build the wheel, install
it with the observability extra into a clean venv without the lockfile, import every module under
`atomic_agents`, which is what a new user's `pip install` sees); `lowest-versions` (resolve runtime
- dependencies with `uv pip compile --resolution lowest-direct`, install current pytest tooling, run
- the suite, so every declared floor is a tested floor).
+ dependencies with `uv pip compile --resolution lowest-direct`, install current pytest tooling plus
+ `opentelemetry-instrumentation==0.51b0` compatible with the OpenTelemetry API floor, then run the
+ suite). Observability tests exercise real installed discovery metadata, the auto-loader and enabled/disabled
+ launcher subprocesses with local exporters; no live model/backend calls are needed.
- `docs.yml` — on push to `main`: build Sphinx docs, run
`scripts/generate_llms_files.py` (spec-compliant `llms.txt` index + `llms-*.txt`
bundles, copied to the site root), deploy to GitHub Pages. The docs version needs
diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml
index 3945d5c..9730e16 100644
--- a/.github/workflows/code-quality.yml
+++ b/.github/workflows/code-quality.yml
@@ -124,12 +124,14 @@ jobs:
version: "latest"
- name: Resolve runtime dependencies at their declared floors
- run: uv pip compile pyproject.toml --resolution lowest-direct --extra observability -o lowest-requirements.txt
+ run: |
+ echo 'opentelemetry-instrumentation==0.51b0' > telemetry-test-requirements.txt
+ uv pip compile pyproject.toml telemetry-test-requirements.txt --resolution lowest-direct --extra observability -o lowest-requirements.txt
- name: Install the floors plus current test tooling
run: |
uv venv lowest-venv
- uv pip install --python lowest-venv -r lowest-requirements.txt pytest pytest-asyncio pytest-cov
+ uv pip install --python lowest-venv -r lowest-requirements.txt pytest pytest-asyncio pytest-cov opentelemetry-instrumentation==0.51b0
uv pip install --python lowest-venv --no-deps -e .
- name: Show resolved versions
diff --git a/atomic-agents/atomic_agents/observability/__init__.py b/atomic-agents/atomic_agents/observability/__init__.py
index 6fe3567..19bb0e2 100644
--- a/atomic-agents/atomic_agents/observability/__init__.py
+++ b/atomic-agents/atomic_agents/observability/__init__.py
@@ -63,7 +63,11 @@ class AtomicAgentsInstrumentor:
"""
def instrument(
- self, *, tracer_provider: Optional["TracerProvider"] = None, config: Optional["TraceConfig"] = None
+ self,
+ *,
+ tracer_provider: Optional["TracerProvider"] = None,
+ config: Optional["TraceConfig"] = None,
+ **options: object,
) -> None:
"""
Patch the framework classes. Safe to call more than once; a second call with different
@@ -72,12 +76,17 @@ class AtomicAgentsInstrumentor:
Args:
tracer_provider: An OpenTelemetry ``TracerProvider``. Defaults to the global provider.
config: An ``openinference.instrumentation.TraceConfig`` (for example ``hide_inputs=True``).
+ **options: Launcher options accepted for OpenTelemetry auto-instrumentation compatibility.
Raises:
- ImportError: When the ``observability`` extra is not installed.
+ ModuleNotFoundError: When the ``observability`` extra is not installed, except during
+ OpenTelemetry auto-discovery, which skips unavailable optional instrumentation.
"""
if not _openinference_is_installed():
- raise ImportError(_INSTALL_HINT)
+ if options.get("skip_dep_check") is True:
+ logger.debug(_INSTALL_HINT)
+ return
+ raise ModuleNotFoundError(_INSTALL_HINT)
tracing = _load_tracing_module()
if tracing is not None:
tracing.install(tracer_provider=tracer_provider, config=config)
diff --git a/atomic-agents/tests/observability/test_openinference_tracing.py b/atomic-agents/tests/observability/test_openinference_tracing.py
index 6fed9e2..6fb3bc8 100644
--- a/atomic-agents/tests/observability/test_openinference_tracing.py
+++ b/atomic-agents/tests/observability/test_openinference_tracing.py
@@ -673,11 +673,12 @@ def test_phoenix_entry_point_loads_and_instruments_with_only_a_tracer_provider()
assert len(spans_of(exporter)) == 1
-def test_instrument_without_openinference_raises_install_hint(monkeypatch):
[email protected]("options", [{}, {"skip_dep_check": False}])
+def test_instrument_without_openinference_raises_install_hint(monkeypatch: pytest.MonkeyPatch, options: dict[str, object]):
monkeypatch.setattr(observability, "_openinference_is_installed", lambda: False)
with pytest.raises(ImportError, match="atomic-agents\\[observability\\]"):
- AtomicAgentsInstrumentor().instrument()
+ AtomicAgentsInstrumentor().instrument(**options)
def test_uninstrument_without_openinference_is_a_no_op(monkeypatch):
diff --git a/atomic-agents/tests/observability/test_opentelemetry_discovery.py b/atomic-agents/tests/observability/test_opentelemetry_discovery.py
new file mode 100644
index 0000000..6c40f55
--- /dev/null
+++ b/atomic-agents/tests/observability/test_opentelemetry_discovery.py
@@ -0,0 +1,231 @@
+import logging
+import os
+from collections.abc import Iterator, Mapping
+from importlib.metadata import EntryPoint, distribution, entry_points
+from pathlib import Path
+import subprocess
+import sys
+import sysconfig
+from unittest.mock import Mock
+
+import pytest
+from openinference.instrumentation import TraceConfig
+from openinference.semconv.trace import SpanAttributes
+from opentelemetry.instrumentation.auto_instrumentation import _load
+from opentelemetry.instrumentation.distro import DefaultDistro
+from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.util.types import AttributeValue
+
+import atomic_agents.observability as observability
+from atomic_agents.observability import AtomicAgentsInstrumentor
+from test_openinference_tracing import CalculationInputSchema, CalculatorTool, QuestionSchema, make_agent, sync_client
+
+
+def local_tracing() -> Iterator[tuple[TracerProvider, InMemorySpanExporter]]:
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+ yield provider, exporter
+ AtomicAgentsInstrumentor().uninstrument()
+ provider.shutdown()
+
+
+def installed_entry_point(group: str) -> EntryPoint:
+ points = [point for point in entry_points(group=group) if point.name == "atomic_agents"]
+ assert len(points) == 1, f"Expected one installed Atomic Agents entry point in {group}"
+ return points[0]
+
+
+def exported_attributes(span: ReadableSpan) -> Mapping[str, AttributeValue]:
+ attributes = span.attributes
+ assert attributes is not None
+ return attributes
+
+
+def run_agent_and_tool() -> None:
+ make_agent(sync_client()).run(QuestionSchema(question="private question"))
+ CalculatorTool().run(CalculationInputSchema(expression="private expression"))
+
+
+def test_installed_opentelemetry_entry_point_activates_real_loader(
+ monkeypatch: pytest.MonkeyPatch, local_tracing: tuple[TracerProvider, InMemorySpanExporter]
+) -> None:
+ provider, exporter = local_tracing
+ instrumentor = installed_entry_point("opentelemetry_instrumentor")
+ monkeypatch.setattr(_load, "entry_points", lambda group: (instrumentor,) if group == "opentelemetry_instrumentor" else ())
+ monkeypatch.setattr("opentelemetry.trace.get_tracer_provider", lambda: provider)
+ monkeypatch.delenv("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", raising=False)
+ monkeypatch.setenv("OPENINFERENCE_HIDE_INPUTS", "true")
+ monkeypatch.setenv("OPENINFERENCE_HIDE_OUTPUTS", "true")
+
+ _load._load_instrumentors(DefaultDistro())
+ run_agent_and_tool()
+
+ spans = exporter.get_finished_spans()
+ assert [exported_attributes(span)[SpanAttributes.OPENINFERENCE_SPAN_KIND] for span in spans] == ["AGENT", "TOOL"]
+ assert [exported_attributes(span)[SpanAttributes.INPUT_VALUE] for span in spans] == ["__REDACTED__", "__REDACTED__"]
+ assert [exported_attributes(span)[SpanAttributes.OUTPUT_VALUE] for span in spans] == ["__REDACTED__", "__REDACTED__"]
+
+
+def test_unknown_launcher_options_preserve_provider_and_privacy(
+ local_tracing: tuple[TracerProvider, InMemorySpanExporter],
+) -> None:
+ provider, exporter = local_tracing
+ AtomicAgentsInstrumentor().instrument(
+ tracer_provider=provider,
+ config=TraceConfig(hide_inputs=True, hide_outputs=True),
+ skip_dep_check=True,
+ custom_launcher_option=object(),
+ )
+ run_agent_and_tool()
+
+ spans = exporter.get_finished_spans()
+ assert len(spans) == 2
+ assert [exported_attributes(span)[SpanAttributes.INPUT_VALUE] for span in spans] == ["__REDACTED__", "__REDACTED__"]
+ assert [exported_attributes(span)[SpanAttributes.OUTPUT_VALUE] for span in spans] == ["__REDACTED__", "__REDACTED__"]
+
+
+def test_loader_skips_missing_openinference_and_continues_without_error(
+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+ instrumentor = installed_entry_point("opentelemetry_instrumentor")
+ sentinel = Mock(
+ name="sentinel", group="opentelemetry_instrumentor", value="sentinel:Instrumentor", dist=distribution("atomic-agents")
+ )
+ sentinel.name = "sentinel"
+ points = (instrumentor, sentinel)
+ monkeypatch.setattr(_load, "entry_points", lambda group: points if group == "opentelemetry_instrumentor" else ())
+ monkeypatch.setattr(observability, "_openinference_is_installed", lambda: False)
+ monkeypatch.delenv("OTEL_PYTHON_DISABLED_INSTRUMENTATIONS", raising=False)
+
+ with caplog.at_level(logging.DEBUG):
+ _load._load_instrumentors(DefaultDistro())
+
+ sentinel.load.return_value.return_value.instrument.assert_called_once_with(skip_dep_check=True)
+ assert "atomic-agents[observability]" in caplog.text
+ assert not [record for record in caplog.records if record.levelno >= logging.ERROR]
+ assert not AtomicAgentsInstrumentor().is_instrumented_by_opentelemetry
+
+
[email protected]("first_group", ["openinference_instrumentor", "opentelemetry_instrumentor"])
+def test_both_entry_points_keep_first_provider_and_config(
+ first_group: str, local_tracing: tuple[TracerProvider, InMemorySpanExporter], caplog: pytest.LogCaptureFixture
+) -> None:
+ provider, exporter = local_tracing
+ second_group = {
+ "openinference_instrumentor": "opentelemetry_instrumentor",
+ "opentelemetry_instrumentor": "openinference_instrumentor",
+ }[first_group]
+ first = installed_entry_point(first_group).load()()
+ second = installed_entry_point(second_group).load()()
+ other_provider = TracerProvider()
+ other_exporter = InMemorySpanExporter()
+ other_provider.add_span_processor(SimpleSpanProcessor(other_exporter))
+ first.instrument(tracer_provider=provider, config=TraceConfig(hide_inputs=True))
+ try:
+ with caplog.at_level(logging.WARNING):
+ second.instrument(tracer_provider=other_provider, config=TraceConfig(hide_inputs=False), skip_dep_check=True)
+ run_agent_and_tool()
+ assert "already installed" in caplog.text
+ assert [exported_attributes(span)[SpanAttributes.INPUT_VALUE] for span in exporter.get_finished_spans()] == [
+ "__REDACTED__",
+ "__REDACTED__",
+ ]
+ assert other_exporter.get_finished_spans() == ()
+ finally:
+ second.uninstrument()
+ other_provider.shutdown()
+
+
[email protected]("first_group", ["openinference_instrumentor", "opentelemetry_instrumentor"])
+def test_either_entry_point_can_uninstrument_and_reinstall(
+ first_group: str, local_tracing: tuple[TracerProvider, InMemorySpanExporter]
+) -> None:
+ provider, exporter = local_tracing
+ second_group = {
+ "openinference_instrumentor": "opentelemetry_instrumentor",
+ "opentelemetry_instrumentor": "openinference_instrumentor",
+ }[first_group]
+ first = installed_entry_point(first_group).load()()
+ second = installed_entry_point(second_group).load()()
+ first.instrument(tracer_provider=provider)
+ second.instrument(tracer_provider=provider)
+ run_agent_and_tool()
+ assert len(exporter.get_finished_spans()) == 2
+
+ second.uninstrument()
+ first.uninstrument()
+ run_agent_and_tool()
+ assert len(exporter.get_finished_spans()) == 2
+
+ second.instrument(tracer_provider=provider, config=TraceConfig(hide_inputs=True), skip_dep_check=True)
+ exporter.clear()
+ run_agent_and_tool()
+ assert [exported_attributes(span)[SpanAttributes.INPUT_VALUE] for span in exporter.get_finished_spans()] == [
+ "__REDACTED__",
+ "__REDACTED__",
+ ]
+
+
[email protected]("disabled_name,expected_kinds", [("", ["AGENT", "TOOL"]), ("atomic_agents", [])])
+def test_real_launcher_respects_disabled_name(disabled_name: str, expected_kinds: list[str], tmp_path: Path) -> None:
+ executable_name = "opentelemetry-instrument.exe" if os.name == "nt" else "opentelemetry-instrument"
+ launcher = Path(sysconfig.get_path("scripts")) / executable_name
+ environment = os.environ.copy()
+ environment.update(
+ OTEL_TRACES_EXPORTER="none",
+ OTEL_METRICS_EXPORTER="none",
+ OTEL_LOGS_EXPORTER="none",
+ OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=disabled_name,
+ OPENINFERENCE_HIDE_INPUTS="true",
+ OPENINFERENCE_HIDE_OUTPUTS="true",
+ )
+ script = f"""
+import sys
+sys.path.insert(0, {str(Path(__file__).parent)!r})
+from test_opentelemetry_discovery import exported_attributes, run_agent_and_tool
+from atomic_agents.observability import AtomicAgentsInstrumentor
+from opentelemetry import trace
+from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+assert AtomicAgentsInstrumentor().is_instrumented_by_opentelemetry is {bool(expected_kinds)!r}
+provider = TracerProvider()
+exporter = InMemorySpanExporter()
+provider.add_span_processor(SimpleSpanProcessor(exporter))
+trace.set_tracer_provider(provider)
+run_agent_and_tool()
+spans = exporter.get_finished_spans()
+assert len(spans) == {len(expected_kinds)}
+assert [exported_attributes(span)['openinference.span.kind'] for span in spans] == {expected_kinds!r}
+assert [exported_attributes(span)['input.value'] for span in spans] == {['__REDACTED__'] * len(expected_kinds)!r}
+AtomicAgentsInstrumentor().uninstrument()
+provider.shutdown()
+print('launcher assertions passed')
+"""
+ script_path = tmp_path / "launcher_probe.py"
+ script_path.write_text(script, encoding="utf-8")
+ result = subprocess.run(
+ [str(launcher), sys.executable, str(script_path)], env=environment, capture_output=True, text=True, timeout=45
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert "launcher assertions passed" in result.stdout
+ assert "Traceback" not in result.stderr
+
+
+def test_normal_import_does_not_require_optional_observability_packages() -> None:
+ script = """
+import sys
+sys.modules['openinference'] = None
+sys.modules['opentelemetry'] = None
+import atomic_agents
+import atomic_agents.observability
+assert 'atomic_agents.observability.openinference_tracing' not in sys.modules
+print('optional-free import passed')
+"""
+ result = subprocess.run([sys.executable, "-c", script], capture_output=True, text=True, timeout=45)
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert "optional-free import passed" in result.stdout
diff --git a/docs/guides/observability.md b/docs/guides/observability.md
index 41d1e14..1bcff64 100644
--- a/docs/guides/observability.md
+++ b/docs/guides/observability.md
@@ -61,6 +61,46 @@ Two things to know about the automatic path:
- Existing `auto_instrument=True` users start exporting agent and tool payloads when they upgrade to a version with the
instrumentor. Use the privacy controls below if that is not wanted.
+## Setup with the OpenTelemetry launcher (automatic)
+
+Install the optional tracing adapter, launcher, SDK, and exporter explicitly:
+
+```bash
+pip install "atomic-agents[observability]" opentelemetry-distro opentelemetry-exporter-otlp-proto-http
+```
+
+Run your existing application with environment-only configuration:
+
+```bash
+export OTEL_SERVICE_NAME=my-app
+export OTEL_TRACES_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:6006
+export OTEL_METRICS_EXPORTER=none
+export OTEL_LOGS_EXPORTER=none
+export OPENINFERENCE_HIDE_INPUTS=true
+export OPENINFERENCE_HIDE_OUTPUTS=true
+opentelemetry-instrument python app.py
+```
+
+The launcher discovers `atomic_agents` through the `opentelemetry_instrumentor` entry point and activates the
+same adapter used by Phoenix and manual setup. Without the OpenInference dependencies, the loader skips the adapter.
+`opentelemetry-bootstrap` does not automatically install Atomic Agents or its observability extra.
+
+To disable this adapter, set `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=atomic_agents` (or add `atomic_agents` to an
+existing comma-separated list). Ordinary imports without a launcher or explicit setup remain uninstrumented.
+
+Choose one provider configuration path: the launcher, Phoenix registration, or manual setup. Both discovery entry
+points share one installation, so activating both does not duplicate Atomic Agents spans. The first provider/config
+wins; a later call with different settings warns and keeps the existing installation. OpenTelemetry also keeps its
+first global provider. Calling Phoenix registration after launcher startup therefore does not switch the export
+destination. To combine explicit activations, configure a shared provider, or uninstrument before changing the
+Atomic Agents provider/config as described below.
+
+The launcher adds AGENT and TOOL spans, with no parent CHAIN or provider LLM spans of its own. Install exactly one
+instrumentor for your LLM provider and activate it through its supported setup. Use the grouping example below when
+you want several agent/tool calls in one trace.
+
## Setup with any OpenTelemetry backend (manual)
```python
@@ -126,8 +166,8 @@ endpoint returned, so a context manager around the endpoint body no longer appli
Agent and tool payloads are exported as `input.value` / `output.value`. To redact them:
-- On the automatic Phoenix path, set `OPENINFERENCE_HIDE_INPUTS=true` and/or `OPENINFERENCE_HIDE_OUTPUTS=true`.
- `TraceConfig()` reads these variables.
+- On the automatic Phoenix or OpenTelemetry launcher path, set `OPENINFERENCE_HIDE_INPUTS=true` and/or
+ `OPENINFERENCE_HIDE_OUTPUTS=true`. `TraceConfig()` reads these variables before the first installation.
- On the manual path, pass `TraceConfig(hide_inputs=True, hide_outputs=True)` to `instrument()`.
Redacted values are exported as `__REDACTED__`. Masking covers the `input.value` and `output.value` attributes of
diff --git a/pyproject.toml b/pyproject.toml
index 239056e..137a0e5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -53,6 +53,9 @@ atomic = "atomic_assembler.main:main"
[project.entry-points.openinference_instrumentor]
atomic_agents = "atomic_agents.observability:AtomicAgentsInstrumentor"
+[project.entry-points.opentelemetry_instrumentor]
+atomic_agents = "atomic_agents.observability:AtomicAgentsInstrumentor"
+
[dependency-groups]
dev = [
"black>=24.8.0,<25.0.0",
@@ -75,6 +78,7 @@ dev = [
"openinference-instrumentation>=0.1.38,<0.2.0",
"openinference-semantic-conventions>=0.1.20,<0.2.0",
"opentelemetry-sdk>=1.30.0,<2.0.0",
+ "opentelemetry-instrumentation>=0.51b0,<1.0.0",
]
[tool.hatch.build.targets.wheel]
diff --git a/uv.lock b/uv.lock
index 3d34942..b56d815 100644
--- a/uv.lock
+++ b/uv.lock
@@ -299,6 +299,7 @@ dev = [
{ name = "openai" },
{ name = "openinference-instrumentation" },
{ name = "openinference-semantic-conventions" },
+ { name = "opentelemetry-instrumentation" },
{ name = "opentelemetry-sdk" },
{ name = "pdoc3" },
{ name = "pre-commit" },
@@ -341,6 +342,7 @@ dev = [
{ name = "openai", specifier = ">=2.0.0,<3.0.0" },
{ name = "openinference-instrumentation", specifier = ">=0.1.38,<0.2.0" },
{ name = "openinference-semantic-conventions", specifier = ">=0.1.20,<0.2.0" },
+ { name = "opentelemetry-instrumentation", specifier = ">=0.51b0,<1.0.0" },
{ name = "opentelemetry-sdk", specifier = ">=1.30.0,<2.0.0" },
{ name = "pdoc3", specifier = ">=0.11.1,<1.0.0" },
{ name = "pre-commit", specifier = ">=4.0.0,<5.0.0" },