[.Net][ADR] OTel auto-instrumentation proposal

[rogerbarreto]

What

ADR 0026 propose convention-aligned OTel auto-instrumentation for Agent Framework. No code change. Only doc.

Why

Today: per-agent UseOpenTelemetry() wrap. Diverge from .NET OTel ecosystem (AddXxxInstrumentation() on provider). No kill switch. AsAIAgent() factories unreachable by DI wrap.

What ADR propose

• AddAgentFrameworkInstrumentation() on TracerProviderBuilder + MeterProviderBuilder
• AddAgentFrameworkWorkflowsInstrumentation() for workflows source
• Dep: OpenTelemetry.Api.ProviderBuilderExtensions, 2 net-new transitive
• AgentFrameworkInstrumentationOptions = full parity with UseOpenTelemetry() (SourceName + ConfigureAgent)
• AsAIAgent() factories gain optional IServiceProvider? services param. Auto-wrap when options registered. Idempotent.
• Workflow.AsAIAgent() join same pattern (agents marker)
• Env-var kill switch OTEL_DOTNET_AGENTFRAMEWORK_INSTRUMENTATION_ENABLED
• Multi-call: last-wins
• UseOpenTelemetry() + OpenTelemetryAgent unchanged. ADR-0003 not superseded.

Open question for reviewer

Existing OpenTelemetryAgent, UseOpenTelemetry(), OpenTelemetryConsts:

• Stay in core (recommended, non-breaking), OR
• Move to new Microsoft.Agents.AI.OpenTelemetry + Microsoft.Agents.AI.Workflows.OpenTelemetry packages (breaking)

Out of scope (deferred)

• Source-name rename / consolidation (separate "source-naming" ADR)
• Experimental. prefix removal (gated on upstream gen-AI semconv stable)
• Profiler-based auto-instrumentation
• BCL listener-driven emission refactor

Refs

• Closes investigation .NET: Investigation: .NET OTel auto-instrumentation convention for Agent Framework #5852
• Builds on ADR-0003

[Copilot]

Pull request overview

Adds ADR 0026 proposing convention-aligned OpenTelemetry “auto-instrumentation” activation for the .NET Agent Framework (provider-builder AddXxxInstrumentation() entrypoints + DI-aware AsAIAgent() wrapping + env-var kill switch). This is documentation-only and is intended to set direction before implementation work begins.

Changes:

• Introduces a new ADR describing provider-builder activation APIs for agent + workflow telemetry.
• Proposes DI-driven auto-wrapping behavior for AsAIAgent() factories and an env-var kill switch.
• Outlines validation/testing expectations and open packaging questions (keep OTel primitives in-core vs move to dedicated packages).

Comments suppressed due to low confidence (1)

docs/decisions/0026-agent-otel-auto-instrumentation.md:139

• In Consequences, “Adds optional IServiceProvider? services = null to every AsAIAgent() overload” reads as if this parameter is universally new. In practice, several providers already have a services parameter today, while a few (e.g., A2A / Copilot) do not. Suggest clarifying the impact as “adds services to the remaining AsAIAgent overloads that lack it” and optionally call out representative examples, so the scope/cost is accurately represented.

- **Bad:** Adds optional `IServiceProvider? services = null` to every
  `AsAIAgent()` overload across ~10–15 provider packages.
  Source-compatible + binary-compatible. Coordinated release needed.