Azure Monitor OpenTelemetry TypeScript (TS)

azure-monitor-opentelemetry-ts
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.80/5
使用8.3K

Azure Monitor OpenTelemetry SDK for TypeScript

为 Node.js 应用程序提供分布式追踪、指标和日志的自动检测。

安装

bash
# 分发版（推荐 - 自动检测）
npm install @azure/monitor-opentelemetry

低级导出器（自定义 OpenTelemetry 设置）

npm install @azure/monitor-opentelemetry-exporter

自定义日志摄取

npm install @azure/monitor-ingestion

环境变量

bash
APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...;IngestionEndpoint=...

快速上手（自动检测）

重要提示： 请在导入其他模块之前调用 useAzureMonitor()。

typescript
import { useAzureMonitor } from "@azure/monitor-opentelemetry";

useAzureMonitor({
  azureMonitorExporterOptions: {
    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
  }
});


// 现在导入您的应用程序
import express from "express";
const app = express();

ESM 支持 (Node.js 18.19+)

bash
node --import @azure/monitor-opentelemetry/loader ./dist/index.js

package.json:

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

完整配置

typescript
import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { resourceFromAttributes } from "@opentelemetry/resources";

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
    storageDirectory: "/path/to/offline/storage",
    disableOfflineStorage: false
  },
  
  // 采样
  samplingRatio: 1.0,  // 0-1，追踪百分比
  
  // 功能
  enableLiveMetrics: true,
  enableStandardMetrics: true,
  enablePerformanceCounters: true,
  
  // 检测库
  instrumentationOptions: {
    azureSdk: { enabled: true },
    http: { enabled: true },
    mongoDb: { enabled: true },
    mySql: { enabled: true },
    postgreSql: { enabled: true },
    redis: { enabled: true },
    bunyan: { enabled: false },
    winston: { enabled: false }
  },
  
  // 自定义资源
  resource: resourceFromAttributes({ "service.name": "my-service" })
};


useAzureMonitor(options);

自定义追踪 (Custom Traces)

typescript
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("my-tracer");


const span = tracer.startSpan("doWork");
try {
  span.setAttribute("component", "worker");
  span.setAttribute("operation.id", "42");
  span.addEvent("processing started");
  
  // 在此处执行您的工作
  
} catch (error) {
  span.recordException(error as Error);
  span.setStatus({ code: 2, message: (error as Error).message });
} finally {
  span.end();
}

自定义指标 (Custom Metrics)

typescript
import { metrics } from "@opentelemetry/api";

const meter = metrics.getMeter("my-meter");


// 计数器 (Counter)
const counter = meter.createCounter("requests_total");
counter.add(1, { route: "/api/users", method: "GET" });


// 直方图 (Histogram)
const histogram = meter.createHistogram("request_duration_ms");
histogram.record(150, { route: "/api/users" });


// 可观察仪表盘 (Observable Gauge)
const gauge = meter.createObservableGauge("active_connections");
gauge.addCallback((result) => {
  result.observe(getActiveConnections(), { pool: "main" });
});

);
});
code
## 手动导出器设置


追踪导出器 (Trace Exporter)
typescript import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter"; import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";

const exporter = new AzureMonitorTraceExporter({
connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
});

const provider = new NodeTracerProvider({
spanProcessors: [new BatchSpanProcessor(exporter)]
});

provider.register();

code
### 指标导出器 (Metric Exporter)
typescript
import { AzureMonitorMetricExporter } from "@azure/monitor-opentelemetry-exporter";
import { PeriodicExportingMetricReader, MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";

const exporter = new AzureMonitorMetricExporter({
connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
});

const meterProvider = new MeterProvider({
readers: [new PeriodicExportingMetricReader({ exporter })]
});

metrics.setGlobalMeterProvider(meterProvider);

code
### 日志导出器 (Log Exporter)
typescript
import { AzureMonitorLogExporter } from "@azure/monitor-opentelemetry-exporter";
import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
import { logs } from "@opentelemetry/api-logs";

const exporter = new AzureMonitorLogExporter({
connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING
});

const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));

logs.setGlobalLoggerProvider(loggerProvider);

code
## 自定义日志摄取
typescript
import { DefaultAzureCredential } from "@azure/identity";
import { LogsIngestionClient, isAggregateLogsUploadError } from "@azure/monitor-ingestion";

const endpoint = "https://<dce>.ingest.monitor.azure.com";
const ruleId = "<data-collection-rule-id>";
const streamName = "Custom-MyTable_CL";

const client = new LogsIngestionClient(endpoint, new DefaultAzureCredential());

const logs = [
{
Time: new Date().toISOString(),
Computer: "Server1",
Message: "Application started",
Level: "Information"
}
];

try {
await client.upload(ruleId, streamName, logs);
} catch (error) {
if (isAggregateLogsUploadError(error)) {
for (const uploadError of error.errors) {
console.error("Failed logs:", uploadError.failedLogs);
}
}
}

code
## 自定义 Span 处理器
typescript
import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";
import { useAzureMonitor } from "@azure/monitor-opentelemetry";

class FilteringSpanProcessor implements SpanProcessor {
forceFlush(): Promise<void> { return Promise.resolve(); }
shutdown(): Promise<void> { return Promise.resolve(); }
onStart(span: Span, context: Context): void {}

onEnd(span: ReadableSpan): void {
// 添加自定义属性
span.attributes["CustomDimension"] = "value";

// 过滤掉内部 Span
if (span.kind === SpanKind.INTERNAL) {
span.spanContext().traceFlags = TraceFlags.NONE;
}
}
}

useAzureMonitor({
spanProcessors: [new FilteringSpanProcessor()]
});

code
## 采样 (Sampling)
typescript
import { ApplicationInsightsSampler } from "@azure/monitor-opentelemetry-exporter";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

// 对 75% 的追踪进行采样
const sampler = new ApplicationInsightsSampler(0.75);

const provider = new NodeTracerProvid

code
er({ sampler });

关闭

typescript
import { useAzureMonitor, shutdownAzureMonitor } from "@azure/monitor-opentelemetry";

useAzureMonitor();


// 在应用程序关闭时
process.on("SIGTERM", async () => {
  await shutdownAzureMonitor();
  process.exit(0);
});

关键类型

typescript
import {
  useAzureMonitor,
  shutdownAzureMonitor,
  AzureMonitorOpenTelemetryOptions,
  InstrumentationOptions
} from "@azure/monitor-opentelemetry";

import {
  AzureMonitorTraceExporter,
  AzureMonitorMetricExporter,
  AzureMonitorLogExporter,
  ApplicationInsightsSampler,
  AzureMonitorExporterOptions
} from "@azure/monitor-opentelemetry-exporter";


import {
  LogsIngestionClient,
  isAggregateLogsUploadError
} from "@azure/monitor-ingestion";

最佳实践

1. 优先调用 useAzureMonitor() - 在导入其他模块之前调用。
2. ESM 项目使用 ESM 加载器 - 使用 --import @azure/monitor-opentelemetry/loader。
3. 启用离线存储 - 确保在断网场景下遥测数据的可靠性。
4. 设置采样率 - 适用于高流量应用程序。
5. 添加自定义维度 - 使用 span processors 进行数据增强。
6. 优雅关闭 - 调用 shutdownAzureMonitor() 以刷新（flush）遥测数据。

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

  • 仅在任务与上述描述的范围明确匹配时使用此技能。
  • 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。