Splunk Observability Cloud の Node.js インストルメンテーションのトラブルシューティング

Node.jsのOpenTelemetry問題のトラブルシューティングの手順

以下の手順は、Node.js インストルメンテーションの問題のトラブルシューティングに役立ちます：

1. 診断ロギングの有効化

2. デバッグメトリクスを有効にする

診断ロギングの有効化

診断ログは、インストルメンテーションの問題のトラブルシューティングに役立ちます。

インストルメンテーションログをコンソールに出力するには、アプリケーションが実行されているのと同じスコープで、 OTEL_LOG_LEVEL 環境変数を debug に設定します。たとえば、OTEL_LOG_LEVEL=<level> node start.js のようになります。.env ファイルには追加しないでください。これは後で読み込まれるためです。

また、logLevel 引数を設定することで、プログラムでデバッグロギングを有効にすることもできます。例：

start({
   logLevel: 'debug',
   metrics: {
      // configuration passed to metrics signal
   },
   profiling: {
      // configuration passed to profiling signal
   },
   tracing: {
      // configuration passed to tracing signal
   },
});

コードでデバッグロギングを無効にするには、次の例のように setLogger() を呼び出します：

const { diag } = require('@opentelemetry/api');
diag.setLogger();

デバッグメトリクスを有効にする

アプリケーションが実行されているのと同じスコープで、SPLUNK_DEBUG_METRICS_ENABLED 環境変数を true に設定することで、内部デバッグメトリクスを有効にできます。たとえば、SPLUNK_DEBUG_METRICS_ENABLED=true node start.js のようになります。.env ファイルには追加しないでください。これは後で読み込まれるためです。

詳細については、「デバッグメトリクス」を参照してください。

トレース・エクスポーターの問題

デフォルトでは、Splunk Distribution of OpenTelemetry JS は OTLP エクスポータを使用します。トレースのエクスポートに影響する問題があると、デバッグログにエラーが表示されます。

OTLP がスパンをエクスポートできない

ログの以下のエラーは、インストルメンテーションがトレースデータを OpenTelemetry Collector に送信できないことを意味します。

@opentelemetry/instrumentation-http http.ClientRequest return request
{"stack":"Error: connect ECONNREFUSED 127.0.0.1:55681\n    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1148:16)\n    at TCPConnectWrap.callbackTrampoline (internal/async_hooks.js:131:17)","message":"connect ECONNREFUSED 127.0.0.1:55681","errno":"-111","code":"ECONNREFUSED","syscall":"connect","address":"127.0.0.1","port":"55681","name":"Error"}

OTLPエクスポーターとOTel Collector 間の接続不足のトラブルシューティングを行うには、以下のことを確認してください：

1. OTEL_EXPORTER_OTLP_ENDPOINT が正しい OpenTelemetry Collector インスタンスホストを指していることを確認します。

2. コレクタインスタンスが設定済みで、稼動していることを確認します。「Splunk OpenTelemetry Collector のトラブルシューティング」を参照してください。

3. OTLP レシーバーが OTel Collector でアクティブになり、トレースパイプラインに接続されていることを確認します。

4. OTel Collector がアドレス http://<host>:4317 を指していることを確認します。URL が正しいことを確認します。

スパン送信時の401エラー

トレースを Splunk Observability Cloud に直接送信して 401 エラーコードを受け取った場合、SPLUNK_ACCESS_TOKEN で指定した認証トークンが無効です。考えられる原因は次のとおりです。

• 値はnullです。

• 値が整形式トークンではありません。

• このトークンは、authScope が ingest に設定されているアクセストークンではありません。

Splunk プラットフォームインスタンスに直接データを送信する場合は、有効な Splunk アクセストークンを使用していることを確認してください。「Splunk Observability Cloud を使用したユーザー API アクセストークンの取得と管理」を参照してください。

Webpackの互換性の問題

Splunk Distribution of OpenTelemetry JS では、Webpack を使ってバンドルされたモジュールをインストルメンテーションすることができません。OpenTelemetry はライブラリの require 呼び出しを傍受することでしかライブラリをインストルメンテーションできないからです。

バンドルされたモジュールを使用する Node.js アプリケーションをインストルメンテーションするには、 requireの呼び出しが OpenTelemetry から見えるように、Webpack externals 設定オプションを使用します。

以下の例では、 express フレームワークをインストルメンテーションするために、webpack.config.js ファイルを編集する方法を示しています：

module.exports = {
   // ...
   externalsType: "node-commonjs",
   externals: [
      "express"
   // See https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node
   // for a list of supported instrumentations. Use the require name of the library or framework,
   // not the name of the instrumentation. For example, "tedious" instead of "instrumentation-tedious".
   ]
};

externals に追加すると、require メソッドを通して express フレームワークがロードされ、OpenTelemetry はそれをインストルメンテーションできるようになります。 node_modules メソッドが検出できるように、パッケージが require フォルダにあることを確認します。

# Install the library or framework and add it to node_modules
npm install express

Node.js の AlwaysOn Profilingのトラブルシューティング

AlwaysOn Profilingに関する一般的な問題と修正については、以下を参照してください：

AlwaysOn Profilingが有効になっていることを確認する

SPLUNK_PROFILER_ENABLED 環境変数を true に設定して、プロファイラが有効になっていることを確認してください。「AlwaysOn Profiling の Node.js 設定」を参照してください。

サポートされていないNode.jsのバージョン

AlwaysOn Profiling を使用するには、Node.js をバージョン 16 以降にアップグレードします。

AlwaysOn Profiling のデータとログが Splunk Observability Cloud に表示されない

Collector 構成の問題により、AlwaysOn Profilingデータとログが Splunk Observability Cloud に表示されない場合があります。

この問題を解決するには、次のようにしてください：

1. Node.jsエージェントの設定、特に SPLUNK_PROFILER_LOGS_ENDPOINT をチェックします。

2. Splunk Distribution of OpenTelemetry Collectorが期待されるエンドポイントで実行されていること、アプリケーションホストまたはコンテナがホスト名を解決して OTLP ポートに接続できることを確認します。

3. Splunk Distribution of OpenTelemetry Collector が実行されていて、バージョンが 0.34 以降であることを確認します。他のコレクタの配布では、プロファイリングデータを含むログデータをルーティングできない場合があります。

4. カスタム設定は、コレクタにプロファイリングデータを処理させる設定をオーバーライドする場合があります。otlp レシーバと splunk_hec エクスポータに正しいトークンとエンドポイントフィールドを設定してください。profiling パイプラインは、構成した OTLP レシーバと Splunk HEC エクスポータを使用する必要があります。

次のスニペットには、profiling パイプラインのサンプルが含まれています：

receivers:
  otlp:
    protocols:
      grpc:

exporters:
  # Profiling
  splunk_hec/profiling:
    token: "${SPLUNK_ACCESS_TOKEN}"
    endpoint: "${SPLUNK_INGEST_URL}/v1/log"
    log_data_enabled: false

processors:
  batch:
  memory_limiter:
    check_interval: 2s
    limit_mib: ${SPLUNK_MEMORY_LIMIT_MIB}

service:
  pipelines:
    logs/profiling:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [splunk_hec, splunk_hec/profiling]