OpenTelemetry Node.js 开发人员须知

Instana 支持 Node.js 的标准 OpenTelemetry JavaScript 自动或手动仪器。更多信息，请参阅 OpenTelemetry 官方文件。

先决条件

确保满足以下前提条件：

  • OpenTelemetry 功能已在 Instana 上启用。

  • Instana 主机代理已连接到 Instana 后台。

  • 本地安装了以下应用程序：

检测

OpenTelemetry 是一个广泛使用的开源项目，用于收集和管理应用程序的遥测数据。 OpenTelemetry 的一个关键方面是仪表化，这包括在应用程序中添加代码，以收集指标、日志和跟踪。

要启用仪器，可以使用以下方法之一。

自动仪表

自动仪器是一种无需修改应用程序源代码即可收集遥测数据的机制。 自动测试是 OpenTelemetry 提供的一项功能，让您无需编写自定义代码即可自动测试应用程序。

使用适当的 "资源探测器 "来改进 Instana 中使用的基础设施实体相关性。 OpenTelemetry JavaScript 自动仪器必须声明资源检测器有足够的资源属性。 您必须有一个具有资源检测器的外部 Instrumentation.js ，以支持足够的资源属性。 例如，在 Kubernetes 或 Red Hat OpenShift 集群等容器环境中链接时，需要 @opentelemetry/resource-detector-container 版本 0.3.4 或更高版本。 以下示例是 OpenTelemetry 官方演示中使用的 Instrumentation.js ：

// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { alibabaCloudEcsDetector } = require('@opentelemetry/resource-detector-alibaba-cloud');
const { awsEc2Detector, awsEksDetector } = require('@opentelemetry/resource-detector-aws');
const { containerDetector } = require('@opentelemetry/resource-detector-container');
const { gcpDetector } = require('@opentelemetry/resource-detector-gcp');
const { envDetector, hostDetector, osDetector, processDetector } = require('@opentelemetry/resources');

const sdk = new opentelemetry.NodeSDK({
    traceExporter: new OTLPTraceExporter(),
    instrumentations: [getNodeAutoInstrumentations()],
    metricReader: new PeriodicExportingMetricReader({
        exporter: new OTLPMetricExporter(),
    }),
    resourceDetectors: [
        containerDetector,
        envDetector,
        hostDetector,
        osDetector,
        processDetector,
        alibabaCloudEcsDetector,
        awsEksDetector,
        awsEc2Detector,
        gcpDetector,
    ],
});

sdk.start();

手动仪表

手动检测包括编写自定义代码来检测应用程序的特定部分。 这需要手动配置应用程序的源代码，以配置 OpenTelemetry SDK 接收、处理和导出遥测数据。 有关更详细的说明，请参阅《 手动仪表》。

向 Instana 发送遥测数据

Instana 通过各种符合开放标准的方法接收 OpenTelemetry 数据，确保与 OpenTelemetry 社区和 Instana 产品无缝集成。 实施工作由双方积极维护，保证了兼容性和可靠性。

向 Instana Agent 发送遥测数据

Instana 代理可直接接收 OpenTelemetry 跟踪、指标和 OTLP 格式的日志。 然后，Instana 代理将数据转发到 Instana 后台。 更多详情，请参阅向 Instana Agent 发送数据。

您必须在 OTLPMetricExporter 的配置中指定 Instana 代理端点。 以 JSON 格式设置端点和 Instana 密钥，并将其作为参数传递给 OTLPMetricExporter ，如下例所示。 更多详情，请参阅使用 Node.js。

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<agent-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>'
    }
  }),
}),

向 Instana 后台发送遥测数据

遥测数据可以以 OTLP 格式从应用程序或系统直接发送到 Instana 后端，这也被称为无代理通信。 更多详情，请参阅将数据发送至 Instana 后台

您必须在 OTLPMetricExporter 的配置中指定 Instana 后端端点。 以 JSON 格式设置端点以及 Instana 密钥和 Instana 主机详细信息，并作为参数传递给 OTLPMetricExporter ，如下例所示。 更多详情，请参阅使用 Node.js。

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<backend-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>',
      'x-instana-host': '<hostname>'
    }
  }),
}),

要启用自动仪表化，请运行以下命令，在运行应用程序时指向 instrumentation.js 文件：

node --require ./instrumentation.js app.js

有关 Node.JS 资源检测器的更多信息，请参见 opentelemetry-js-contrib。

故障诊断

NodeJS OpenTelemetry 应用程序列表中未列出实例

  1. 检查 Instana 主机代理日志，查看是否有任何信息与此 OpenTelemetry 进程相关。
  2. 检查 NodeJS 是否自动或手动正确安装了仪器。
  3. 检查仪器代码中的端点和 Instana 密钥等配置是否设置正确。

引用