@microsoft/opentelemetry

Microsoft OpenTelemetry distribution for Node.js — one import, one call, full observability across Azure Monitor, OTLP-compatible backends, and A365.

Getting Started

npm install @microsoft/opentelemetry

Important: Import and call useMicrosoftOpenTelemetry() as early as possible in your application entry point so instrumentations can patch libraries before they are loaded.

ESM Support

Note: ESM support requires Node.js 20.6.0 or later. This package's ESM loader flow relies on --import and node:module.register(), which are not available on older Node.js releases. For background on why startup ordering matters, see the OpenTelemetry ESM Support documentation.

For ESM applications, instrumentation hooks must be registered before any instrumented modules (for example http, express, axios, or loggers) are loaded. This is a fundamental ESM constraint: modules cannot be instrumented after they are already loaded.

This pattern is not reliable for auto-instrumentation:

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

import express from "express";

Use --import so the loader is registered at process startup.

node --import @microsoft/opentelemetry/loader ./app.mjs

For example, in package.json:

{
  "scripts": {
    "start": "node --import @microsoft/opentelemetry/loader ./dist/index.js"
  }
}

If you prefer explicit telemetry configuration in a bootstrap file, preload that file instead:

telemetry.mjs:

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

useMicrosoftOpenTelemetry({
  azureMonitor: {
    azureMonitorExporterOptions: {
      connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
    },
    enableLiveMetrics: false,
  },
  instrumentationOptions: {
    bunyan: { enabled: true },
    winston: { enabled: true },
  },
});

Start your app:

node --import ./telemetry.mjs ./app.mjs

Your application code can keep regular static ESM imports in app.mjs.

A365

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

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId, tenantId) => getToken(agentId, tenantId),
  },
});

For A365 scenarios, scope APIs, baggage, hosting middleware, and official terminology alignment, see A365_DOCUMENTATION.md.

Azure Monitor

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

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

OTLP only (no Azure Monitor)

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

// Set OTEL_EXPORTER_OTLP_ENDPOINT in your environment
useMicrosoftOpenTelemetry();

That's it — traces, metrics, and logs are collected automatically with built-in instrumentations for HTTP, databases, and more.

Configuration

`MicrosoftOpenTelemetryOptions`

Option	Type	Default	Description
`resource`	`Resource`	auto-detected	OpenTelemetry Resource (service name, version, etc.)
`samplingRatio`	`number`	`1.0`	Ratio of telemetry items to transmit (0.0–1.0)
`tracesPerSecond`	`number`	`5`	Max traces per second. Set to `0` to use `samplingRatio` instead
`instrumentationOptions`	`InstrumentationOptions`	all enabled	Toggle built-in instrumentations (see below)
`spanProcessors`	`SpanProcessor[]`	—	Additional span processors
`logRecordProcessors`	`LogRecordProcessor[]`	—	Additional log record processors
`metricReaders`	`MetricReader[]`	—	Additional metric readers
`views`	`ViewOptions[]`	—	Metric views
`azureMonitor`	`AzureMonitorOpenTelemetryOptions`	—	Azure Monitor backend config. When provided, Azure Monitor export is enabled
`a365`	`A365Options`	—	A365 observability config
`enableConsoleExporters`	`boolean`	auto	Enable console exporters for traces, metrics, and logs

`InstrumentationOptions`

Most instrumentations use InstrumentationConfig shape ({ enabled?: boolean, ... }).

Built-in infra instrumentations (http, azureSdk, mongoDb, mySql, postgreSql, redis, redis4) are enabled by default.
Logging instrumentations (bunyan, winston) are disabled by default.
GenAI instrumentations (openaiAgents, langchain) are enabled by default.
When a365.enabled is true, non-GenAI instrumentations (http, azureSdk, DB/cache, and logging) are disabled by default unless explicitly set in instrumentationOptions.

Set enabled: true or enabled: false explicitly for predictable behavior.

Key	Type	Default	Description
`http`	`InstrumentationConfig`	enabled	HTTP client/server instrumentation
`azureSdk`	`InstrumentationConfig`	enabled	Azure SDK instrumentation
`mongoDb`	`InstrumentationConfig`	enabled	MongoDB instrumentation
`mySql`	`InstrumentationConfig`	enabled	MySQL instrumentation
`postgreSql`	`InstrumentationConfig`	enabled	PostgreSQL instrumentation
`redis`	`InstrumentationConfig`	enabled	Redis instrumentation
`redis4`	`InstrumentationConfig`	enabled	Redis 4 instrumentation
`bunyan`	`InstrumentationConfig`	disabled	Bunyan log instrumentation
`winston`	`InstrumentationConfig`	disabled	Winston log instrumentation
`openaiAgents`	`OpenAIAgentsInstrumentationConfig`	enabled	OpenAI Agents SDK instrumentation (requires `@openai/agents`)
`langchain`	`LangChainInstrumentationConfig`	enabled	LangChain instrumentation (requires `@langchain/core`)

Turn instrumentations on/off

useMicrosoftOpenTelemetry({
  instrumentationOptions: {
    // Disable specific built-in instrumentations
    http: { enabled: false },
    redis: { enabled: false },

    // Enable GenAI instrumentations
    openaiAgents: {
      enabled: true,
      isContentRecordingEnabled: true,
    },
    langchain: {
      enabled: true,
      isContentRecordingEnabled: true,
    },
  },
});

Disable most built-in auto-instrumentation:

useMicrosoftOpenTelemetry({
  instrumentationOptions: {
    http: { enabled: false },
    azureSdk: { enabled: false },
    azureFunctions: { enabled: false },
    mongoDb: { enabled: false },
    mySql: { enabled: false },
    postgreSql: { enabled: false },
    redis: { enabled: false },
    redis4: { enabled: false },
    bunyan: { enabled: false },
    winston: { enabled: false },
    openaiAgents: { enabled: false },
    langchain: { enabled: false },
  },
});

Console exporters

Use console exporters when validating local telemetry or debugging setup.

useMicrosoftOpenTelemetry({
  enableConsoleExporters: true,
});

Behavior:

enableConsoleExporters: true: always enable console exporters (traces, metrics, logs).
enableConsoleExporters: false: do not auto-add the standard console exporters.
Omitted: console exporters auto-enable only when no other exporter path is active.

`azureMonitor` options

Option	Type	Default	Description
`azureMonitorExporterOptions`	`AzureMonitorExporterOptions`	—	Exporter config including `connectionString`, `storageDirectory`, `disableOfflineStorage`
`enableLiveMetrics`	`boolean`	`true`	Enable Live Metrics streaming
`enableStandardMetrics`	`boolean`	`true`	Enable standard metrics collection
`enableTraceBasedSamplingForLogs`	`boolean`	`false`	Enable log sampling based on trace
`enablePerformanceCounters`	`boolean`	`true`	Enable performance counter collection
`browserSdkLoaderOptions`	`BrowserSdkLoaderOptions`	disabled	Application Insights browser SDK loader config (`enabled`, `connectionString`)

OTLP via environment variables

Set OTEL_EXPORTER_OTLP_ENDPOINT and OTLP export is enabled automatically — no code changes needed. Signal-specific variables (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, etc.) override the base endpoint.

See the OpenTelemetry OTLP Exporter specification for the full list.

`a365` options

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enable A365 observability. Registers the `A365SpanProcessor` for baggage/attribute enrichment of downstream exporters (Azure Monitor, OTLP, console). Does not send data to the A365 service on its own — set `enableObservabilityExporter` for that
`enableObservabilityExporter`	`boolean`	`false`	Enable the A365 HTTP exporter (`Agent365Exporter`) to send spans to the A365 observability service. Requires `enabled: true`. Equivalent to `ENABLE_A365_OBSERVABILITY_EXPORTER` env var
`tokenResolver`	`(agentId, tenantId, authScopes?) => string \| Promise<string>`	—	Token resolver for A365 service authentication
`clusterCategory`	`ClusterCategory`	`"prod"`	Cluster category for endpoint resolution (`local`, `dev`, `test`, `preprod`, `firstrelease`, `prod`, `gov`, `high`, `dod`, `mooncake`, `ex`, `rx`)
`domainOverride`	`string`	—	Override the A365 observability service domain
`authScopes`	`string[]`	`["api://9b975845-388f-4429-889e-eab1ef63949c/.default"]`	OAuth scopes for A365 service authentication
`observabilityScopeOverride`	`string`	—	Single-string scope override (highest precedence). Equivalent to `A365_OBSERVABILITY_SCOPES_OVERRIDE` env var
`logLevel`	`string`	`"none"`	A365 internal log level: `none`, `info`, `warn`, `error`, or pipe-separated combination. Overrides `A365_OBSERVABILITY_LOG_LEVEL` env var
`useS2SEndpoint`	`boolean`	`false`	Use the S2S (service-to-service) endpoint path for export

When A365 export is enabled, the distro defaults to GenAI-focused telemetry. To opt back into non-GenAI auto-instrumentation, set explicit overrides:

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId, tenantId) => getToken(agentId, tenantId),
  },
  instrumentationOptions: {
    http: { enabled: true },
    azureSdk: { enabled: true },
    mongoDb: { enabled: true },
    mySql: { enabled: true },
    postgreSql: { enabled: true },
    redis: { enabled: true },
    redis4: { enabled: true },
    bunyan: { enabled: true },
    winston: { enabled: true },
  },
});

A365 hosting middleware setup

Hosting middleware is configured separately from a365 exporter options. To use A365 hosting middleware, attach it to your adapter explicitly.

Use the one-liner helper:

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

configureA365Hosting(adapter);

By default this registers both BaggageMiddleware and OutputLoggingMiddleware.

OutputLoggingMiddleware captures outgoing message content as span attributes. If your responses may contain sensitive content, disable output logging:

configureA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: false,
});

If you need explicit flags:

configureA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: true,
});

For previously published package versions that do not include configureA365Hosting, use:

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

new ObservabilityHostingManager().configure(adapter as unknown as { use(...m: unknown[]): void }, {
  enableBaggage: true,
  enableOutputLogging: true,
});

A365 exporter tuning

Option	Type	Default	Description
`maxQueueSize`	`number`	`2048`	Maximum span queue size before drops occur
`scheduledDelayMilliseconds`	`number`	`5000`	Delay (ms) between automatic batch flush attempts
`exporterTimeoutMilliseconds`	`number`	`90000`	Maximum time (ms) for the entire export call
`httpRequestTimeoutMilliseconds`	`number`	`30000`	HTTP request timeout (ms) when sending spans to A365 service
`maxExportBatchSize`	`number`	`512`	Maximum number of spans per export batch
`maxPayloadBytes`	`number`	—	Maximum estimated payload size (bytes) per HTTP chunk

Example:

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId, tenantId) => getToken(agentId, tenantId),
    maxQueueSize: 4096,
    maxExportBatchSize: 1024,
    scheduledDelayMilliseconds: 10000,
    httpRequestTimeoutMilliseconds: 15000,
  },
});

A365 environment variables

A365 options can also be set via environment variables (highest precedence):

Environment Variable	Description
`ENABLE_A365_OBSERVABILITY_EXPORTER`	`"true"` / `"false"` — override `enabled`
`A365_OBSERVABILITY_SCOPES_OVERRIDE`	Space-separated list of OAuth scopes
`A365_OBSERVABILITY_DOMAIN_OVERRIDE`	Override service domain
`CLUSTER_CATEGORY`	Override cluster category
`A365_OBSERVABILITY_LOG_LEVEL`	A365 internal logger filter level (`none`, `info`, `warn`, `error`, or pipe-delimited combination) — overrides `observabilityLogLevel`
`A365_PER_REQUEST_MAX_TRACES`	Max buffered traces (default: `1000`)
`A365_PER_REQUEST_MAX_SPANS_PER_TRACE`	Max spans per trace (default: `5000`)
`A365_PER_REQUEST_MAX_CONCURRENT_EXPORTS`	Max concurrent exports (default: `20`)
`A365_PER_REQUEST_FLUSH_GRACE_MS`	Grace period after root span ends (default: `250`)
`A365_PER_REQUEST_MAX_TRACE_AGE_MS`	Max trace age before forced flush (default: `1800000`)

Example

import { useMicrosoftOpenTelemetry, shutdownMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
import { resourceFromAttributes } from "@opentelemetry/resources";

useMicrosoftOpenTelemetry({
  resource: resourceFromAttributes({ "service.name": "my-app" }),
  samplingRatio: 0.5,
  azureMonitor: {
    azureMonitorExporterOptions: {
      connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
    },
  },
});

// On shutdown
await shutdownMicrosoftOpenTelemetry();

Guides

Fabric Getting Started — Send telemetry to Microsoft Fabric / Azure Data Explorer via OTLP + OTel Collector

Samples

See the samples/ directory for working TypeScript examples covering connection setup, custom metrics, custom traces, sampling, OTLP dual-export, and more.

Contributing

See CONTRIBUTING.md.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Data Collection

As this SDK is designed to enable applications to perform data collection which is sent to the Microsoft collection endpoints the following is required to identify our privacy statement.

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Internal Telemetry

Internal telemetry can be disabled by setting the environment variable APPLICATIONINSIGHTS_STATSBEAT_DISABLED to true.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

Reporting Security Issues

See SECURITY.md for information on reporting vulnerabilities.

License

MIT

@microsoft/opentelemetry

@microsoft/opentelemetry

Getting Started

ESM Support

A365

Azure Monitor

OTLP only (no Azure Monitor)

Configuration

`MicrosoftOpenTelemetryOptions`

`InstrumentationOptions`

Turn instrumentations on/off

Console exporters

`azureMonitor` options

OTLP via environment variables

`a365` options

A365 hosting middleware setup

A365 exporter tuning

A365 environment variables

Example

Guides

Samples

Contributing

Data Collection

Internal Telemetry

Trademarks

Reporting Security Issues

License

Settings

On This Page

@microsoft/opentelemetry

@microsoft/opentelemetry

Getting Started

ESM Support

A365

Azure Monitor

OTLP only (no Azure Monitor)

Configuration

MicrosoftOpenTelemetryOptions

InstrumentationOptions

Turn instrumentations on/off

Console exporters

azureMonitor options

OTLP via environment variables

a365 options

A365 hosting middleware setup

A365 exporter tuning

A365 environment variables

Example

Guides

Samples

Contributing

Data Collection

Internal Telemetry

Trademarks

Reporting Security Issues

License

Settings

On This Page

`MicrosoftOpenTelemetryOptions`

`InstrumentationOptions`

`azureMonitor` options

`a365` options