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

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

互換性要件

Nodejs トレーサーの最新バージョンは、バージョン >=12 を公式にサポートしています。バージョン 8 および 10 は 0.x リリースラインのメンテナンスモードでサポートされます。Node のバージョンサポートおよび対応するバージョンについて詳しくは、互換性要件ページを参照してください。 

インストールと利用開始

Datadog トレースライブラリを Node.js アプリケーションに追加するには、次の手順に従います。

  1. Node.js 12 以降に対応する npm を使用して Datadog Tracing ライブラリをインストールします。

    npm install dd-trace --save

    発売終了済みの Node.js バージョン 10 または 8 をトレースしたい場合は、以下を実行して dd-trace のバージョン 0.x をインストールしてください。

    npm install dd-trace@latest-node10

    または

    npm install dd-trace@latest-node8

    ディストリビューションタグおよび Node.js のランタイムばージョンサポートについて詳しくは、互換性要件 ページを参照してください。

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

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

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

  3. APM に Datadog Agent を構成する

  4. 統合サービスタグ付けの service、env、version など、必要なコンフィギュレーションをトレーサーに追加します。

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

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

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

APM に Datadog Agent を構成する

インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は apm_config 下にある datadog.yaml ファイルの enabled: true で有効になっており、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 に送信します。これが正しいホストとポートでない場合は、以下の環境変数を設定して変更します。

      DD_AGENT_HOST と DD_TRACE_AGENT_PORT

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

      UDS などの異なるプロトコルを使用するには、URL 全体を単一の環境変数 DD_TRACE_AGENT_URL として指定します。

      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、Azure App Services Extension など、他の多くの環境で利用できます。

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

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

    コンフィギュレーション

    トレーサーの設定は、パラメーターを init() メソッドとして、または環境変数として構成できます。

    タグ付け

    env
    環境変数: DD_ENV
    デフォルト: null
    アプリケーションの環境 (例: prod、pre-prod、stage ) を設定します。バージョン 0.20 以降で利用可能。
    service
    環境変数: DD_SERVICE
    デフォルト: null
    このプログラムで使用するサービス名。バージョン 0.20 以降で利用可能。
    version
    環境変数: DD_VERSION
    デフォルト: null
    アプリケーションのバージョン番号。デフォルトは、package.json のバージョンフィールドの値です。バージョン 0.20 以降で利用可能。
    tags
    環境変数: DD_TAGS
    デフォルト: {}
    すべてのスパンおよびメトリクスに適用されるべきグローバルタグを設定します。環境変数としてパスした場合、フォーマットは key:value,key:value となります。プログラム的に設定する場合は、tracer.init({ tags: { foo: 'bar' } }) となり、バージョン 0.20 以降で利用可能。

    サービスに env、service、version を設定するには、DD_ENV、DD_SERVICE、DD_VERSION を使用することをおすすめします。このような環境変数の構成におすすめの方法については、統合サービスタグ付けのドキュメントをご参照ください。

    インスツルメンテーション

    enabled
    環境変数: DD_TRACE_ENABLED
    デフォルト: true
    トレーサーを有効にするかどうか。
    debug
    環境変数: DD_TRACE_DEBUG
    デフォルト: false
    トレーサーでデバッグロギングを有効化します。
    url
    環境変数: DD_TRACE_AGENT_URL
    デフォルト: null
    トレーサーが送信するトレース Agent の URL。設定した場合、ホスト名およびポートより優先されます。datadog.yaml ファイルの apm_config.receiver_socket または DD_APM_RECEIVER_SOCKET 環境変数と組み合わせて、Unix ドメインソケットをサポートします。
    hostname
    環境変数: DD_TRACE_AGENT_HOSTNAME
    デフォルト: localhost
    トレーサーが送信する Agent のアドレス。
    port
    環境変数: DD_TRACE_AGENT_PORT
    デフォルト: 8126
    トレーサーが送信するトレース Agent のポート。
    dogstatsd.port
    環境変数: DD_DOGSTATSD_PORT
    デフォルト: 8125
    メトリクスが送信される DogStatsD Agent のポート。
    logInjection
    環境変数: DD_LOGS_INJECTION
    デフォルト: false
    対応するログライブラリのログにトレース ID の自動挿入を有効にします。
    sampleRate
    デフォルト: 1
    スパンのサンプリング率: 0〜1 間の浮動小数点。
    flushInterval
    デフォルト: 2000
    トレーサーが Agent へトレースを送信する際のインターバル (ミリセカンド)。
    runtimeMetrics
    環境変数: DD_RUNTIME_METRICS_ENABLED
    デフォルト: false
    ランタイムメトリクスのキャプチャを有効にするかどうか。ポート 8125 (または dogstatsd.port で構成) が UDP 用に Agent で開いている必要があります。

    環境変数: DD_SERVICE_MAPPING
    デフォルト: null
    例: mysql:my-mysql-service-name-db,pg:my-pg-service-name-db
    各プラグインのサービス名を提供します。カンマ区切りの plugin:service-name ペア (スペースありまたはなし) を許容します。

    experimental
    デフォルト: {}
    試験機能は、 Boolean の true を使用して一度に、またはキー/値のペアを使用して個々に有効にできます。試験機能に関する詳細は、サポートまでお問合せください。
    plugins
    デフォルト: true
    ビルトインプラグインを使用して、外部ライブラリの自動インスツルメンテーションを有効にするかどうか。
    DD_TRACE_DISABLED_PLUGINS
    トレーサーが初期化された際に自動で無効となるインテグレーション名のカンマ区切り文字列。DD_TRACE_DISABLED_PLUGINS=express,dns などの環境変数のみとなります。
    logLevel
    環境変数: DD_TRACE_LOG_LEVEL
    デフォルト: debug
    デバッグロギングが有効な場合に使用する、トレーサーの最小ログレベル用ストリング (例: error、debug)。

    その他の参考資料

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

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