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 バージョンが寿命 (EOL) に達したことを検出すると、 Node.js Tracer が発行イベントをトリガーします。

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

INSTANA_TRACING_DISABLE_EOL_EVENTS=true
 

EOL Node.js バージョンの完全なリストについては、公式 Node.js リリースページを参照のこと。

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

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

• 環境変数 INSTANA_ALLOW_ROOT_EXIT_SPAN 環境変数を設定する。

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

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

もし INSTANA_ALLOW_ROOT_EXIT_SPAN が 1 または true に設定されている場合、または 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:connectionは接続文字列。
  • 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 件の呼び出しサイトをキャプチャーします。 この値は必要に応じて増減できます (HTTP エントリー・スパンのスタック・トレースは収集されないことに注意してください。このトレースは Node.js コア・コードのみが表示されます)。 スタック・トレースのキャプチャーを無効にするには、値 0 を使用します。

require('@instana/collector')({
  tracing: {
    stackTraceLength: 10
  }
});
 

また、環境変数 INSTANA_STACK_TRACE_LENGTH を設定することによっても、スタック・トレースの長さを構成できます。

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であることに注意してください。 予期しないインスタナ関連のデバッグログ( "name":"@instana/collector" と "level":20 を含むログ行)が表示される場合は、設定でログレベルをデバッグに設定しているか、 INSTANA_LOG_LEVEL=debug または INSTANA_DEBUG が設定されているかを確認してください。 あなた自身のロガーを提供する場合（以下を参照）、あなたはそのロガーのログレベルを望むように設定する責任があります。

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