azure-monitor-opentelemetry-ts

用途

Azure Monitor OpenTelemetry SDK for TypeScript 用于为 Node.js / TypeScript 应用接入 Azure Monitor，自动采集并上报分布式追踪（traces）、指标（metrics）和日志（logs）。它构建在 OpenTelemetry 标准之上，既可以开箱即用地自动插桩，也支持按 OpenTelemetry 原生方式手工搭建导出管线。

主要能力

自动插桩：通过发行版包 @azure/monitor-opentelemetry 自动采集常见依赖的遥测数据。
可配置插桩库：在 instrumentationOptions 中按需开启或关闭 azureSdk、http、mongoDb、mySql、postgreSql、redis、bunyan、winston 等插桩。
遥测导出器：@azure/monitor-opentelemetry-exporter 提供 Trace、Metric、Log 三类导出器，可用于自定义 OpenTelemetry 设置。
自定义日志摄取：@azure/monitor-ingestion 提供 LogsIngestionClient，可将自定义日志上传到 Azure Monitor。
采样：支持 samplingRatio 配置以及 ApplicationInsightsSampler 采样器。
附加特性开关：enableLiveMetrics、enableStandardMetrics、enablePerformanceCounters。
自定义资源与处理器：可通过 resourceFromAttributes 设置 service.name 等资源属性，并可挂载自定义 SpanProcessor 对 span 做富化或过滤。
离线存储：导出器选项支持 storageDirectory 与 disableOfflineStorage，用于断连场景下可靠上报。
优雅关闭：提供 shutdownAzureMonitor() 以刷新遥测数据。

使用方式

安装

# Distro (recommended - auto-instrumentation)
npm install @azure/monitor-opentelemetry

# Low-level exporters (custom OpenTelemetry setup)
npm install @azure/monitor-opentelemetry-exporter

# Custom logs ingestion
npm install @azure/monitor-ingestion

环境变量

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

快速开始（自动插桩）

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

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

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

// Now import your application
import express from "express";
const app = express();

ESM 支持（Node.js 18.19+）

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

package.json：

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

完整配置示例（含采样、特性开关、插桩库与自定义资源）：

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,
  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);

此外资料还给出了自定义 Traces、自定义 Metrics（Counter / Histogram / Observable Gauge）、手工设置 Trace/Metric/Log 导出器、自定义日志摄取、自定义 Span Processor、采样以及关闭流程的代码示例，可按需参考上文的官方示例片段。

适用场景

需要为 Node.js / TypeScript 服务接入 Azure Monitor 的应用性能监控。
希望基于 OpenTelemetry 标准统一 traces、metrics、logs 采集的项目。
需要自动插桩常见 HTTP 框架、数据库驱动或 Azure SDK 调用的服务。
高流量场景下需要通过采样控制遥测数据量。
需要在断连环境下缓存遥测数据后补传。

限制

资料中注明：仅当任务明确匹配上述范围时才使用该技能。
不应将输出视为环境相关验证、测试或专家评审的替代品。
若缺少所需输入、权限、安全边界或成功标准，应停止并向用户询问澄清。
关于定价、收费、平台支持范围的更多细节，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制