›

OpenTelemetry 桥接

与 OpenTelemetry Tracing API 的集成在 v3.34.0 中作为实验性功能添加。与 OpenTelemetry Metrics API 的集成在 v3.45.0 中作为实验性功能添加。

Elastic APM OpenTelemetry 桥接允许您在代码中使用与供应商无关的 OpenTelemetry API (@opentelemetry/api)，并让 Elastic Node.js APM 代理处理这些 API 调用。这允许您使用 Elastic APM 代理进行追踪和指标，而无需在添加手动追踪或自定义指标时锁定到 APM 代理自身的公共 API。

使用 OpenTelemetry Tracing API

编辑

① 首先，您需要将 Elastic APM 代理和 OpenTelemetry API 依赖项添加到您的项目中。所需的最低 OpenTelemetry API 版本为 1.0.0；有关当前支持的最大 API 版本，请参阅OpenTelemetry 兼容性部分。例如

npm install --save elastic-apm-node @opentelemetry/api

② 其次，您需要配置并启动 APM 代理。这可以通过环境变量完全完成（因此无需修改您的应用程序代码）

export ELASTIC_APM_SERVER_URL='<url of your APM server>'
export ELASTIC_APM_SECRET_TOKEN='<secret token for your APM server>'  # or ELASTIC_APM_API_KEY=...
export ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED=true 
export NODE_OPTIONS='-r elastic-apm-node/start.js'  # Tell node to preload and start the APM agent
node my-app.js

未来的版本可能会删除此配置变量，并默认启用跟踪 API 的使用。

或者，您也可以在应用程序代码的顶部配置并启动 APM 代理

require('elastic-apm-node').start({
    serverUrl: '<url of your APM server>',
    secretToken: '<secret token for your APM server>', // or, apiKey: '<your API key>'
    opentelemetryBridgeEnabled: true
});

// Application code ...

有关其他配置选项，请参阅完整的 APM 代理配置参考。

③ 最后，您可以使用 OpenTelemetry API 对代码中的任何手动追踪。例如，以下脚本使用 Tracer#startActiveSpan() 来跟踪发出的 HTTPS 请求

const https = require('https')
const otel = require('@opentelemetry/api')
const tracer = otel.trace.getTracer('trace-https-request')

tracer.startActiveSpan('makeRequest', span => {
  https.get('https://httpstat.us/200', (response) => {
    console.log('STATUS:', response.statusCode)
    const body = []
    response.on('data', (chunk) => body.push(chunk))
    response.on('end', () => {
      console.log('BODY:', body.toString())
      span.end()
    })
  })
})

APM 代理源代码存储库包含一些使用 OpenTelemetry 追踪桥接的示例。

使用 OpenTelemetry Metrics API

编辑

① 如上所述，安装所需的依赖项。所需的最低 OpenTelemetry API 版本为 1.3.0（添加指标时的版本）；有关当前支持的最大 API 版本，请参阅OpenTelemetry 兼容性部分。例如

npm install --save elastic-apm-node @opentelemetry/api

② 配置并启动 APM 代理。这可以通过环境变量完全完成（如下所示）或在代码中完成。（有关其他配置选项，请参阅启动代理和完整的 APM 代理配置参考。）

export ELASTIC_APM_SERVER_URL='<url of your APM server>'
export ELASTIC_APM_SECRET_TOKEN='<secret token for your APM server>'  # or ELASTIC_APM_API_KEY=...
export NODE_OPTIONS='-r elastic-apm-node/start.js'  # Tell node to preload and start the APM agent
node my-app.js

③ 最后，您可以使用 OpenTelemetry Metrics API 来创建指标，APM 代理会将这些指标定期发送到您的 Elastic APM 部署，您可以在 Kibana 中可视化它们。

// otel-metrics-hello-world.js 
const { createServer } = require('http')
const otel = require('@opentelemetry/api')

const meter = otel.metrics.getMeter('my-meter')
const numReqs = meter.createCounter('num_requests', { description: 'number of HTTP requests' })

const server = createServer((req, res) => {
  numReqs.add(1)
  req.resume()
  req.on('end', () => {
    res.end('pong\n')
  })
})
server.listen(3000, () => {
  console.log('listening at http://127.0.0.1:3000/')
})

完整示例在这里。

使用 OpenTelemetry Metrics SDK

编辑

当直接使用 OpenTelemetry Metrics SDK 时，Elastic APM 代理还支持将指标导出到 APM 服务器。您可能希望使用 OpenTelemetry Metrics SDK 来使用 View 来配置直方图桶大小、设置 Prometheus 导出器或其他原因。例如

// use-otel-metrics-sdk.js 
const otel = require('@opentelemetry/api')
const { MeterProvider } = require('@opentelemetry/sdk-metrics')
const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus')

const exporter = new PrometheusExporter({ host: '127.0.0.1', port: 3001 })
const meterProvider = new MeterProvider()
meterProvider.addMetricReader(exporter)
otel.metrics.setGlobalMeterProvider(meterProvider)

const meter = otel.metrics.getMeter('my-meter')
const latency = meter.createHistogram('latency', { description: 'Response latency (s)' })
// ...

完整示例在这里。

OpenTelemetry 指标配置

编辑

可以使用一些配置选项来控制 OpenTelemetry 指标支持。

可以通过disableMetrics 配置选项过滤掉特定的指标名称。
可以通过 disableInstrumentations: '@opentelemetry/api' 配置选项禁用与 OpenTelemetry Metrics API 的集成。
可以通过 disableInstrumentations: '@opentelemetry/sdk-metrics' 配置选项禁用与 OpenTelemetry Metrics SDK 的集成。
可以通过 metricsInterval: '0s' 配置选项禁用 APM 代理中的所有指标支持。
默认直方图桶边界与 OpenTelemetry 默认值不同，以提供更好的分辨率。APM 代理使用的边界可以使用 customMetricsHistogramBoundaries 配置选项进行配置。

桥接架构

编辑

OpenTelemetry 追踪桥接的工作方式与 OpenTelemetry Node.js Trace SDK 类似。它向 OpenTelemetry API 注册 Tracer 和 ContextManager 提供程序。用户代码中后续的 @opentelemetry/api 调用将使用这些提供程序。APM 代理将 OpenTelemetry 转换为 Elastic APM 语义，并将追踪数据发送到您的 APM 服务器，以便在 Elastic Observability 的 APM 应用程序中获得全面支持。

一些语义转换的示例：服务的第一个入口 span（例如，传入的 HTTP 请求）将被转换为 Elasic APM Transaction，后续的 span 将被映射到 Elastic APM `Span`。OpenTelemetry Span 属性将被转换为 Elastic APM 数据模型中的相应字段。

从用户的角度来看，唯一的区别在于追踪的设置。不是设置 OpenTelemetry JS SDK，而是按照上述方式设置 APM 代理。

OpenTelemetry 指标支持略有不同。如果您的代码仅使用 Metrics API，则 APM 代理会提供完整的 MeterProvider，以便收集指标并将其发送到 APM 服务器。如果您的代码使用 Metrics SDK，则 APM 代理会将 MetricReader 添加到您的 MeterProvider，以便将指标发送到 APM 服务器。这允许您将 APM 代理用作使用指标的简单设置，或与您现有的 OpenTelemetry 指标配置结合使用。

注意事项

编辑

并非所有 OpenTelemetry API 的功能都受支持。本节介绍任何限制和差异。

追踪

编辑

Span 链接属性。支持在启动 span 时添加链接，但任何添加的 span 链接属性都将被静默删除。
目前不支持 Span 事件 (Span#addEvent())。事件将被静默删除。
不支持在进程内部或外部传播 baggage。Baggage 项将被静默删除。

指标

编辑

不支持指标 exemplars。
不支持摘要指标。
尚不支持指数直方图。
OpenTelemetry 直方图数据中的 sum、count、min 和 max 将被丢弃。
默认直方图桶边界与 OpenTelemetry 默认值不同。它们提供了更好的分辨率。可以使用 customMetricsHistogramBoundaries 配置选项进行配置。
指标标签名称在 APM 服务器中被去点 (s/\./_/g)，以避免 Elasticsearch 中可能出现的映射冲突。
使用的默认聚合时效性与 OpenTelemetry 默认值不同，它更倾向于 delta 时效性（更适合在 Kibana 中可视化）而不是累积时效性。

指标支持需要 APM 服务器 >=7.11 — 对于较早版本的 APM 服务器，标签名称包含 .、* 或 " 的指标将会被丢弃。

日志

编辑

目前不支持 OpenTelemetry 日志 API — 仅支持跟踪和指标 API。

« 日志 OpenTracing 桥接 »