Node.js アプリケーションのトレース

Docs > APM > Datadog へのトレースの送信 > Automatic Instrumentation > Add the Datadog Tracing Library > Node.js アプリケーションのトレース

互換性要件

最新の Node.js トレーサーは、バージョン >=14 に対応しています。Datadog の Node.js バージョンとフレームワークのサポート一覧 (レガシーバージョンとメンテナンスバージョンを含む) については、互換性要件ページをご覧ください。

はじめに

作業を始める前に、Agent のインストールと構成が済んでいることを確認してください。

アプリケーションをインスツルメントする

Datadog Agent をインストールして構成したら、次はアプリケーションに直接トレーシングライブラリを追加してインスツルメントします。互換性情報の詳細をお読みください。

Agent のインストールが完了したら、以下の手順で Datadog のトレーシングライブラリを Node.js アプリケーションに追加します。

Node.js 14 以降に対応する npm を使用して Datadog Tracing ライブラリをインストールします。
```
npm install dd-trace --save
```
発売終了済みの Node.js バージョン 12 をトレースしたい場合は、以下を実行して dd-trace のバージョン 2.x をインストールしてください。
```
npm install dd-trace@latest-node12
```
ディストリビューションタグおよび Node.js のランタイムばージョンサポートについて詳しくは、互換性要件ページを参照してください。ライブラリの以前のメジャーバージョン (0.x、1.x、2.x) から別のメジャーバージョン (2.x、3.x) にアップグレードする場合は、移行ガイドを読み、変更点を評価するようにしてください。
コードまたはコマンドライン引数を使用して、トレーサーをインポートして初期化します。Node.js トレースライブラリは、他のモジュールの前にインポートして初期化する必要があります。
セットアップが完了した後、Web リクエストの URL ルートの欠落、スパンの切断または欠落など、完全なトレースを受信していない場合は、ステップ 2 が正しく行われたことを確認してください。最初に初期化されるトレースライブラリは、トレーサーが自動インスツルメンテーションに必要なすべてのライブラリに適切にパッチを適用するために必要です。
TypeScript、Webpack、Babel などのトランスパイラーを使用する場合は、トレーサーライブラリを外部ファイルにインポートして初期化し、アプリケーションをビルドするときにそのファイル全体をインポートします。

コードにトレーサーを追加する

JavaScript

// の行は、インスツルメントされたいずれのモジュールのインポートより前である必要があります。
const tracer = require('dd-trace').init();

TypeScript とバンドラー

EcmaScript モジュール構文をサポートする TypeScript およびバンドラーの場合、正しいロード順序を維持するために、別のファイルでトレーサーを初期化します。

// server.ts
import './tracer'; // インスツルメントされたいずれのモジュールのインポートより前である必要があります。

// tracer.ts
import tracer from 'dd-trace';
tracer.init(); // ホイストを避けるため異なるファイルで初期化。
export default tracer;

デフォルトのコンフィギュレーションで十分な場合、またはすべてのコンフィギュレーションが環境変数を介して行われる場合は、dd-trace/init を使用することもできます。これは 1 つのステップでロードおよび初期化されます。

import 'dd-trace/init';

コマンドライン引数を介したトレーサーの追加

Node.js の --require オプションを使用して、トレーサーを 1 回のステップでロードして初期化します。

node --require dd-trace/init app.js

注: このアプローチでは、トレーサーのすべてのコンフィギュレーションに環境変数を使用する必要があります。

バンドル

dd-trace は Node.js アプリケーションがモジュールをロードする際に行う require() 呼び出しを傍受することで動作します。これには、ファイルシステムにアクセスするための fs モジュールのような Node.js に組み込まれているモジュールや、pg データベースモジュールのような NPM レジストリからインストールされたモジュールが含まれます。

バンドラーはアプリケーションがディスク上のファイルに対して行う require() 呼び出しをすべてクロールします。require() の呼び出しをカスタムコードに置き換え、その結果の JavaScript を 1 つの “バンドルされた” ファイルにまとめます。require('fs') のような組み込みモジュールがロードされたとき、その呼び出しは結果として生成されるバンドルにそのまま残ります。

dd-trace のような APM ツールはこの時点で機能しなくなります。組み込みモジュールの呼び出しは引き続き傍受できますが、サードパーティライブラリの呼び出しは傍受しません。つまり、dd-trace アプリをバンドラーでバンドルすると、ディスクアクセス (fs 経由) とアウトバウンド HTTP リクエスト (http 経由) の情報はキャプチャしますが、サードパーティライブラリの呼び出しは省略する可能性が高くなります。例:

express フレームワークの受信リクエストルート情報を抽出する。
データベースクライアント mysql に対して実行されるクエリを表示する。

一般的な回避策は、APM がインスツルメンテーションする必要のあるすべてのサードパーティモジュールを、バンドラーの “外部” として扱うことです。この設定では、インスツルメンテーションされたモジュールはディスク上に残り、require() でロードされ続け、インスツルメンテーションされていないモジュールはバンドルされます。しかし、これでは余計なファイルがたくさんあるビルドになってしまい、バンドルする意味がなくなってしまいます。

Datadog では、カスタムビルトバンドラープラグインを推奨しています。このプラグインは、バンドラーに動作を指示したり、中間コードを挿入したり、“翻訳された” require() 呼び出しを傍受したりすることができます。その結果、より多くのパッケージがバンドルされた JavaScript ファイルに含まれるようになります。

注: アプリケーションによっては、100% のモジュールをバンドルすることができますが、ネイティブモジュールはまだバンドルの外部に残しておく必要があります。

Esbuild サポート

このライブラリは esbuild プラグインの形で実験的な esbuild サポートを提供し、少なくとも Node.js v16.17 または v18.7 が必要です。プラグインを使用するには、dd-trace@3+ がインストールされていることを確認し、バンドルをビルドするときに dd-trace/esbuild モジュールを要求します。

以下は esbuild で dd-trace を使う例です。

const ddPlugin = require('dd-trace/esbuild')
const esbuild = require('esbuild')

esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [ddPlugin],
  platform: 'node', // 組み込みモジュールの使用を可能にします
  target: ['node16'],
  external: [
    // esbuild はネイティブモジュールをバンドルできません
    '@datadog/native-metrics',

    // プロファイリングを使用する場合は必須です
    '@datadog/pprof',

    // Datadog のセキュリティ機能を使用する場合は必須です
    '@datadog/native-appsec',
    '@datadog/native-iast-taint-tracking',
    '@datadog/native-iast-rewriter',

    // ビルドステップで graphql エラーが発生した場合は必須です
    'graphql/language/visitor',
    'graphql/language/printer',
    'graphql/utilities'
  ]
}).catch((err) => {
  console.error(err)
  process.exit(1)
})

注: トレーサーでは、コンパイルされた C++ コードであるネイティブモジュール (通常、拡張機能が .node で終わる) を使用するため、 external リストにエントリを追加する必要があります。現在、Node.js トレーサーで使用されているネイティブモジュールは @datadog プレフィックス付きパッケージの中にあります。このため、バンドルしたアプリケーションと共に node_modules/ ディレクトリも配布する必要があります。ディレクトリには、バンドル内に含まれるべき多くの不要なパッケージがあるため、node_modules/ ディレクトリ全体を配布する必要はありません。

必要なネイティブモジュール (とその依存関係) だけを含む、より小さな node_modules/ ディレクトリを生成するには、まず必要なパッケージのバージョンを決定し、それらをインストールするための一時ディレクトリを作成し、そこから結果の node_modules/ ディレクトリをコピーします。例:

cd path/to/project
npm ls @datadog/native-metrics
# dd-trace@5.4.3-pre ./dd-trace-js
# └── @datadog/native-metrics@2.0.0
$ npm ls @datadog/pprof
# dd-trace@5.4.3-pre ./dd-trace-js
# └── @datadog/pprof@5.0.0
mkdir temp && cd temp
npm init -y
npm install @datadog/native-metrics@2.0.0 @datadog/pprof@5.0.0
cp -R ./node_modules path/to/bundle