OpenTelemetry Node.js 開発者向けの注意事項

オンラインで編集する

Instana Node.js 向けの標準的な自動または手動のインストルメンテーション（ OpenTelemetry、 JavaScript ）に対応しています。詳細については、 OpenTelemetry の公式ドキュメントを参照してください。

前提条件

オンラインで編集する

以下の前提条件を満たしていることを確認してください：

「 OpenTelemetry 」機能は、 Instana で有効になっています。
Instana のホストエージェントは、 Instana のバックエンドに接続されています。
以下のアプリケーションはローカルにインストールされる：
- Node.js
- TypeScript （ TypeScript をご利用の場合）

インスツルメンテーション

オンラインで編集する

OpenTelemetry は、アプリケーションから遠隔測定データを収集し管理するための、広く使われているオープンソースプロジェクトです。 OpenTelemetry の重要な側面の 1 つはインスツルメンテーションで、メトリクス、ログ、トレースを収集するためにアプリケーションにコードを追加します。

インスツルメンテーションを有効にするには、以下のいずれかの方法を使用する。

自動計測

オンラインで編集する

自動計測とは、アプリケーションのソースコードを変更することなく、テレメトリデータを収集するための仕組みです。自動計測は、OpenTelemetry が提供する機能で、カスタムコードを書くことなく、アプリケーションを自動的に計測することができます。

適切な「リソース検出器」を使用して、 Instana で使用されるインフラストラクチャ・エンティティの相関関係を改善する。 OpenTelemetry JavaScript の自動インスツルメンテーションでは、十分なリソース属性を確保するために、リソース検出器を宣言する必要があります。十分なリソース属性をサポートするためのリソース検出器を備えた、外部の Instrumentation.js が必要です。たとえば、 Kubernetes や Red Hat OpenShift@opentelemetry/resource-detector-container クラスタなどのコンテナ環境内でリンクを行うには、バージョン 0.3.4 以降が必要です。次の例は、 OpenTelemetryInstrumentation.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 エージェントは、 OTLP 形式の OpenTelemetry トレース、メトリクス、およびログを直接受信できます。その後、 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 キーなどの設定が正しく行われているか確認してください。

参照

オンラインで編集する