[FEATURE] Emit OpenTelemetry traces, metrics, and logs (OTLP exporter) for hosted MCP integrations

[sajeetharan]

Feature Description

Add OpenTelemetry instrumentation (traces, metrics, logs) to the Cosmos DB MCP Toolkit and expose an OTLP exporter so server-level telemetry can be ingested by host platforms — specifically the Azure Logic Apps Connector Namespaces managed MCP hosting integration with Application Insights.

Problem or Use Case

The Connector Namespaces team has confirmed OTel emission is a blocking requirement for onboarding the Cosmos DB MCP Toolkit to their hosted MCP platform. They need server-level telemetry to provide support for hosted instances.

Today the toolkit only uses ILogger<T> for structured logging — there are no OpenTelemetry.* NuGet references, no OTel configuration in Program.cs, and no OTLP exporter wiring. As a result, hosts cannot get distributed traces across MCP tool invocations, Cosmos DB SDK calls, or embedding requests.

Reference implementation: Azure/data-api-builder already implements this pattern and is the recommended reference for onboarding to Connector Namespaces.

Proposed Solution

1. Add OpenTelemetry .NET SDK packages:
   • OpenTelemetry.Extensions.Hosting
   • OpenTelemetry.Exporter.OpenTelemetryProtocol (OTLP)
   • OpenTelemetry.Instrumentation.AspNetCore
   • OpenTelemetry.Instrumentation.Http
   • OpenTelemetry.Instrumentation.Runtime
2. Wire up traces with a custom ActivitySource (e.g., AzureCosmosDB.MCP.Toolkit) and spans around:
   • Each MCP tool invocation (tool name, request id, duration, success/failure)
   • Cosmos DB SDK calls (account, database, container, operation, RU charge if available)
   • Embedding / OpenAI calls (deployment, model, token usage when available)
   • JWT validation path (when Mode=EntraJwt)
3. Wire up metrics with a Meter (e.g., AzureCosmosDB.MCP.Toolkit):
   • mcp.tool.invocations (counter, dim: tool, status)
   • mcp.tool.duration (histogram, dim: tool)
   • cosmos.request.charge (histogram, dim: operation, container)
   • cosmos.request.duration (histogram)
   • embedding.tokens (counter, dim: model)
4. Bridge ILogger to OTel logs so existing structured logs flow through the OTLP pipeline.
5. Configurable OTLP exporter (env-driven, OTel standard):
   • OTEL_EXPORTER_OTLP_ENDPOINT
   • OTEL_EXPORTER_OTLP_PROTOCOL (grpc | http/protobuf)
   • OTEL_EXPORTER_OTLP_HEADERS
   • OTEL_SERVICE_NAME (default: azure-cosmosdb-mcp-toolkit)
   • OTEL_RESOURCE_ATTRIBUTES
6. No-op by default: if no OTLP endpoint is configured, OTel pipeline registers a no-op exporter so there is zero cost and zero behavior change for existing deployments.
7. Document the contract in README.md / docs/ including the spans/metrics emitted and how to point at App Insights via Azure Monitor OTel Distro.
8. Sanitization: never include connection strings, JWT contents, query bodies, or document payloads in span attributes; rely on operation-level metadata only.

Example Usage

# Hosted by Connector Namespaces (App Insights ingest)
OTEL_EXPORTER_OTLP_ENDPOINT=https://<otel-collector>/v1
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_SERVICE_NAME=azure-cosmosdb-mcp-toolkit
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,service.namespace=cosmos-mcp

Alternatives Considered

• Continue with ILogger only and rely on the host to scrape stdout — rejected; gives no distributed traces or RED metrics and is a blocker for Connector Namespaces onboarding.
• Use Application Insights SDK directly — rejected; OTel is the platform-neutral contract required by the host, and the host already integrates OTLP → App Insights.

Context

Tracking ask from the Connector Namespaces team for onboarding the Cosmos DB MCP Toolkit to their hosted MCP platform. Reference: Azure/data-api-builder, Connector Namespaces docs.