互換性要件

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

はじめに

作業を始める前に、Agent のインストールと構成 が済んでいることを確認してください。確認したら、以下の手順を実行して、Datadog SDK を Node.js アプリケーションに追加し、そのアプリケーションをインスツルメントします。

Datadog SDK のインストール

Node.js 18 以降に対応する npm を使用して Datadog SDK をインストールするには、以下を実行します。

npm install dd-trace

サポートを終了した Node.js バージョン 16 に対応する Datadog SDK (dd-trace のバージョン 4.x) をインストールするには、以下を実行します。

npm install dd-trace@latest-node16

Datadog のディストリビューションタグおよび Node.js のランタイムバージョンサポートについて詳しくは、互換性要件 ページを参照してください。 ライブラリの以前のメジャーバージョン (0.x、1.x、2.x、3.x、4.x) から別のメジャーバージョンにアップグレードする場合は、移行ガイド を読み、変更点を評価してください。

      npm install dd-trace -D # instead of `npm install dd-trace`
    

Datadog パブリック API のインストール (オプション)

このステップは、Serverless またはシングルステップインスツルメンテーションでカスタムインスツルメンテーションを行う場合にのみ必要です。ほかのカスタムインスツルメンテーションのユースケースではオプションです。Datadog パブリック API を使用すべき状況の詳細については、Datadog API を使用したカスタムインスツルメンテーション を参照してください。

npm install dd-trace-api

続けて、カスタムインスツルメンテーションを実施する任意のコード内で dd-trace-api の代わりに dd-trace をインポートできます。

トレーサーのインポートと初期化

トレーサーをコード内で、またはコマンドライン引数を使用して、インポートして初期化します。Node.js SDK は、その他すべてのモジュールより前にインポートして初期化する必要があります。

セットアップの完了後、Web リクエストの URL ルートがない、切断されている、スパンがないなどの、不完全なトレースを受信する場合は、SDK が正しくインポートされ、初期化されていることを確認してください。SDK が自動インスツルメンテーションに必要なすべてのライブラリに適切にパッチを適用するには、最初に SDK を初期化しておく必要があります。

TypeScript、Webpack、Babel などのトランスパイラーを使用する場合は、SDK を外部ファイルにインポートして初期化し、アプリケーションをビルドするときにそのファイル全体をインポートします。

コマンドライン引数による SDK の追加

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

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

上記のアプローチでは、SDK のすべての構成に環境変数を使用する必要があります。プログラムによる構成を使用する必要がある場合は、専用ファイルで dd-trace を初期化し、代わりにそのファイルを要求してください。

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

ファイルには次の内容が含まれている必要があります。

// ./dd-trace.js
require('dd-trace').init({
  // programmatic config
})

CLI 引数を制御できない場合は、代わりに環境変数を使用できます。

ESM アプリケーションの場合のみ: ローダーをインポートする

ESM (ECMAScript モジュール) アプリケーションには、_追加の_コマンドライン引数が必要です。この引数は、SDK がどのようにインポートおよび初期化されるかに関係なく追加してください。

• v20.6 より前の Node.js の場合: --loader dd-trace/loader-hook.mjs
• v20.6 以降の Node.js の場合: --import dd-trace/register.js

たとえば、Node.js 22 で上記のオプション 1 を使用して SDK を初期化する場合、次のように開始します。

node --import dd-trace/register.js app.js

これは、--require dd-trace/init コマンドライン引数と組み合わせることもできます。

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

Node.js v20.6 以降では、両方のコマンドライン引数を組み合わせて使用するための簡単な方法があります。

node --import dd-trace/initialize.mjs 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', // allows built-in modules to be required
  target: ['node16'],
  external: [
    // required if you use native metrics
    '@datadog/native-metrics',

    // required if you use profiling
    '@datadog/pprof',

    // required if you use Datadog security features
    '@datadog/native-appsec',
    '@datadog/native-iast-taint-tracking',
    '@datadog/native-iast-rewriter',
  ]
}).catch((err) => {
  console.error(err)
  process.exit(1)
})

Next.js でのバンドル

Next.js、またはアプリケーションのバンドルに Webpack を利用する別のフレームワークを使用している場合は、 ご使用の next.config.js 構成ファイル内の Webpack に、次のような宣言を追加します。

/** @type {import('next').NextConfig} */
const nextConfig = {
  // ... non-relevant parts omitted, substitute your own config ...

  // this custom webpack config is required for Datadog tracing to work
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }
  ) => {
    const externals = [
      // required if you use native metrics
      '@datadog/native-metrics',

      // required if you use profiling
      '@datadog/pprof',

      // required if you use Datadog security features
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/native-iast-rewriter',
    ];
    config.externals.push(...externals);
    return config;
  },
};

export default nextConfig;

サポート対象外の Datadog 機能

以下の機能は、Node.js トレーサーでデフォルトで無効になっています。これらはバンドルに対応していないため、アプリケーションがバンドルされている場合は使用できません。

• APM: Dynamic Instrumentation

一般的なバンドルに関する注意事項

注: SDK 内のネイティブモジュール (コンパイル済みの 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

注: Next.js の場合、一般に path/to/bundle はアプリの .next/standalone ディレクトリです。

この段階で、バンドル (アプリケーションコードと依存関係の大部分) と、ネイティブモジュールとその依存関係を含む node_modules/ ディレクトリをデプロイできるはずです。

構成

必要に応じて、unified service tagging の設定など、アプリケーションパフォーマンスのテレメトリデータを送信するための SDK を構成します。詳細については、ライブラリの構成 を参照してください。

初期化のオプションについては、トレーサー設定 をお読みください。

参考資料

お役に立つドキュメント、リンクや記事:

ソースコードソースコード API ドキュメントよくあるご質問 サービス、リソース、トレースを調査するよくあるご質問 高度な使用方法よくあるご質問