Add optional Monocle observability (opt-in)

[imohammedansari]

Add optional Monocle observability (opt-in)

Adds optional Monocle tracing to the Deep Research assistant. Monocle is an OpenTelemetry-based tracer for agentic apps; it records each run end-to-end (LLM calls, agent steps, tool invocations, with inputs/outputs, timings, token counts). It is entirely opt-in and a clean no-op unless enabled.

Env interface (unprefixed, shared across the Monocle-enabled apps)

• MONOCLE_TRACING — truthy gate, OFF by default.
• MONOCLE_EXPORTERS — plural, comma-separated; default file. Validated against file, console, okahu, s3, blob, gcs.
• OKAHU_API_KEY — required only when the okahu exporter is selected.

The app reads MONOCLE_EXPORTERS itself, fails fast on an unknown exporter or okahu-without-key, then forwards the comma-separated string verbatim as setup_monocle_telemetry(workflow_name="openai-agents-deep-research", monocle_exporters_list=...).

Optional dependency

monocle_apptrace is a monocle extra in setup.py (pip install "deep-researcher[monocle]"); it is not in core requirements.txt/install_requires. Enabling MONOCLE_TRACING without the extra raises a clear RuntimeError with the install hint. Telemetry helpers are no-ops when disabled or absent.

Behaviour (4 cases verified)

Case	Result
Disabled (MONOCLE_TRACING unset)	no-op; monocle_apptrace never imported
Enabled + installed, MONOCLE_EXPORTERS=file,console	setup_monocle_telemetry(..., monocle_exporters_list="file,console")
Enabled + installed, MONOCLE_EXPORTERS unset	forwarded "file"
Enabled + absent	RuntimeError with pip install "deep-researcher[monocle]" hint
Unknown exporter / okahu without key	ValueError fail-fast before instrumenting

Files changed

• deep_researcher/utils/telemetry.py (new) — gated setup + no-op async span/scope helpers
• deep_researcher/main.py — one setup_telemetry(...) call + single workflow -> agentic.turn span shaping (no-op when disabled)
• setup.py — monocle extra
• .env.example — MONOCLE_TRACING / MONOCLE_EXPORTERS / OKAHU_API_KEY
• README.md — "Monocle Tracing" subsection under Trace Monitoring

Author: Mohammed Ansari mohammed.ansari@okahu.ai. No secrets (placeholder okh_xxxxxxxx). Offline test suite unchanged (the pre-existing test_reformat_section_headings failure is unrelated).