OpenTelemetry Instana および Node.js アプリケーションの監視

制約事項

オンラインで編集する

注：同じ Node.js アプリケーション内で、 OpenTelemetry SDKと Instana Node.js Tracerを同時に使用することは避けてください。両方を併用すると、次のような問題が生じる可能性があります：

Instana での着信履歴
重複したテレメトリデータ
計装の故障

Node.js OpenTelemetry SDK による監視オプション

オンラインで編集する

OpenTelemetry SDK を使用する場合、以下のトレースオプションから選択できます：

エージェントベースのトレース： OpenTelemetry SDK を使用して、トレースとメトリクスが Instana のエージェントエンドポイントに送信されます
サーバーレスのトレース：
- OpenTelemetry SDK を使用した OTLP 形式のサーバーレストレーシング : トレースとメトリクスは、 OpenTelemetry SDK を使用して Instana OTLP エンドポイントに送信されます ( 推奨 )
- OpenTelemetry SDK を使用した Instana 形式のサーバーレストレーシング : OpenTelemetry SDK を使用すると、トレースとメトリクスが Instana 形式で Instana に送信されます。

注：ホスト、プロセス、およびサービス間のインフラストラクチャの相関関係を特定するには、少なくとも1つのメトリクスを送信する必要があります。

OpenTelemetry SDK を使用したエージェントベースのトレース

オンラインで編集する

OpenTelemetry SDKを使用することで、 Node.js アプリケーションのエージェントベースのトレーシングを有効にできます。

要件

オンラインで編集する

パッケージのインストール

オンラインで編集する

パッケージをインストールするには、次のコマンドを実行してください：

npm i @opentelemetry/exporter-metrics-otlp-http @opentelemetry/exporter-trace-otlp-http @opentelemetry/propagator-instana @opentelemetry/resource-detector-instana @opentelemetry/resources @opentelemetry/sdk-metrics --save

パッケージの有効化

オンラインで編集する

実際に動作する完全な例については、「エージェントベースの HTTP の例」を参照してください。

...
          const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
          const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
          const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
          const { instanaAgentDetector } = require('@opentelemetry/resource-detector-instana');
          const { processDetector, envDetector } = require('@opentelemetry/resources');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          const instanaAgentHost = 'http://127.0.0.1:4318';

          const instanaReader = new PeriodicExportingMetricReader({
            exportIntervalMillis: 1000 * 10,
            exporter: new OTLPMetricExporter({
              url: `${otlpEndpoint}/v1/metrics`
            })
          });

          const sdk = new opentelemetry.NodeSDK({
            resourceDetectors: [envDetector, processDetector, instanaAgentDetector],
            traceExporter: new OTLPTraceExporter({
              url: `${otlpEndpoint}/v1/traces`
            }),
            propagator: new InstanaPropagator(),
            metricReader: instanaReader,
            instrumentations: ...
          });

OpenTelemetry のSDKを使用した、 OTLP 形式のサーバーレストレース

オンラインで編集する

OTLP 形式の OpenTelemetry SDKを使用して、 Node.js アプリケーションのサーバーレストレースを設定し、トレースやメトリクスを Instana に送信することができます。

要件

オンラインで編集する

OpenTelemetry の設定 SDK for Node.js
「 OTLP 」のアクセプターであるサーバーレスエンドポイントを選択し、エンドポイントを URL に設定 INSTANA_ENDPOINT_URL します。
エージェントキーを取得し、それをエージェントキーに設定 INSTANA_AGENT_KEY します。

パッケージのインストール

オンラインで編集する

以下のパッケージをインストールするには、次のコマンドを実行してください：

npm i @opentelemetry/exporter-metrics-otlp-grpc @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-instana @opentelemetry/sdk-metrics --save

パッケージの有効化

オンラインで編集する

実際に動作する完全な例については、「Serverless OpenTelemetry OTLP 形式の例」を参照してください。

...
          const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
          const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
          const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          const otlpEndpoint = process.env.INSTANA_ENDPOINT_URL;
          const metadata = new grpc.Metadata();
          metadata.set('x-instana-key', process.env.INSTANA_AGENT_KEY);

          const instanaReader = new PeriodicExportingMetricReader({
            exportIntervalMillis: 1000 * 10,
            exporter: new OTLPMetricExporter({
              url: otlpEndpoint,
              metadata
            })
          });

          const sdk = new opentelemetry.NodeSDK({
            traceExporter: new OTLPTraceExporter({
              url: otlpEndpoint,
              metadata
            }),
            propagator: new InstanaPropagator(),
            metricReader: instanaReader,
            instrumentations: [...]
          });

          ...

OpenTelemetry のSDKを使用した、 Instana 形式のサーバーレストレース

オンラインで編集する

OpenTelemetry によって監視されているアプリケーションが実行されると、 Instana エクスポーターは、 OpenTelemetry のスパンを Instana のスパンに変換し、それらをバックエンドエンドポイントに送信します。

OpenTelemetry のトレースは、 Instana のUI上で、通常の Instana のトレーススパンと同様に表示されます。

要件

オンラインで編集する

OpenTelemetry をインストールしてください SDK for Node.js
OTLP のアクセプタエンドポイントを選択し、エンドポイントを URL に設定 INSTANA_ENDPOINT_URL します。
エージェントキーを取得し、それをエージェントキーに設定 INSTANA_AGENT_KEY します。

インストール

オンラインで編集する

次のコマンドを実行して、以下のパッケージをインストールしてください：

npm i @instana/opentelemetry-exporter@ @opentelemetry/propagator-instana --save

起動

オンラインで編集する

実際に動作する完全な例については、「Serverless OpenTelemetry Instana 形式の例」を参照してください。

...
          const { InstanaExporter } = require('@instana/opentelemetry-exporter');
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

          /*
           * If you have not provided the agent key and the serverless endpoint URL via environment variables:
           * const instanaTraceExporter = new InstanaExporter({ agentKey: 'agent_key', endpointUrl: 'endpoint_url' });
           */
          const instanaTraceExporter = new InstanaExporter();

          const sdk = new opentelemetry.NodeSDK({
            ...
            traceExporter: instanaTraceExporter,
            propagator: new InstanaPropagator(),
            instrumentations: [...]
          });

OpenTelemetry プラグインの概要

オンラインで編集する

Node.js 用の Instana OpenTelemetry プラグインを使用して、トレースの伝播、サンプリング、およびリソース検出を管理し、テレメトリデータの相関関係とコンテキストを向上させましょう。

OpenTelemetry 増殖者

オンラインで編集する

OpenTelemetry のコンテキストプロパゲーターパッケージ @opentelemetry/propagator-instana は、 Instana の独自トレース相関ヘッダーを OpenTelemetry のトレースコンテキストに変換し、その逆の変換も行います。

OpenTelemetry のコンテキストプロパゲータに関する一般的な情報については、 OpenTelemetry のプロパゲータを参照してください。

OpenTelemetry プロパゲーターのインストール

オンラインで編集する

OpenTelemetry プロパゲーターをインストールするには、次のコマンドを実行してください：

npm install --save @opentelemetry/propagator-instana@

OpenTelemetry プロパゲーターの有効化

オンラインで編集する

OpenTelemetry プロパゲーターを有効にするには、次のコマンドを実行してください：

...
          const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
          // ...

          new opentelemetry.NodeSDK({
            ...
            propagator: new InstanaPropagator(),
            ...
          });

OpenTelemetry サンプラー

オンラインで編集する

falseOpenTelemetry のサンプラーパッケージ @instana/opentelemetry-sampler は、デフォルトの OpenTelemetry のサンプリング動作を上書きし、トレースコンテキスト内のフラグの sampled 値がである場合を除き、すべてのリクエストがサンプリングされるようにします。

OpenTelemetry サンプラーのインストール

オンラインで編集する

OpenTelemetry サンプラーをインストールするには、次のコマンドを実行してください：

npm install --save @instana/opentelemetry-sampler@

OpenTelemetry サンプラーの有効化

オンラインで編集する

@opentelemetry/propagator-instanaこのサンプラーは、パッケージと組み合わせて使用する必要があります。

const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
          const { InstanaAlwaysOnSampler } = require('@instana/opentelemetry-sampler');

          const sdk = new opentelemetry.NodeSDK({
            ...
            propagator: new InstanaPropagator(),
            sampler: new InstanaAlwaysOnSampler()
            ...
          });

          ...

OpenTelemetry リソース検出器

オンラインで編集する

注：Instana （ OpenTelemetry ）のリソース検出機能を利用するには、必ず同じホスト上に Instana エージェントが展開され、実行されている必要があります。

OpenTelemetry のリソース検出器パッケージ @opentelemetry/resource-detector-instana は、 OpenTelemetry のトレース情報に追加のリソース属性を付加します。

OpenTelemetry リソース検出器のインストール

オンラインで編集する

OpenTelemetry リソース検出ツールをインストールするには、次のコマンドを実行してください：

npm install --save @opentelemetry/resource-detector-instana

OpenTelemetry リソース検出機能の有効化

オンラインで編集する

import {
            Resource,
            processDetector,
            envDetector,
          } from "@opentelemetry/resources";
          import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
          import { NodeSDK } from "@opentelemetry/sdk-node";
          import { instanaAgentDetector } from "@opentelemetry/resource-detector-instana";

          const globalResource = new Resource({
             [SemanticResourceAttributes.SERVICE_NAME]: "TestService",
          });

          const sdk = new NodeSDK({
             resourceDetectors: [envDetector, processDetector, instanaAgentDetector]
             resource: globalResource,
          });

          ...

さらに、以下の環境変数を設定することもできます：

INSTANA_RETRY_TIMEOUT_MS: リソース検出機能は、 Instana エージェントへの接続を試みる際、3回の再試行を行います。この値は、再試行間のタイムアウト時間です。 (デフォルト: 1000)
INSTANA_AGENT_TIMEOUT_MS: Instana エージェントへの接続時のクライアントタイムアウト。 (デフォルト: 3000)