OpenTelemetry Node.js 开发者的说明

先决条件

在线编辑

确保满足以下前提条件：

在 Instana 上已启用“ OpenTelemetry ”功能。
Instana 主机代理已连接到 Instana 后端。
本地安装了以下应用程序：
- Node.js
- TypeScript ，如果您使用的是 TypeScript

检测

在线编辑

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

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

自动仪器化

在线编辑

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

使用适当的“资源检测器”来改进 Instana 中使用的基础设施实体关联。 OpenTelemetry JavaScript 的自动instrumentation必须声明资源检测器，以便拥有足够的资源属性。您必须拥有一个带有资源检测器的外部 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 代理

在线编辑

Instana 代理可以直接接收 OpenTelemetry 的跟踪、指标和日志，格式为 OTLP。然后， Instana 代理将数据转发至 Instana 后端。有关详细信息，请参阅 “将数据发送至 Instana 代理 ”。

您必须在 OTLPMetricExporter 的配置中指定 Instana 代理端点。请将端点与 Instana 键一起设置为 JSON 格式，并将其作为参数传递给 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 后端端点。请将端点与 Instana 密钥及 Instana 主机详细信息设置为 JSON 格式，并将其作为参数传递给 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 ”应用程序列表中

在线编辑

请检查 Instana 主机代理日志，查看是否有任何消息与该 OpenTelemetry 进程相关。
检查NodeJS是否已自动或手动正确加载。
请检查在已插桩的代码中，端点和 Instana 键等配置是否设置正确。

引用

在线编辑