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

互換性要件

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

インストールと利用開始

アプリ内のドキュメントに従ってください (推奨)

Datadog のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:

  • デプロイコンフィギュレーション (ホスト、Docker、Kubernetes、または Amazon ECS) を範囲とする段階的な手順。
  • service、env、version タグを動的に設定します。
  • セットアップ中に Continuous Profiler、トレースの 100% の取り込み、およびトレース ID 挿入を有効にします。

APM 用に Datadog Agent を構成する

インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は apm_config 下にある datadog.yaml ファイルの enabled: true で有効になっており、http://localhost:8126 でトレースデータをリッスンします。コンテナ化環境の場合、以下のリンクに従って、Datadog Agent 内でトレース収集を有効にします。

    1. メイン datadog.yaml コンフィギュレーションファイルの apm_config セクションで apm_non_local_traffic: true を設定します。

    2. コンテナ化された環境でトレースを受信するように Agent を構成する方法については、それぞれの説明を参照してください。

    Docker
    Kubernetes
    Amazon ECS
    ECS Fargate

    1. トレースクライアントは、デフォルトでは localhost:8126 にトレースを送信します。これが Agent の正しいホストとポートでない場合、以下を実行して DD_TRACE_AGENT_HOSTNAME と DD_TRACE_AGENT_PORT 環境変数を設定してください。

      DD_TRACE_AGENT_HOSTNAME=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server

      Unix ドメインソケットを使用するには、URL 全体を一つの環境変数 DD_TRACE_AGENT_URL として指定します。

      別のソケット、ホスト、ポートが必要な場合は、DD_TRACE_AGENT_URL 環境変数または DD_TRACE_AGENT_HOST と DD_TRACE_AGENT_PORT 環境変数を使用します。いくつかの例を挙げます。

      DD_AGENT_HOST=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server
DD_TRACE_AGENT_URL=http://<HOSTNAME>:<PORT> node server
DD_TRACE_AGENT_URL=unix:<SOCKET_PATH> node server

    1. Datadog Agent の DD_SITE を に設定して、Agent が正しい Datadog の場所にデータを送信するようにします。

    AWS Lambda で Datadog APM を設定するには、サーバーレス関数のトレースドキュメントを参照してください。

    トレースは、Heroku、Cloud Foundry、AWS Elastic Beanstalk など、他の環境で利用できます。

    その他の環境については、その環境のインテグレーションのドキュメントを参照し、セットアップの問題が発生した場合はサポートにお問い合わせください。

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

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

    Kubernetes アプリケーション、または Linux ホストやコンテナ上のアプリケーションからトレースを収集する場合、以下の説明の代わりに、アプリケーションにトレーシングライブラリを挿入することができます。手順については、ライブラリの挿入をお読みください。

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

    1. 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) にアップグレードする場合は、移行ガイドを読み、変更点を評価するようにしてください。

    2. コードまたはコマンドライン引数を使用して、トレーサーをインポートして初期化します。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']
}).catch((err) => {
  console.error(err)
  process.exit(1)
})

    コンフィギュレーション

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

    その他の参考資料

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

    ソースコードGITHUB more more API ドキュメントドキュメント more more サービス、リソース、トレースを調査するAPM の UI を利用する more more 高度な使用方法高度な使用方法 more more