Instrument applications with Microsoft OpenTelemetry Distro

Use this article to understand built-in instrumentation, autoinstrumentation, baggage, middleware, and manual scopes in Microsoft OpenTelemetry Distro.

Built-in instrumentation

The Microsoft OpenTelemetry Distro combines standard OpenTelemetry pipelines with Microsoft-curated instrumentation. The Distro can collect application telemetry, infrastructure telemetry, and agent or generative AI telemetry depending on language and configuration.

Category	What it covers
Signal pipelines	Traces, metrics, and logs.
Resource detection	Service, host, cloud, and Azure runtime context where supported.
Infrastructure instrumentation	HTTP, ASP.NET Core, Azure SDK, database clients, and logging frameworks where supported.
Generative AI instrumentation	OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK, and Agent Framework where supported.
Manual agent scopes	Agent invocation, tool execution, inference, and output telemetry where supported.
Exporters and processors	Azure Monitor, Microsoft Agent 365, OTLP, console output, span processors, log processors, and metric readers.

Instrumentation coverage

Language	Common application instrumentation	Common agent and generative AI instrumentation
Python	OpenTelemetry resources, processors, readers, logging, metrics, and traces.	Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 baggage, and Microsoft Agent 365 scopes.
Node.js	HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan, and Winston.	OpenAI Agents SDK, LangChain, Microsoft Agent 365 baggage, and Microsoft Agent 365 scopes.
.NET	ASP.NET Core, HttpClient, SQL Client, Azure SDK, resource detection, metrics, and logs.	Semantic Kernel, OpenAI and Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage, and Microsoft Agent 365 scopes.

Automatic instrumentation listens to telemetry signals emitted by supported libraries and frameworks. Manual instrumentation is used when an application needs to describe agent-specific operations, such as invocation, tool execution, inference, or asynchronous output.

Add custom OpenTelemetry sources, meters, processors, or readers when your application emits telemetry that isn't covered by the built-in instrumentations.

Autoinstrumentation

Auto-instrumentation listens to telemetry emitted by supported frameworks and forwards it through the Distro's OpenTelemetry pipeline. For agent scenarios, set baggage such as tenant ID and agent ID before the instrumented framework creates spans.

Framework	Python	Node.js	.NET
Semantic Kernel	Supported	Not supported	Supported
OpenAI and OpenAI Agents SDK	Supported	Supported	Supported
Agent Framework	Supported	Not supported	Supported
LangChain	Supported	Supported	Not listed

Semantic Kernel

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

Node.js

Semantic Kernel auto-instrumentation isn't supported for Node.js.

.NET

Semantic Kernel instrumentation is enabled by default. To disable it, set the instrumentation option explicitly.

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableSemanticKernelInstrumentation = false;
});

OpenAI

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

Node.js

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    openaiAgents: { enabled: true },
  },
});

.NET

OpenAI and Azure OpenAI instrumentation is enabled by default. To disable it, set the instrumentation option explicitly.

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableOpenAIInstrumentation = false;
});

Agent Framework

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

Node.js

Agent Framework auto-instrumentation isn't supported for Node.js.

.NET

Agent Framework instrumentation is enabled by default. To disable it, set the instrumentation option explicitly.

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableAgentFrameworkInstrumentation = false;
});

LangChain

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

Node.js

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    langchain: { enabled: true },
  },
});

.NET

LangChain auto-instrumentation isn't listed for .NET.

Baggage

Baggage carries contextual attributes through the active OpenTelemetry context so spans created during a request can share identifiers such as tenant ID, agent ID, and conversation ID. Use baggage before starting auto-instrumented framework operations or manual scopes that need that context.

Python

from microsoft.opentelemetry.a365.core import BaggageBuilder

baggage_scope = (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
)

with baggage_scope:
    # Spans created in this context can receive these baggage values.
    pass

Node.js

import { BaggageBuilder } from "@microsoft/opentelemetry";

const baggageScope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .conversationId("conv-789")
  .build();

await baggageScope.run(async () => {
  // Spans created in this context can receive these baggage values.
});

.NET

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();

// Spans created in this context can receive these baggage values.

Baggage values should be set from the authoritative request context for the product surface. Avoid storing secrets or credentials in baggage.

Baggage middleware

Baggage middleware can populate context for incoming requests so application code doesn't need to build baggage manually for every activity. Use hosting middleware when your product surface provides the required tenant, agent, caller, channel, and conversation context.

Python

Register middleware directly on the adapter.

from microsoft.opentelemetry.a365.hosting.middleware import BaggageMiddleware

adapter.use(BaggageMiddleware())

Alternatively, use the hosting manager when you need to configure hosting features together.

from microsoft.opentelemetry.a365.hosting.middleware import (
    ObservabilityHostingManager,
    ObservabilityHostingOptions,
)

manager = ObservabilityHostingManager()
manager.configure(adapter, ObservabilityHostingOptions(enable_baggage=True))

Node.js

Register middleware directly on the adapter.

import { BaggageMiddleware } from "@microsoft/opentelemetry";

adapter.use(new BaggageMiddleware());

Alternatively, use the hosting manager when you need to configure hosting features together.

import { ObservabilityHostingManager } from "@microsoft/opentelemetry";

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

To populate baggage from a turn context explicitly, use the helper.

import { BaggageBuilder, BaggageBuilderUtils } from "@microsoft/opentelemetry";

const baggageScope = BaggageBuilderUtils
  .fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is populated from the turn context activity.
});

.NET

Register turn-level middleware on the adapter when the hosting integration is available.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

For HTTP-level context, register request context middleware before the agent pipeline runs.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

Middleware should avoid overwriting baggage that was already established by an originating request.

Manual instrumentation

Use manual instrumentation when automatic instrumentation doesn't describe the agent operation with enough detail. Manual scopes let an application describe common agent activities in a consistent way across languages.

Scope	Use for
InvokeAgentScope	The start and completion of an agent invocation.
ExecuteToolScope	A tool call made by an agent.
InferenceScope	An AI model inference operation.
OutputScope	Output that must be recorded after the originating scope has already completed.

Reuse the same request and agent identity values across scopes in a request so related telemetry can be correlated.

Agent invocation

Python

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

Node.js

import { InvokeAgentScope } from "@microsoft/opentelemetry";
import type {
  AgentDetails,
  A365Request,
  InvokeAgentScopeDetails,
} from "@microsoft/opentelemetry";

const agentDetails: AgentDetails = {
  agentId: "agent-456",
  agentName: "Email Assistant",
  agentDescription: "An AI agent powered by Azure OpenAI",
  agentAUID: "auid-123",
  agentEmail: "agent@contoso.com",
  agentBlueprintId: "blueprint-789",
  tenantId: "tenant-123",
};

const request: A365Request = {
  content: "Please help me organize my emails",
  sessionId: "session-42",
  conversationId: "conv-xyz",
  channel: { name: "msteams" },
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: "myagent.contoso.com", port: 443 },
};

const invokeScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    invokeScope.recordInputMessages(["Please help me organize my emails"]);

    // Run the agent invocation.

    invokeScope.recordOutputMessages(["I found 15 urgent emails."]);
  });
} catch (error) {
  invokeScope.recordError(error as Error);
  throw error;
} finally {
  invokeScope.dispose();
}

.NET

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

var agentDetails = new AgentDetails(
    agentId: "agent-456",
    agentName: "Email Assistant",
    agentDescription: "An AI agent powered by Azure OpenAI",
    agenticUserId: "auid-123",
    agenticUserEmail: "agent@contoso.com",
    agentBlueprintId: "blueprint-789",
    tenantId: "tenant-123");

var request = new Request(
    content: "Please help me organize my emails",
    sessionId: "session-42",
    conversationId: "conv-xyz",
    channel: new Channel(name: "msteams"));

var scopeDetails = new InvokeAgentScopeDetails(
    endpoint: new Uri("https://myagent.contoso.com"));

using var invokeScope = InvokeAgentScope.Start(
    request: request,
    scopeDetails: scopeDetails,
    agentDetails: agentDetails);

invokeScope.RecordInputMessages(new[] { "Please help me organize my emails" });

// Run the agent invocation.

invokeScope.RecordOutputMessages(new[] { "I found 15 urgent emails." });

Tool execution

Python

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

with ExecuteToolScope.start(
    request=request,
    details=tool_details,
    agent_details=agent_details,
) as scope:
    result = search_emails(tool_details.arguments)
    scope.record_response(result)

Node.js

import { ExecuteToolScope } from "@microsoft/opentelemetry";
import type { ToolCallDetails } from "@microsoft/opentelemetry";

const toolDetails: ToolCallDetails = {
  toolName: "email-search",
  arguments: JSON.stringify({ query: "from:manager@contoso.com" }),
  toolCallId: "tool-call-456",
  description: "Search emails by criteria",
  toolType: "function",
  endpoint: {
    host: "tools.contoso.com",
    port: 8080,
    protocol: "https",
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

.NET

var toolDetails = new ToolCallDetails(
    toolName: "email-search",
    arguments: "{\"query\": \"from:manager@contoso.com\"}",
    toolCallId: "tool-call-456",
    description: "Search emails by criteria",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080"));

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolDetails,
    agentDetails: agentDetails);

// Execute the tool.

scope.RecordResponse("{\"count\": 15}");

Inference

Python

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

Node.js

import { InferenceOperationType, InferenceScope } from "@microsoft/opentelemetry";
import type { InferenceDetails } from "@microsoft/opentelemetry";

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: "gpt-4o-mini",
  providerName: "azure-openai",
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    scope.recordInputMessages(["Summarize the following emails for me."]);
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
    scope.recordFinishReasons(["stop"]);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

.NET

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI");

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails);

scope.RecordInputMessages(new[] { "Summarize the following emails for me." });

// Call the model.

scope.RecordOutputMessages(new[] { "Here is your email summary." });
scope.RecordInputTokens(145);
scope.RecordOutputTokens(82);
scope.RecordFinishReasons(new[] { "stop" });

Output

Python

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

Node.js

import { OutputScope } from "@microsoft/opentelemetry";
import type { A365SpanDetails, OutputResponse } from "@microsoft/opentelemetry";

// Capture this before disposing the originating InvokeAgentScope.
const parentContext = invokeScope.getSpanContext();
const response: OutputResponse = {
  messages: ["Here is your organized inbox."],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined,
  { parentContext } as A365SpanDetails
);

scope.dispose();

.NET

// Capture this before disposing the originating InvokeAgentScope.
var parentContext = invokeScope.GetActivityContext();
var response = new Response(new[] { "Here is your organized inbox." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext));

Product documentation should define any product-specific validation requirements for these scopes.

Next steps

• Configure Microsoft OpenTelemetry Distro
• Validate Microsoft OpenTelemetry Distro locally