Node.js のゼロコード計装¶

Beacon Node.js は、パッケージで検証済みのメンテナンス対象 Node.js 系列に対応し、最低バージョンは Node.js 18.19 です。Security のランタイム要件は、後述のとおりさらに限定されます。

接続前に共通設定を完了し、DataKit OpenTelemetry コレクターを有効にしてください。以下は Linux/macOS のシェルの例で、アプリケーションと DataKit が同じホストにあることを前提とします。別ホストやコンテナに配置する場合は、127.0.0.1 を置き換え、リッスンアドレスを調整してください。

インストール¶

npm install @beacon-observability/nodejs

起動¶

export OTEL_SERVICE_NAME=my-node-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export NODE_OPTIONS="--require @beacon-observability/nodejs/register"
node app.js

アプリケーションの既存の node コマンドを保持してください。NODE_OPTIONS にすでに設定がある場合は、既存の引数を上書きせずに --require を追加します。

デバッグと診断¶

上記の NODE_OPTIONS プリロード設定を保持し、一時的に OpenTelemetry の診断ログを有効にします。

OTEL_LOG_LEVEL=debug node app.js > beacon-nodejs-debug.log 2>&1

ログは端末に出力されます。上のコマンドは標準出力と標準エラーをまとめて保存します。Security を有効にする場合は、必要な ESM --import プリロードを引き続き使用してください。

調査後は通常の起動コマンドに戻してください。デプロイ環境に OTEL_LOG_LEVEL=debug を設定した場合は、その設定を削除してアプリケーションを再起動します。

Profile¶

先に DataKit Profile コレクターを有効にし、以下の変数を設定して、上記の起動方法を引き続き使用してください。Profile は独立した HTTP アップロード先を使用し、OTLP Trace のアドレスとは共用しません。

@beacon-observability/nodejs には Profile 機能が含まれています。Node.js ゼロコードガイドのプリロード設定を保持し、互換 pprof multipart 形式を受け付ける HTTP 受信先を設定してください。

export NODE_OPTIONS="--require @beacon-observability/nodejs/register"
export OTEL_SERVICE_NAME=my-node-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_PPROF_UPLOAD_URL=http://127.0.0.1:9529/profiling/v1/input
node app.js

既定では wall profile が有効です。heap profile も収集する場合は、次のように設定します。

export OTEL_PROFILING_MEMORY_ENABLED=true

既定のアップロード間隔は 60 秒です。OTEL_PROFILING_EXPORT_INTERVAL で秒単位の間隔を設定でき、OTEL_PROFILING_PPROF_HEADERS でカンマ区切りの name:value HTTP ヘッダーを指定できます。

パラメーターリファレンス¶

環境変数名は大文字と小文字を区別します。

環境変数	型 / 設定値	既定値	説明
`OTEL_PROFILING_ENABLED`	真偽値。`true`、`1`、`yes`、`on` で有効化	`false`	pprof の収集を有効にします。
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	未設定	Profile を有効にする場合は必須です。multipart pprof アップロードを受信する URL。
`OTEL_PROFILING_EXPORT_INTERVAL`	正の数、秒	`60`	Profile の収集とアップロードの間隔。
`OTEL_PROFILING_MEMORY_ENABLED`	真偽値	`false`	既定の wall-time Profile に加えて heap Profile を収集します。
`OTEL_PROFILING_PPROF_HEADERS`	カンマ区切りの `name=value` または `name:value`	空	追加の HTTP リクエストヘッダー。

エクスポーターは OTEL_SERVICE_NAME と、OTEL_RESOURCE_ATTRIBUTES 内の service.version、deployment.environment.name（または deployment.environment）、host.name を Profile のメタデータとして使用します。

Security¶

Security はパッケージに含まれており、Node.js 22.22.3+ または 24.11.1+ に対応します。--require ではなく ESM --import によるプリロードが必要です。Node.js Security ガイドを参照してください。

接続の確認¶

対応するフレームワークやライブラリを経由するリクエストをアプリケーションの API に送り、Guance の「APM > トレース」で上記のサービス名を絞り込んでください。確認手順の詳細は共通設定を、データがない場合はトラブルシューティングを参照してください。