Azure Monitor Opentelemetry Ts

1---
2name: azure-monitor-opentelemetry-ts
3description: Instrument applications with Azure Monitor and OpenTelemetry for JavaScript (@azure/monitor-opentelemetry). Use when adding distributed tracing, metrics, and logs to Node.js applications with Application Insights.
4package: "@azure/monitor-opentelemetry"
5---
6 
7# Azure Monitor OpenTelemetry SDK for TypeScript
8 
9Auto-instrument Node.js applications with distributed tracing, metrics, and logs.
10 
11## Installation
12 
13```bash
14# Distro (recommended - auto-instrumentation)
15npm install @azure/monitor-opentelemetry
16 
17# Low-level exporters (custom OpenTelemetry setup)
18npm install @azure/monitor-opentelemetry-exporter
19 
20# Custom logs ingestion
21npm install @azure/monitor-ingestion
22```
23 
24## Environment Variables
25 
26```bash
27APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...;IngestionEndpoint=...
28```
29 
30## Quick Start (Auto-Instrumentation)
31 
32**IMPORTANT:** Call `useAzureMonitor()` BEFORE importing other modules.
33 
34```typescript
35import { useAzureMonitor } from "@azure/monitor-opentelemetry";
36 
37useAzureMonitor({
38  azureMonitorExporterOptions: {
39    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
40  }
41});
42 
43// Now import your application
44import express from "express";
45const app = express();
46```
47 
48## ESM Support (Node.js 18.19+)
49 
50```bash
51node --import @azure/monitor-opentelemetry/loader ./dist/index.js
52```
53 
54**package.json:**
55```json
56{
57  "scripts": {
58    "start": "node --import @azure/monitor-opentelemetry/loader ./dist/index.js"
59  }
60}
61```
62 
63## Full Configuration
64 
65```typescript
66import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
67import { resourceFromAttributes } from "@opentelemetry/resources";
68 
69const options: AzureMonitorOpenTelemetryOptions = {
70  azureMonitorExporterOptions: {
71    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
72    storageDirectory: "/path/to/offline/storage",
73    disableOfflineStorage: false
74  },
75  
76  // Sampling
77  samplingRatio: 1.0,  // 0-1, percentage of traces
78  
79  // Features
80  enableLiveMetrics: true,
81  enableStandardMetrics: true,
82  enablePerformanceCounters: true,
83  
84  // Instrumentation libraries
85  instrumentationOptions: {
86    azureSdk: { enabled: true },
87    http: { enabled: true },
88    mongoDb: { enabled: true },
89    mySql: { enabled: true },
90    postgreSql: { enabled: true },
91    redis: { enabled: true },
92    bunyan: { enabled: false },
93    winston: { enabled: false }
94  },
95  
96  // Custom resource
97  resource: resourceFromAttributes({ "service.name": "my-service" })
98};
99 
100useAzureMonitor(options);
101```
102 
103## Custom Traces
104 
105```typescript
106import { trace } from "@opentelemetry/api";
107 
108const tracer = trace.getTracer("my-tracer");
109 
110const span = tracer.startSpan("doWork");
111try {
112  span.setAttribute("component", "worker");
113  span.setAttribute("operation.id", "42");
114  span.addEvent("processing started");
115  
116  // Your work here
117  
118} catch (error) {
119  span.recordException(error as Error);
120  span.setStatus({ code: 2, message: (error as Error).message });
121} finally {
122  span.end();
123}
124```
125 
126## Custom Metrics
127 
128```typescript
129import { metrics } from "@opentelemetry/api";
130 
131const meter = metrics.getMeter("my-meter");
132 
133// Counter
134const counter = meter.createCounter("requests_total");
135counter.add(1, { route: "/api/users", method: "GET" });
136 
137// Histogram
138const histogram = meter.createHistogram("request_duration_ms");
139histogram.record(150, { route: "/api/users" });
140 
141// Observable Gauge
142const gauge = meter.createObservableGauge("active_connections");
143gauge.addCallback((result) => {
144  result.observe(getActiveConnections(), { pool: "main" });
145});
146```
147 
148## Manual Exporter Setup
149 
150### Trace Exporter
151 
152```typescript
153import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";
154import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
155 
156const exporter = new AzureMonitorTraceExporter({
157  connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
158});
159 
160const provider = new NodeTracerProvider({
161  spanProcessors: [new BatchSpanProcessor(exporter)]
162});
163 
164provider.register();
165```
166 
167### Metric Exporter
168 
169```typescript
170import { AzureMonitorMetricExporter } from "@azure/monitor-opentelemetry-exporter";
171import { PeriodicExportingMetricReader, MeterProvider } from "@opentelemetry/sdk-metrics";
172import { metrics } from "@opentelemetry/api";
173 
174const exporter = new AzureMonitorMetricExporter({
175  connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
176});
177 
178const meterProvider = new MeterProvider({
179  readers: [new PeriodicExportingMetricReader({ exporter })]
180});
181 
182metrics.setGlobalMeterProvider(meterProvider);
183```
184 
185### Log Exporter
186 
187```typescript
188import { AzureMonitorLogExporter } from "@azure/monitor-opentelemetry-exporter";
189import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
190import { logs } from "@opentelemetry/api-logs";
191 
192const exporter = new AzureMonitorLogExporter({
193  connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
194});
195 
196const loggerProvider = new LoggerProvider();
197loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));
198 
199logs.setGlobalLoggerProvider(loggerProvider);
200```
201 
202## Custom Logs Ingestion
203 
204```typescript
205import { DefaultAzureCredential } from "@azure/identity";
206import { LogsIngestionClient, isAggregateLogsUploadError } from "@azure/monitor-ingestion";
207 
208const endpoint = "https://<dce>.ingest.monitor.azure.com";
209const ruleId = "<data-collection-rule-id>";
210const streamName = "Custom-MyTable_CL";
211 
212const client = new LogsIngestionClient(endpoint, new DefaultAzureCredential());
213 
214const logs = [
215  {
216    Time: new Date().toISOString(),
217    Computer: "Server1",
218    Message: "Application started",
219    Level: "Information"
220  }
221];
222 
223try {
224  await client.upload(ruleId, streamName, logs);
225} catch (error) {
226  if (isAggregateLogsUploadError(error)) {
227    for (const uploadError of error.errors) {
228      console.error("Failed logs:", uploadError.failedLogs);
229    }
230  }
231}
232```
233 
234## Custom Span Processor
235 
236```typescript
237import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
238import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";
239import { useAzureMonitor } from "@azure/monitor-opentelemetry";
240 
241class FilteringSpanProcessor implements SpanProcessor {
242  forceFlush(): Promise<void> { return Promise.resolve(); }
243  shutdown(): Promise<void> { return Promise.resolve(); }
244  onStart(span: Span, context: Context): void {}
245  
246  onEnd(span: ReadableSpan): void {
247    // Add custom attributes
248    span.attributes["CustomDimension"] = "value";
249    
250    // Filter out internal spans
251    if (span.kind === SpanKind.INTERNAL) {
252      span.spanContext().traceFlags = TraceFlags.NONE;
253    }
254  }
255}
256 
257useAzureMonitor({
258  spanProcessors: [new FilteringSpanProcessor()]
259});
260```
261 
262## Sampling
263 
264```typescript
265import { ApplicationInsightsSampler } from "@azure/monitor-opentelemetry-exporter";
266import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
267 
268// Sample 75% of traces
269const sampler = new ApplicationInsightsSampler(0.75);
270 
271const provider = new NodeTracerProvider({ sampler });
272```
273 
274## Shutdown
275 
276```typescript
277import { useAzureMonitor, shutdownAzureMonitor } from "@azure/monitor-opentelemetry";
278 
279useAzureMonitor();
280 
281// On application shutdown
282process.on("SIGTERM", async () => {
283  await shutdownAzureMonitor();
284  process.exit(0);
285});
286```
287 
288## Key Types
289 
290```typescript
291import {
292  useAzureMonitor,
293  shutdownAzureMonitor,
294  AzureMonitorOpenTelemetryOptions,
295  InstrumentationOptions
296} from "@azure/monitor-opentelemetry";
297 
298import {
299  AzureMonitorTraceExporter,
300  AzureMonitorMetricExporter,
301  AzureMonitorLogExporter,
302  ApplicationInsightsSampler,
303  AzureMonitorExporterOptions
304} from "@azure/monitor-opentelemetry-exporter";
305 
306import {
307  LogsIngestionClient,
308  isAggregateLogsUploadError
309} from "@azure/monitor-ingestion";
310```
311 
312## Best Practices
313 
3141. **Call useAzureMonitor() first** - Before importing other modules
3152. **Use ESM loader for ESM projects** - `--import @azure/monitor-opentelemetry/loader`
3163. **Enable offline storage** - For reliable telemetry in disconnected scenarios
3174. **Set sampling ratio** - For high-traffic applications
3185. **Add custom dimensions** - Use span processors for enrichment
3196. **Graceful shutdown** - Call `shutdownAzureMonitor()` to flush telemetry
320