Hector Hernandez (hectorhdzg) · Apr 10, 2026 · Apr 9, 2026 · Apr 9, 2026
@@ -1,113 +1,90 @@
-# microsoft-opentelemetry
+# @microsoft/opentelemetry
 
-TypeScript package for a Microsoft OpenTelemetry distribution that provides a single onboarding experience for observability across Azure Monitor, OTLP-compatible backends, and Microsoft-specific integrations.
+Microsoft OpenTelemetry distribution for Node.js — one import, one call, full observability across Azure Monitor, OTLP-compatible backends, and A365.
 
-This repository starts from the POC described in `azure-data/microsoft-opentelemetry-distro-poc`, but is intentionally kept minimal while the package shape and delivery plan are being defined.
+## Getting Started
 
-## Goal
-
-The target package should reduce fragmented setup across multiple observability stacks to one import and one configuration function.
-
-Intended API shape:
+```bash
+npm install @microsoft/opentelemetry
+```
 
 ```typescript
-import { useMicrosoftOpenTelemetry } from "microsoft-opentelemetry";
+import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
 
 useMicrosoftOpenTelemetry({
   azureMonitor: {
     azureMonitorExporterOptions: {
-      connectionString: "InstrumentationKey=...;IngestionEndpoint=...",
+      connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
     },
   },
 });
 ```
 
-## Planned Scope
-
-- Azure Monitor exporter support
-- OTLP exporter support
-- Microsoft-specific agent observability extensions (A365)
-- GenAI instrumentation toggles for OpenAI and LangChain
-- Standard Node.js web and HTTP instrumentations
-- Environment-variable driven configuration
-- A stable package surface for downstream agent applications
-
-## OTLP Export
-
-OTLP HTTP export is automatically enabled when the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable is set. No code changes are needed — the distro will export traces, metrics, and logs to the specified endpoint.
-
-When OTLP is enabled alongside Azure Monitor, telemetry is sent to both backends simultaneously.
-
-### Supported environment variables
-
-The following standard OpenTelemetry environment variables are supported. General variables apply to all signals; signal-specific variables override the general ones.
-
-| Variable | Description |
-|---|---|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base endpoint for all signals (e.g. `http://localhost:4318`). Signal paths `/v1/traces`, `/v1/metrics`, `/v1/logs` are appended automatically. |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` pairs sent as HTTP headers. |
-| `OTEL_EXPORTER_OTLP_COMPRESSION` | Compression algorithm: `gzip` or `none`. |
-| `OTEL_EXPORTER_OTLP_TIMEOUT` | Export timeout in milliseconds (default: `10000`). |
-| `OTEL_EXPORTER_OTLP_PROTOCOL` | Transport protocol: `http/protobuf` (default) or `http/json`. |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Full endpoint URL for traces. Overrides the base endpoint. |
-| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Additional headers for trace exports. |
-| `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` | Compression for trace exports. |
-| `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` | Timeout for trace exports. |
-| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Full endpoint URL for metrics. |
-| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | Additional headers for metric exports. |
-| `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` | Compression for metric exports. |
-| `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` | Timeout for metric exports. |
-| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Aggregation temporality: `cumulative`, `delta`, or `lowmemory`. |
-| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | `explicit_bucket_histogram` or `base2_exponential_bucket_histogram`. |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Full endpoint URL for logs. |
-| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | Additional headers for log exports. |
-| `OTEL_EXPORTER_OTLP_LOGS_COMPRESSION` | Compression for log exports. |
-| `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT` | Timeout for log exports. |
-
-For the full specification, see the [OpenTelemetry OTLP Exporter Configuration documentation](https://opentelemetry.io/docs/specs/otel/protocol/exporter/).
-
-## Current Repository Layout
-
-- `src/` – package source
-  - `index.ts` – main entry point (`useMicrosoftOpenTelemetry`)
-  - `types.ts` – configuration options (scoped by backend)
-  - `setup/` – modular setup for Azure Monitor, OTLP, A365
-- `azure-monitor-opentelemetry/` – temporary copy of Azure Monitor code (see Phase 3)
-- `tests/` – test suite
-- `package.json` – project metadata and dependencies
-- `tsconfig.json` – TypeScript compiler configuration
-- `PLANNING.md` – implementation plan and open questions
-
-## Development
-
-Install dependencies and run the build and test suite:
+That's it — traces, metrics, and logs are collected automatically with built-in instrumentations for HTTP, databases, and more.
 
-```bash
-npm install
-npm run build
-npm run lint
-npm test
-```
+## Configuration
 
-## Reference
+### `MicrosoftOpenTelemetryOptions`
 
-- POC repo: https://github.com/azure-data/microsoft-opentelemetry-distro-poc
-- Planning document: [PLANNING.md](./PLANNING.md)
-- Python distro: https://github.com/microsoft/opentelemetry-distro-python
+| 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 (HTTP, MongoDB, MySQL, PostgreSQL, Redis, Azure SDK, Azure Functions, Winston, Bunyan, OpenAI Agents, LangChain) |
+| `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 (see below) |
+| `a365` | `A365Options` | — | A365 observability config |
 
-## Contributing
+### `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` | — | Application Insights browser SDK loader config |
+
+### OTLP via environment variables
 
-Read our [contributing guide](./CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to this distribution.
+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.
 
-## Data Collection
+See the [OpenTelemetry OTLP Exporter specification](https://opentelemetry.io/docs/specs/otel/protocol/exporter/) for the full list.
 
-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.
+### Example
 
-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.
+```typescript
+import { useMicrosoftOpenTelemetry, shutdownMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 
-## Trademarks
+useMicrosoftOpenTelemetry({
+  resource: resourceFromAttributes({ "service.name": "my-app" }),
+  samplingRatio: 0.5,
+  azureMonitor: {
+    azureMonitorExporterOptions: {
+      connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
+    },
+    enableLiveMetrics: true,
+  },
+});
+
+// On shutdown
+await shutdownMicrosoftOpenTelemetry();
+```
+
+## Samples
+
+See the [samples/](./samples/) directory for working TypeScript examples covering connection setup, custom metrics, custom traces, sampling, OTLP dual-export, and more.
+
+
+## Contributing
 
-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](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). 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.
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 

@@ -0,0 +1,72 @@
+---
+page_type: sample
+languages:
+  - typescript
+products:
+  - azure-monitor
+urlFragment: microsoft-opentelemetry-typescript
+---
+
+# Microsoft OpenTelemetry distribution samples for TypeScript
+
+These sample programs show how to use the `@microsoft/opentelemetry` distribution in common scenarios.
+
+| **File Name**                               | **Description**                                                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [basicConnection.ts][basicconnection]       | Demonstrates how to configure Microsoft OpenTelemetry using a connection string.                         |
+| [cloudRole.ts][cloudrole]                   | Demonstrates how to set Cloud Role Name and Cloud Role Instance using OpenTelemetry Resource attributes. |
+| [customMetric.ts][custommetric]             | Demonstrates how to generate custom metrics that will be sent to Azure Monitor.                          |
+| [customTrace.ts][customtrace]               | Demonstrates how to generate custom traces that will be sent to Azure Monitor.                           |
+| [liveMetrics.ts][livemetrics]               | Demonstrates how to enable or disable Live Metrics for real-time monitoring.                             |
+| [offlineStorage.ts][offlinestorage]         | Demonstrates how to configure offline storage and automatic retries for telemetry.                       |
+| [otlpExporter.ts][otlpexporter]             | Demonstrates how to enable the OTLP exporter alongside Azure Monitor to send telemetry to two locations. |
+| [redactQueryStrings.ts][redactquerystrings] | Demonstrates how to redact URL query strings from telemetry to protect sensitive information.            |
+| [sampling.ts][sampling]                     | Demonstrates how to enable sampling to reduce data ingestion volume and control costs.                   |
+
+## Prerequisites
+
+- [Node.js LTS](https://github.com/nodejs/release#release-schedule) (>= 20.0.0)
+- [TypeScript](https://www.typescriptlang.org/) (install via `npm install -g typescript`)
+- An [Azure subscription](https://azure.microsoft.com/free/) with an [Application Insights](https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview) resource
+
+## Setup
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Compile the samples:
+
+```bash
+npm run build
+```
+
+3. Copy `sample.env` to `.env` and fill in your connection string:
+
+```bash
+cp sample.env .env
+```
+
+4. Run a sample:
+
+```bash
+node dist/basicConnection.js
+```
+
+Or pass the connection string directly:
+
+```bash
+APPLICATIONINSIGHTS_CONNECTION_STRING="<your connection string>" node dist/basicConnection.js
+```
+
+[basicconnection]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/basicConnection.ts
+[cloudrole]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/cloudRole.ts
+[custommetric]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/customMetric.ts
+[customtrace]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/customTrace.ts
+[livemetrics]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/liveMetrics.ts
+[offlinestorage]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/offlineStorage.ts
+[otlpexporter]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/otlpExporter.ts
+[redactquerystrings]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/redactQueryStrings.ts
+[sampling]: https://github.com/Azure/opentelemetry-distro-javascript/blob/main/samples/src/sampling.ts
@@ -0,0 +1,33 @@
+{
+  "name": "@microsoft/opentelemetry-samples",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Microsoft OpenTelemetry distribution samples for TypeScript",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prebuild": "rimraf dist/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Azure/opentelemetry-distro-javascript"
+  },
+  "author": "Microsoft Corporation",
+  "license": "MIT",
+  "dependencies": {
+    "@microsoft/opentelemetry": "latest",
+    "dotenv": "latest",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "rimraf": "latest",
+    "typescript": "~5.9.3"
+  }
+}
@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * @summary Demonstrates how to configure Microsoft OpenTelemetry using a connection string.
+ */
+
+import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
+import "dotenv/config";
+
+async function main(): Promise<void> {
+  useMicrosoftOpenTelemetry({
+    azureMonitor: {
+      azureMonitorExporterOptions: {
+        connectionString:
+          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<your connection string>",
+      },
+    },
+  });
+
+  console.log("Microsoft OpenTelemetry configured successfully!");
+  console.log("Telemetry will be sent to Azure Application Insights");
+}
+
+main().catch(console.error);
@@ -5,7 +5,7 @@
  * @summary Demonstrates how to set Cloud Role Name and Cloud Role Instance using OpenTelemetry Resource attributes.
  */
 
-import { useAzureMonitor } from "@azure/monitor-opentelemetry";
+import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import "dotenv/config";
@@ -17,17 +17,17 @@ async function main(): Promise<void> {
     "service.instance.id": process.env.OTEL_SERVICE_INSTANCE_ID || "my-instance",
   });
 
-  const options = {
+  useMicrosoftOpenTelemetry({
     resource: customResource,
-    azureMonitorExporterOptions: {
-      connectionString:
-        process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<your connection string>",
+    azureMonitor: {
+      azureMonitorExporterOptions: {
+        connectionString:
+          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<your connection string>",
+      },
     },
-  };
-
-  useAzureMonitor(options);
+  });
 
-  console.log("Azure Monitor configured with custom cloud role settings:");
+  console.log("Microsoft OpenTelemetry configured with custom cloud role settings:");
   console.log(
     `  Cloud Role Name: ${process.env.OTEL_SERVICE_NAMESPACE || "my-namespace"}.${process.env.OTEL_SERVICE_NAME || "my-service"}`,
   );

@@ -5,19 +5,22 @@
  * @summary Demonstrates how to generate custom metrics that will be sent to Azure Monitor.
  */
 
-import { useAzureMonitor, shutdownAzureMonitor } from "@azure/monitor-opentelemetry";
+import {
+  useMicrosoftOpenTelemetry,
+  shutdownMicrosoftOpenTelemetry,
+} from "@microsoft/opentelemetry";
 import { metrics } from "@opentelemetry/api";
 import "dotenv/config";
 
 async function main(): Promise<void> {
-  const options = {
-    azureMonitorExporterOptions: {
-      connectionString:
-        process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<your connection string>",
+  useMicrosoftOpenTelemetry({
+    azureMonitor: {
+      azureMonitorExporterOptions: {
+        connectionString:
+          process.env.APPLICATIONINSIGHTS_CONNECTION_STRING || "<your connection string>",
+      },
     },
-  };
-
-  useAzureMonitor(options);
+  });
 
   const meter = metrics.getMeter("testMeter");
   const customCounter = meter.createCounter("TestCounter");
@@ -27,7 +30,7 @@ async function main(): Promise<void> {
 
   console.log("Custom metrics sent to Azure Monitor");
 
-  await shutdownAzureMonitor();
+  await shutdownMicrosoftOpenTelemetry();
 }
 
 main().catch(console.error);