Get started with Microsoft OpenTelemetry Distro

This guidance shows you how to add observability to your application with Microsoft OpenTelemetry Distro. The Distro automatically collects traces, metrics, and logs with built-in instrumentations, and exports the telemetry to Azure Monitor, any OpenTelemetry Protocol (OTLP) endpoint, or Microsoft Agent 365.

Install the package

The Microsoft OpenTelemetry Distro package identifiers and install commands are:

Language	Package	Install command
Python	microsoft-opentelemetry	pip install microsoft-opentelemetry
Node.js	@microsoft/opentelemetry	npm install @microsoft/opentelemetry
.NET	Microsoft.OpenTelemetry	dotnet add package Microsoft.OpenTelemetry

Initialize the Distro

Distro initialization follows the same conceptual flow across supported languages:

1. Initialize the Distro early enough for automatic instrumentations to observe the libraries and frameworks used by the application.
2. Select the destination categories that apply to the scenario, such as Azure Monitor, Microsoft Agent 365, OTLP, or local development output.
3. Use Distro defaults for resource detection, signal pipelines, exporters, processors, and built-in instrumentations.
4. Add application-specific OpenTelemetry sources or meters when the application emits custom telemetry outside the Distro defaults.
5. Ensure the application flushes telemetry during shutdown when the language runtime or hosting model requires it.

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Node.js

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

useMicrosoftOpenTelemetry();

.NET

using Microsoft.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.OtlpEndpoint = new Uri("http://localhost:4317");
    });

var app = builder.Build();
app.Run();

Configure destinations

Use Distro configuration to choose the destination categories for the application. The exact destination setup depends on the product surface, but the common Distro configuration pattern is to initialize the Distro and provide destination options.

Azure Monitor

Python

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    azure_monitor_connection_string="InstrumentationKey=...;IngestionEndpoint=...",
)

Node.js

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

useMicrosoftOpenTelemetry({
  azureMonitor: {
    azureMonitorExporterOptions: {
      connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
    },
  },
});

.NET

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.Exporters = ExportTarget.AzureMonitor;
        o.AzureMonitor.ConnectionString = "InstrumentationKey=...";
    });

OpenTelemetry Protocol (OTLP)

Python

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Node.js

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

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

useMicrosoftOpenTelemetry();

.NET

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.Exporters = ExportTarget.Otlp;
        o.OtlpEndpoint = new Uri("http://localhost:4317");
    });

Microsoft Agent 365

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,
    a365_cluster_category="prod",
)

Node.js

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

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

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
    clusterCategory: "prod",
  },
});

.NET

builder.Services.AddOpenTelemetry()
    .UseMicrosoftOpenTelemetry(o =>
    {
        o.Exporters = ExportTarget.Agent365;
        o.Agent365.Exporter.TokenResolver = (agentId, tenantId) =>
            tokenProvider.GetTokenAsync(agentId, tenantId);
    });

Next steps

• What is Microsoft OpenTelemetry Distro?
• Configure Microsoft OpenTelemetry Distro
• Instrument applications with Microsoft OpenTelemetry Distro
• Validate Microsoft OpenTelemetry Distro locally
• OpenTelemetry documentation
• Microsoft Agent 365 overview
• Microsoft Foundry overview
• Azure Monitor overview