OpenTelemetry 桥接

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

或者，您也可以在应用程序代码的顶部配置并启动 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 Metrics 配置编辑

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

桥接架构编辑

OpenTelemetry Tracing 桥接的工作原理类似于 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 支持略有不同。如果您的代码仅使用 Metrics API，则 APM 代理提供完整的 MeterProvider，以便累积指标并将其发送到 APM 服务器。如果您的代码使用 Metrics SDK，则 APM 代理会将 MetricReader 添加到您的 MeterProvider，以将指标发送到 APM 服务器。这允许您将 APM 代理用作使用指标的简单设置，或与您现有的 OpenTelemetry Metrics 配置结合使用。

注意事项编辑

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

跟踪编辑

指标编辑

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

日志编辑

OpenTelemetry Logs API 当前不受支持，仅支持 Tracing 和 Metrics API。