Node.js コレクターの設定

コレクターは IP 127.0.0.1 を使用して、ホストのデフォルト・ゲートウェイを介したフォールバックとして Instana エージェントと通信しようとします。 これらの IP のいずれでもエージェントを使用できない場合は、agentHost オプションを使用してカスタム IP を使用することができます。

require('@instana/collector')({
  agentHost: '::1' // use IPv6 to contact via localhost
});
 

あるいは、環境変数を利用します。

require('@instana/collector')({
  agentHost: process.env.HOST_IP
});
 

構成されていない場合、Instana コレクターは INSTANA_AGENT_HOST という名前の環境変数を検索し、この環境変数で定義されている内容を使用してエージェントと通信します。 この環境変数がない場合は、まず localhost でエージェントとの接続を試行し、次にデフォルト・ゲートウェイで接続を試行します。

コレクターはポート 42699 を介して Instana エージェントとの通信を試行します。 ポートが変更されている場合は、agentPortオプションを使用してポートを変更できます。

require('@instana/collector')({
  agentPort: 42699
});
 

構成されていない場合、Instana コレクターは INSTANA_AGENT_PORT という名前の環境変数を検索し、この環境変数で定義されている内容を使用してエージェントと通信します。 この環境変数がない場合は、デフォルト・ポート 42699 にフォールバックします。

Node.js アプリケーションと Instana エージェントが Kubernetes クラスタ上で実行されている場合は、この構成に必要な設定に関する情報について、 Kubernetes のネットワークアクセスに関するドキュメントを確認してください。

Instana エージェントが導入されている非サーバーレス環境では、 Node.js Tracerは、実行中の Node.js のバージョンがサポート終了（EOL）に達したことを検知すると、問題イベントをトリガーします。

これらのEOLイベントを抑制するには、次の環境変数を使用して無効にすることができます：

INSTANA_TRACING_DISABLE_EOL_EVENTS=true
 

Node.js のサポート終了（EOL）バージョンの完全な一覧については、 Node.js の公式リリースページをご覧ください。

デフォルトでは、 Instana Node.js Tracer は、アクティブなエントリスパンを持つ終了スパンのみをキャプチャします。 この機能を有効にすると、トレーサーがスタンドアロンの出口スパンをトレースできるようになります。

この機能を有効にするには、以下のいずれかのオプションを使用する：

• 環境 INSTANA_ALLOW_ROOT_EXIT_SPAN 変数を設定してください。

• トレーサー初期化機能で機能を設定する：

  require('@instana/collector')({
  tracing: {
    allowRootExitSpan: true
  }
  });
   

が または 1 に設定されている INSTANA_ALLOW_ROOT_EXIT_SPANtrue 場合、あるいは allowRootExitSpan が に設定されている true場合、アクティブなエントリスパンが存在しなくても、トレーサーはエクシッツパンをキャプチャします。

この機能は、 Instana の自動インスツルメンテーションではサポートされていない仕組みによってタスクがトリガーされる、以下のようなシナリオで役立ちます：

• サポートされていないメッセージング・ライブラリからの着信メッセージ
• サポートされていないプロトコル（例：生の Transmission Control Protocol （ TCP ）や WebSocket ）を介して行われるリクエスト
• setTimeout、'setInterval、またはサポートされていないNode.jsスケジューリング・ライブラリなどのメカニズムを使用して、アプリケーションによって内部的に開始されるスケジュールされたジョブ

Node.js Tracer 4.9.0 以降では、特定のトレースや呼び出しを除外することで、不要なデータの取り込みを削減できます。 このフィルタリング機能により、トレースの収集が最適化されます。 トレースを無効にするには、 Node.js のTracer設定で以下のパラメータを定義してください：

• 技術：該当する技術を指定してください。例：、 Kafka Redis、 DynamoDB、、または HTTP。
• 方法：除外する方法を特定する。 たとえば、以下の技術については、これらのメソッドを除外してください：
  • Kafka: send, consume
  • Redis: get, type
  • DynamoDB: query, scan
  • HTTP: get, post
• エンドポイント（該当する場合）：特定のエンドポイントに基づいてフィルタリングをさらに絞り込みます。 たとえば、以下のテクノロジーのエンドポイントは次のように定義されています：
  • Kafka: エンドポイントはトピック名です。
  • HTTP: エンドポイントは URL というパスです。
• 接続（オプション）：特定の接続のトレースを除外します。 たとえば、以下の技術の接続は次のように定義されています：
  • Redis: 接続は接続文字列です。
  • HTTP: 接続情報にはホスト名とポート番号が含まれます。

トレースを無効にするには、完全に無効にするか、特定の計測対象や、データベース、メッセージング、ロギングなどのグループ全体を選択的に除外することができます。 この柔軟性により、アプリケーションの要件に合わせてトレースを微調整することができます。

トレースを無効にする設定を適用するには、以下のいずれかの方法を使用してください：

• 環境変数
• コード内設定
• エージェントの設定 ( YAML )

自動トレースもデフォルトで有効になっています。 自動トレースのみを無効にする (SDK またはopenTracing による手動トレースは有効にしておく) には、次のオプションを初期化関数に渡します。

require('@instana/collector')({
  tracing: {
    automaticTracingEnabled: false
  }
});
 

最後に、環境変数 INSTANA_DISABLE_AUTO_INSTR=true を設定することでも自動トレースを無効にすることができます。

自動トレースが無効化されていても、SDK または OpenTracing API を使用してスパンを手動で作成することはできます。

Opentelemetry の統合は、デフォルトで有効になっています。 統合を無効にするには、以下のオプションを初期化関数に渡します。

require('@instana/collector')({
  tracing: {
    useOpentelemetry: false
  }
});
 

さらに、 INSTANA_DISABLE_USE_OPENTELEMETRY 変数を trueに設定することで、 OpenTelemetry 統合を無効にすることができます。 詳細については、 「 Instana 環境変数」 を参照してください。

Instana Node.js コレクターがワーカースレッドを追跡しないようにするには、次の環境変数を設定してください：

INSTANA_DISABLE_WORKER_THREADS=true

この設定では、すべてのワーカースレッドのトレースが無効になりますが、メインプロセスは引き続き自動的にトレースされます。 ワーカースレッドが、トレースの対象から除外したい内部タスクやバックグラウンドタスクを実行する場合に、この設定を使用してください。

デフォルトでは、コレクターはキャプチャされた各出口スパンについて、直近の10箇所の呼び出し箇所をキャプチャします。 この値は、必要に応じて増減させることができます。

スタックトレースの取得については、次の2つの点を設定できます：

• スタックトレースの長さ ：キャプチャする呼び出し箇所の数。
  • 指定可能な値：0～500
  • デフォルト値: 10
• スタックトレースモード ：スタックトレースの取得方法。
  • 対応する値：
    • all: すべての終了スパンについてスタックトレースを収集します（デフォルト）。

      # Captures stack trace for all spans.
      INSTANA_STACK_TRACE=all

    • error: エラーが発生したスパンについてのみスタックトレースを収集します。

      # Captures stack trace only for erroneous spans.
      INSTANA_STACK_TRACE=error

    • none: スタックトレースは収集されません。

      # Disable collection of stack trace.
      INSTANA_STACK_TRACE=none

スタックトレースの取得は、以下のいずれかのオプションを使用して設定できます：

• 環境変数
• コード内設定
• エージェントの構成

Instana コレクターは、プロジェクト内のプライマリ package.json ファイルを検索し、アプリケーション名などの重要な情報を抽出しようとします。 package.json ファイルのカスタム・パスを定義する必要がある場合、またはコレクターがファイルを見つけることができない場合は、 packageJsonPathという名前の構成オプションを使用できます。

require('@instana/collector')({
  packageJsonPath: 'absolute/path/to/package.json'
});
 

INSTANA_PACKAGE_JSON_PATH 環境変数を設定することで、 package.json ファイルのパスを構成することもできます。

サービスは、Instana の中心となる概念です。 呼び出し、スパン、およびトレースはサービスに密接に関連しています。 デフォルトの場合、Node.js コレクターはメインの package.json ファイルの name 属性と version 属性を使用します。 サービス名をカスタマイズするには、serviceName プロパティーを構成します。

require('@instana/collector')({
  serviceName: 'shop'
});
 

環境変数 INSTANA_SERVICE_NAME を設定することでも、カスタム・サービス名を構成できます。 カスタムサービスの設定に関する詳細については、 「サービス名のグローバル設定」 を参照してください。

コレクターバージョン4.xから、Kafkaトレース相関ヘッダーは常に'stringフォーマットで送信されるようになり、'binaryフォーマットのサポートはなくなりました。 詳細については、Kafkaヘッダーの移行を参照してください。

環境変数「INSTANA_KAFKA_HEADER_FORMAT」とコード内設定オプション「tracing: { kafka: { headerFormat: .... }}}」を参照する設定をすべて削除する。

デフォルトのログ・レベルを変更するには、以下を使用して構成できます。

require('@instana/collector')({
  level: 'debug'
});
 

環境変数 INSTANA_LOG_LEVEL を debug、info、warn または error のいずれかに設定することでも、ログ・レベルを構成できます。 最後に INSTANA_DEBUG を空ではない文字列に設定すると、ログ・レベルが debug に設定されます。

デフォルトのログ・レベルは infoであることに注意してください。 予期しない Instana 関連のデバッグログ（や "name":"@instana/collector""level":20 を含むログ行）が表示された場合は、設定でログレベルが「debug」に設定されていないか、または や INSTANA_DEBUG が設定されていない INSTANA_LOG_LEVEL=debug かを確認してください。 独自のロガー (以下を参照) を提供する場合は、必要に応じてそのロガーのログ・レベルを設定する必要があります。

「ロガーの設定」 を参照してください。