Node.jsアプリケーションをSplunk Observability Cloudにインストルメンテーションする 🔗
注釈
Due to changes in the upstream OpenTelemetry documentation, 「automatic instrumentation」 has been changed to 「zero-code instrumentation」. For more information, see Instrumentation methods for Splunk Observability Cloud.
Splunk Distribution of OpenTelemetry JS は、Node.js アプリケーションと、アプリケーションが使用する一般的な node.js ライブラリの多くを自動的にインストルメンテーションできます。
開始するには、ガイド付きセットアップを使用するか、手動で指示に従ってください。
ガイド付きセットアップを使用してカスタマイズされた指示を生成する 🔗
環境とアプリケーションの基本的なインストールコマンドをすべて生成するには、Node.js ガイド付きセットアップを使用します。Node.jsガイド付きセットアップにアクセスするには、以下の手順に従います:
Splunk Observability Cloud にログインします。
Node.js ガイド付きセットアップ を開きます。オプションで、ガイド付きセットアップに自分で移動することもできます:
ナビゲーションメニューで、
を選択します。Go to the Available integrations tab, or select Add Integration in the Deployed integrations tab.
インテグレーションフィルターーメニューで、By Product を選択します。
APM 製品を選択します。
Node.jsのガイド付きセットアップを開くには、Node.js タイルを選択します。
Splunk Distribution of OpenTelemetry JS を手動でインストールする 🔗
ガイド付きセットアップを使用しない場合は、以下の手順に従って手動で Splunk Distribution of OpenTelemetry JS をインストールしてください:
Node.jsインストルメンテーションをインストールし、有効化します。 🔗
Splunk Distribution of OpenTelemetry JS で Node.js アプリケーションをインストルメンテーションするには、以下の手順に従ってください:
@splunk/otel
パッケージをインストールします:npm install @splunk/otel
カスタムインストルメンテーションを追加するには、カスタムインストルメンテーションの追加 を参照してください。
環境変数
OTEL_SERVICE_NAME
を設定します:export OTEL_SERVICE_NAME=<yourServiceName>
$env:OTEL_SERVICE_NAME=<yourServiceName>
(オプション) Splunk Distribution of OpenTelemetry Collectorが別のホストで実行されている場合は、エンドポイント URL を設定します:
export OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>
$env:OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>
(オプション)デプロイ環境とサービスバージョンを設定します:
export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
$env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
(オプション) メトリクス収集を有効にします。メトリクス・コレクションを有効にする を参照してください。
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
環境変数を使用してメトリクス機能を有効にします。詳細については、メトリクスの設定 を参照してください。
export SPLUNK_METRICS_ENABLED='true'
$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ファイル を参照してください。
KubernetesにNode.jsディストリビューションをデプロイする 🔗
Kubernetes環境にCollector for Node.jsをデプロイするには、以下の手順に従ってください:
アプリケーションイメージのDockerfileを編集し、以下のコマンドを追加します:
# Install the @splunk/otel package RUN npm install @splunk/otel # Set appropriate permissions RUN chmod -R go+r /node_modules/@splunk/otel
環境変数を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 に直接データを送信する必要がある場合は、以下の環境変数を設定します:
export SPLUNK_ACCESS_TOKEN=<access_token>
export SPLUNK_REALM=<realm>
$env:SPLUNK_ACCESS_TOKEN=<access_token>
$env:SPLUNK_REALM=<realm>
アクセストークンを取得するには、Splunk Observability Cloudを使用したユーザー APIアクセストークンの取得と管理 を参照してください。
Splunk レルムを見つけるには、レルムに関する注意事項 を参照してください。
取り込みAPIエンドポイントの詳細については、APMのトレースの送信 を参照してください。
注意
この手順はスパンとトレースに適用されます。AlwaysOn Profiling データを送信するには、OTel Collector を使用する必要があります。
ソースホストの指定 🔗
エージェントが使用するホストを上書きするには、環境変数 OTEL_RESOURCE_ATTRIBUTES
を使用して、ホストの名前を希望するソースに設定します:
$env:OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>
export OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>
Lambda 関数のインストルメンテーション 🔗
Splunk OpenTelemetry Lambda Layer を使用して AWS Lambda 関数をインストルメンテーションできます。詳細は AWS Lambda 関数を Splunk Observability Cloud にインストルメンテーションする を参照してください。