你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

Azure Monitor OpenTelemetry Exporter 客户端库 for JavaScript - 版本 1.0.0-beta.47

NPM 版本

入门指南

此导出程序包假定您的应用程序已使用 OpenTelemetry SDK 进行检测 。 准备好导出 OpenTelemetry 数据后,您可以将此导出器添加到您的应用程序中。

安装软件包

npm install @azure/monitor-opentelemetry-exporter

当前支持的环境

有关详细信息,请参阅我们的 支持策略。

警告: 本 SDK 仅适用于 Node.js 环境。 将 Application Insights JavaScript SDK 用于浏览器环境。

先决条件

分布式跟踪

将导出器添加到现有的 OpenTelemetry Tracer Provider ()NodeTracerProvider / BasicTracerProvider

import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";
import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

// Create an exporter instance
const exporter = new AzureMonitorTraceExporter({
  connectionString: "<connection string>",
});

// Create and configure the Node Tracer provider
const tracerProvider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "basic-service",
  }),
  spanProcessors: [
    new BatchSpanProcessor(exporter, {
      exportTimeoutMillis: 15000,
      maxQueueSize: 1000,
    }),
  ],
});

// Register Tracer Provider as global
tracerProvider.register();

指标

将导出器添加到现有的 OpenTelemetry Meter 提供程序 ()MeterProvider

import { AzureMonitorMetricExporter } from "@azure/monitor-opentelemetry-exporter";
import { PeriodicExportingMetricReader, MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";

// Add the exporter into the MetricReader and register it with the MeterProvider
const exporter = new AzureMonitorMetricExporter({
  connectionString: "<connection string>",
});

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

// Register Meter Provider as global
metrics.setGlobalMeterProvider(meterProvider);

日志

将 Log Exporter 添加到现有的 OpenTelemetry Logger 提供程序 ()LoggerProvider

import { AzureMonitorLogExporter } from "@azure/monitor-opentelemetry-exporter";
import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
import { logs } from "@opentelemetry/api-logs";

// Add the Log exporter into the logRecordProcessor and register it with the LoggerProvider
const exporter = new AzureMonitorLogExporter({
  connectionString: "<connection string>",
});

const logRecordProcessor = new BatchLogRecordProcessor({ exporter });
const loggerProvider = new LoggerProvider({
  processors: [logRecordProcessor],
});

// Register logger Provider as global
logs.setGlobalLoggerProvider(loggerProvider);

可用性结果

注册日志提供者后,发送包含以下可用性属性的OpenTelemetry日志记录。 导出器将记录转换为应用洞察的可用性遥测数据。

import { logs } from "@opentelemetry/api-logs";

const logger = logs.getLogger("availability");
logger.emit({
  body: "Homepage availability test completed.",
  attributes: {
    "microsoft.availability.id": "availability-test-run-123",
    "microsoft.availability.name": "Homepage",
    "microsoft.availability.duration": "00:00:00.250",
    "microsoft.availability.success": true,
    "microsoft.availability.runLocation": "westus2",
    "microsoft.availability.message": "HTTP 200",
  },
});

需要以下属性:

Attribute Description
microsoft.availability.id 本次测试运行的标识符。
microsoft.availability.name 可用性测试的名称。
microsoft.availability.duration 例如 00:00:00.250,测试时长。
microsoft.availability.success 测试是否成功。

microsoft.availability.runLocation 和 microsoft.availability.message 是可选的。 如果省略了消息属性,日志正体将作为可用性消息使用。 可用性结果时间戳来自OpenTelemetry日志记录。

可用性记录使用与其他OpenTelemetry日志相同的相关上下文。 当记录被发送为活动范围(或显式OpenTelemetry上下文)时,区间追踪ID和区间ID填充应用洞察操作ID和父ID。 这些值具有权威性,不能被对数属性覆盖。 可用性测试运行ID与操作ID是分开的。

如果缺少或空的属性,导出器会将记录作为普通消息遥测发送。 例外和自定义事件属性优先于可用性属性。

采样

您可以启用采样来限制您收到的遥测记录数量。 为了在 Application Insights 中启用正确的采样,请使用如下所示的 。ApplicationInsightsSampler

import { ApplicationInsightsSampler } from "@azure/monitor-opentelemetry-exporter";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

// Sampler expects a sample rate of between 0 and 1 inclusive
// A rate of 0.75 means approximately 75 % of your traces will be sent
const aiSampler = new ApplicationInsightsSampler(0.75);
const provider = new NodeTracerProvider({
  sampler: aiSampler,
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "basic-service",
  }),
});

provider.register();

例子

有关一些冠军场景的完整示例,请参阅文件夹 samples/ 。

重要概念

有关 OpenTelemetry 项目的更多信息,请查看 OpenTelemetry 规范。

自定义尺寸尺寸限制

作为自定义维度导出的属性会被其 UTF-8 字节长度单独限制。 这包括来自跨度、跨度事件、日志、指标和资源的自定义维度。 映射到其他遥测字段的属性不受这些限制约束。 非字符串值在截断前会序列化,截断会保留完整的 UTF-8 字符。

Attributes 默认限制 使用 GenAI 消息限制选择加入
gen_ai.input.messages、gen_ai.output.messages 256 KiB 4 MiB
gen_ai.system_instructions、gen_ai.tool.definitions、gen_ai.tool.call.arguments、gen_ai.tool.call.result、gen_ai.evaluation.explanation 256 KiB 256 KiB
所有其他自定义尺寸 8 KiB 8 KiB

有关选择加入的说明,请参见 GenAI 消息大小限制 。

实验性功能

用于 APPLICATIONINSIGHTS_EXPERIMENTAL_FEATURES 在构建导出器之前选择加入命名的实验性功能。 特征名称采用逗号分隔、不区分大小写,并修剪掉周围空白。 未设置或空值则无法实现任何实验特征。 不知名的名字被忽略。 实验性功能可能会在未来的版本中发生变化或被移除。

生成式AI消息大小限制

启用gen_ai_input_output_limit_increase可将自定义尺寸限制gen_ai.input.messagesgen_ai.output.messages从 256 KiB 提高到 4 MiB。 其他所有限制保持不变。

$env:APPLICATIONINSIGHTS_EXPERIMENTAL_FEATURES = "gen_ai_input_output_limit_increase"

每个导出器在施工过程中只读取一次此设置。 对环境变量的更改不会影响现有导出器。

包含 base64 编码图像或音频的多模态消息可以产生大型遥测项。 在使用 BatchSpanProcessor 或 时,考虑减少maxExportBatchSize或增加 exportTimeoutMillisBatchLogRecordProcessor。 您也可以在源端限制捕获的内容。 截断的结构化值可能不再是有效的 JSON。

请求压缩

导出器会自动对通过 HTTPS 发送到 Azure Monitor 摄取端点(包括内部 Statsbeat 和客户 SDK Stats)的遥测数据进行 gzip 压缩。压缩/v2/track/v2.1/track适用于公有云、美国政府云和中国云中认可的 Azure Monitor 域及其上。 自定义摄取端点和域外的反向代理继续接收未压缩的 JSON。

压缩发生在管道策略运行之后。 自定义httpClient接收压缩后的实体与Content-Encoding: gzipContent-Length压缩后的。 现有请求 Content-Encoding 保持不变。 离线遥测数据以包络形式存储,仅在发送或重放时进行压缩。 这不会改变 Live Metrics 、OTLP 导出器或其他 Azure SDK 客户端。

如果 gzip 压缩失败,导出器会记录诊断警告并发送原始未压缩请求。 如果发送请求失败,正常的重试和离线存储行为仍然适用。

故障排除

启用调试日志记录

您可以通过更改提供程序的日志记录级别来启用调试日志记录。

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";

const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();

伐木业

启用 Azure 日志记录还可能有助于发现有关失败的有用信息。 若要查看 HTTP 请求和响应的日志,请将 AZURE_LOG_LEVEL 环境变量设置为 info。 或者,可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

有关如何启用日志的更详细说明,可以查看 @azure/记录器包文档。

后续步骤

此导出器可与 OpenTelemetry JS 一起使用。

插件注册表

要查看是否已为您正在使用的库制作插件,请查看 OpenTelemetry 注册表。

如果您在注册表中找不到您的库,请随时在 上 opentelemetry-js-contrib建议新的插件请求。

贡献

若要参与此库,请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。