Node.jsアプリケーションをSplunk Observability Cloudにインストルメンテーションする

Splunk Distribution of OpenTelemetry Node.js は、Node.js アプリケーションやサービスを自動的にインストルメンテーションできます。次の手順に従って、操作を開始します。

注: 元の OpenTelemetry ドキュメントに変更があったため、「自動インストルメンテーション」は「ゼロコード インストルメンテーション」に変更されました。詳細については、「Splunk Observability Cloud のインストルメンテーションの方法」を参照してください。

Splunk Distribution of OpenTelemetry JS は、Node.js アプリケーションと、アプリケーションが使用する一般的な node.js ライブラリの多くを自動的にインストルメンテーションできます。

開始するには、ガイド付きセットアップを使用するか、手動で指示に従ってください。

ガイド付きセットアップを使用してカスタマイズされた指示を生成する

環境とアプリケーションのための基本的なインストールコマンドをすべて生成するには、Node.js ガイド付きセットアップを使用してください。Node.js ガイド付きセットアップにアクセスするには、以下の手順に従ってください。

  1. Splunk Observability Cloud にログインします。

  2. Node.js のガイド付きセットアップを開きます。オプションで、ガイド付きセットアップに自分で移動することもできます：

    1. ナビゲーションメニューで、Data Management を選択します。

    2. Available integrations タブにアクセスするか、Deployed integrations タブで Add Integration を選択します。

    3. インテグレーションフィルターメニューで、By Product を選択します。

    4. APM 製品を選択します。

    5. Node.jsのガイド付きセットアップを開くには、Node.js タイルを選択します。

Splunk Distribution of OpenTelemetry JS を手動でインストールする

ガイド付きセットアップを使用しない場合は、以下の手順に従って Splunk Distribution of OpenTelemetry JS を手動でインストールしてください。

Node.jsインストルメンテーションをインストールし、有効化します。

Splunk Distribution of OpenTelemetry JS で Node.js アプリケーションをインストルメンテーションするには、以下の手順に従ってください：

  1. @splunk/otel パッケージをインストールします：

    npm install @splunk/otel

    カスタム インストルメンテーションを追加するには、「カスタム インストルメンテーションを追加する」を参照してください。

  2. OTEL_SERVICE_NAME 環境変数を設定します：

    Linux
    export OTEL_SERVICE_NAME=<yourServiceName>
    Windows PowerShell
    $env:OTEL_SERVICE_NAME=<yourServiceName>

  3. (オプション) Splunk Distribution of OpenTelemetry Collectorが別のホストで実行されている場合は、エンドポイント URL を設定します：

    Linux
    export OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>
    Windows PowerShell
    $env:OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>

  4. (オプション）デプロイ環境とサービスバージョンを設定します：

    Linux
    export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
    Windows PowerShell
    $env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

  5. （オプション）メトリクスコレクションを有効にします。「メトリクスコレクションを有効にする」を参照してください。

  6. Node.jsアプリケーションを実行するには、以下のコマンドを入力します：

    node -r @splunk/otel/instrument <your-app.js>

APM に何もデータが表示されない場合は、「Splunk Observability Cloud の Node.js インストルメンテーションのトラブルシューティング」を参照してください。

注: Webpack を使用するアプリケーションをインストルメンテーションするには、「Webpack の互換性の問題」を参照してください。

AlwaysOn Profilingの有効化

AlwaysOn Profiling を有効にするには、SPLUNK_PROFILER_ENABLED 環境変数 を true に設定します。

メモリプロファイリングを有効にするには、AlwaysOn Profilingを有効にした後、SPLUNK_PROFILER_MEMORY_ENABLED 環境変数を true に設定します。

次の例は、アプリケーションコードからプロファイラを起動する方法を示しています：

start({
   serviceName: '<service-name>',
   endpoint: 'collectorhost:port',
   profiling: {                       // Activates CPU profiling
      memoryProfilingEnabled: true,   // Activates Memory profiling
   }
});

詳細については、「Splunk APMのAlwaysOn Profiling にデータを取り込む」を参照してください。詳細な設定については、「AlwaysOn Profiling の Node.js 設定」を参照してください。

メトリクス・コレクションを有効にする

実行時の自動メトリクスコレクションを有効にするには、SPLUNK_METRICS_ENABLED 環境変数を使用して、メトリクス機能を有効にします。詳細については、「メトリクスの設定」を参照してください。

Linux
export SPLUNK_METRICS_ENABLED='true'
Windows PowerShell
$env:SPLUNK_METRICS_ENABLED='true'

Node.jsディストリビューションの設定

ほとんどの場合、入力する必要がある設定はサービス名だけです。トレース伝播フォーマットの変更やサーバートレースデータの構成などの高度な設定については、「Splunk Observability Cloud 用の Splunk Distribution of OTel JS を設定する」を参照してください。

プログラムでアプリケーションをインストルメンテーションする

トレースパイプラインをさらに細かく制御するには、Node.jsアプリケーションをプログラムでインストルメンテーションします。

プログラムでアプリケーションをインストルメンテーションするには、インストルメンテーション関数を呼び出す前に、エントリポイントスクリプトの先頭に以下の行を追加します：

const { start } = require('@splunk/otel');

start({
   serviceName: 'my-node-service',
   endpoint: 'http://localhost:4317'
});

// Rest of your main module

start() 関数は、コンフィギュレーション設定を引数として受け取ります。たとえば、ランタイムメトリクスやメモリプロファイリングを有効にするために使用できます。

start({
   serviceName: 'my-node-service',
   metrics: { runtimeMetricsEnabled: true },
   profiling: { memoryProfilingEnabled: true }
});

エントリー・ポイント・スクリプトに start() 関数を追加したら、-r フラグを使用してインストルメンテーションされたエントリー・ポイント・スクリプトを渡してアプリケーションを実行します：

node -r <entry-point.js> <your-app.js>

カスタムインストルメンテーションの追加

OpenTelemetry JS Instrumentation インターフェイスを実装したカスタムまたはサードパーティのインストルメンテーションを追加するには、以下のコードを使って start() に渡します：

const { start } = require('@splunk/otel');
const { getInstrumentations } = require('@splunk/otel/lib/instrumentations');

start({
   tracing: {
      instrumentations: [
         ...getInstrumentations(), // Adds default instrumentations
         new MyCustomInstrumentation(),
         new AnotherInstrumentation(),
      ],
   },
});

サポートされているインストルメンテーションのリストは、GitHub の https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations を参照してください。

注: エントリー ポイント スクリプトの例については、GitHub の sample tracer.js file を参照してください。

KubernetesにNode.jsディストリビューションをデプロイする

Kubernetes環境にCollector for Node.jsをデプロイするには、以下の手順に従ってください：

  1. アプリケーションイメージのDockerfileを編集し、以下のコマンドを追加します：

    # Install the @splunk/otel package
RUN npm install @splunk/otel
# Set appropriate permissions
RUN chmod -R go+r /node_modules/@splunk/otel

  2. 環境変数をKubernetesリソースに公開するために、Kubernetes Downward APIを設定します。

    次の例は、.spec.template.spec.containers.env セクションの下に OpenTelemetry 設定を追加して、環境変数を公開するようにデプロイメントを更新する方法を示しています：

    apiVersion: apps/v1
kind: Deployment
spec:
selector:
   matchLabels:
      app: your-application
template:
   spec:
      containers:
      - name: myapp
        image: your-app-image
        env:
         - name: SPLUNK_OTEL_AGENT
           valueFrom:
             fieldRef:
               fieldPath: status.hostIP
         - name: OTEL_EXPORTER_OTLP_ENDPOINT
           value: "http://$(SPLUNK_OTEL_AGENT):4317"
         - name: OTEL_SERVICE_NAME
           value: "<serviceName>"
         - name: OTEL_RESOURCE_ATTRIBUTES
           value: "deployment.environment=<environmentName>"
        command:
         - node
         - -r @splunk/otel/instrument
         - <your-app>.js

Splunk Observability Cloud に直接データを送信する

デフォルトでは、すべてのテレメトリは Splunk Distribution of OpenTelemetry Collector のローカルインスタンスに送信されます。

Splunk Observability Cloud に直接データを送信する必要がある場合は、以下の環境変数を設定します：

Linux
export SPLUNK_ACCESS_TOKEN=<access_token>
export SPLUNK_REALM=<realm>
Windows PowerShell
$env:SPLUNK_ACCESS_TOKEN=<access_token>
$env:SPLUNK_REALM=<realm>

アクセストークンを取得するには、「Splunk Observability Cloud を使用したユーザー API アクセストークンの取得と管理」を参照してください。

Splunk レルムを見つけるには、「Note about realms」を参照してください。

取り込み API エンドポイントの詳細については、「APM のトレースの送信」を参照してください。

注意: この手順は、スパンとトレースに適用されます。AlwaysOn Profiling データを送信するには、OTel Collector を使用する必要があります。

ソースホストの指定

エージェントが使用するホストを上書きするには、環境変数 OTEL_RESOURCE_ATTRIBUTES を使用して、ホストの名前を希望するソースに設定します。

Windows PowerShell
$env:OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>
Linux
export OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>

Lambda 関数のインストルメンテーション

Splunk OpenTelemetry Lambda Layer を使用して AWS Lambda 関数をインストルメンテーションできます。詳細については、「AWS Lambda 関数を Splunk Observability Cloud にインストルメンテーションする」を参照してください。