Node.js アプリケーションのトレース
Datadog の調査レポート: サーバーレスの状態 レポート: サーバーレスの状態

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

インストールと利用開始

Datadog アカウントをお持ちの場合、アプリ内ガイドでホストベースの設定やコンテナベースの設定に関する詳細な手順をご確認いただけます。

APM で使用される用語の説明は、公式ドキュメントを参照してください。

コンフィギュレーションおよび API の使用の詳細については、Datadog の API ドキュメントを参照してください。

貢献の詳細については、開発ガイドを参照してください。

Quickstart

このライブラリは、インスツルメントされたいずれのモジュールよりも先にインポートおよび初期化する必要があります。トランスパイラーを使用する時は、トレーサーライブラリを外部ファイルにインポートして初期化する必要があります。その後、アプリケーションを構築する際にそのファイルをまとめてインポートします。これにより、ホイストを防ぎ、他のモジュールがインポートされる前にトレーサーライブラリを確実にインポートして初期化します。

Node.js アプリケーションのトレースを開始するには、まず Datadog Agent をインストールおよび構成し、次に Docker アプリケーションのトレースまたは Kubernetes アプリケーションに関する追加ドキュメントを確認します。

次に、以下の npm を使用して Datadog Tracing ライブラリをインストールします。

npm install --save dd-trace

最後に、トレーサーをインポートして初期化します。

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

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

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

コンフィギュレーション

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

構成環境変数デフォルト説明
enabledDD_TRACE_ENABLEDtrueトレーサーを有効にするかどうか。
debugDD_TRACE_DEBUGfalseトレーサーでデバッグロギングを有効化します。
serviceDD_SERVICE_NAMEnullこのプログラムで使用するサービス名。
urlDD_TRACE_AGENT_URLnullトレーサーが送信するトレース Agent の URL。設定した場合、ホスト名およびポートより優先されます。
hostnameDD_TRACE_AGENT_HOSTNAMElocalhostトレーサーが送信する Agent のアドレス。
portDD_TRACE_AGENT_PORT8126トレーサーが送信するトレース Agent のポート。
dogstatsd.portDD_DOGSTATSD_PORT8125メトリクスが送信される DogStatsD Agent のポート。
envDD_ENVnullアプリケーションの環境 (例: prodpre-prod、staging`) を設定します。
logInjectionDD_LOGS_INJECTIONfalse対応するログライブラリのログにトレース ID の自動挿入を有効にします。
tagsDD_TAGS{}すべてのスパンおよびメトリクスに適用されるべきグローバルタグを設定します。環境変数として渡される場合、フォーマットは key:value, key:value となります。
sampleRate-1スパンのサンプリング率: 01 間の浮動小数点。
flushInterval-2000トレーサーが Agent へトレースを送信する際のインターバル (ミリセカンド)。
runtimeMetricsDD_RUNTIME_METRICS_ENABLEDfalseランタイムメトリクスのキャプチャを有効にするかどうか。ポート 8125 (または dogstatsd.port で構成) が UDP 用に Agent で開いている必要があります。
reportHostnameDD_TRACE_REPORT_HOSTNAMEfalse各トレースにシステムのホスト名を報告するかどうか。無効の場合は、Agent のホスト名が使用されます。
experimental-{}試験機能は、 Boolean の true を使用して一度に、またはキー/値のペアを使用して個々に有効にできます。試験機能に関する詳細は、サポートまでお問合せください。
plugins-trueビルトインプラグインを使用して、外部ライブラリの自動インスツルメンテーションを有効にするかどうか。
clientTokenDD_CLIENT_TOKENnullブラウザーのトレーシング用クライアントトークン。Datadog の Integrations -> APIs で生成できます。
logLevelDD_TRACE_LOG_LEVELdebugデバッグロギングが有効な場合に使用する、トレーサーの最小ログレベル用ストリング (例: error, debug)。

Agent ホスト名の変更

アプリケーションレベルのトレーサーを設定し、以下のカスタム Agent ホスト名にトレースを送信します。

Nodejs racing Module が自動的に検索し環境変数の DD_AGENT_HOSTDD_TRACE_AGENT_PORT で初期化します。

DD_AGENT_HOST=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> ノードサーバー

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

DD_TRACE_AGENT_URL=unix:<SOCKET_PATH>ノードサーバー

互換性

Node 8 以降がこのライブラリのサポート対象です。8.x や 10.x など、偶数バージョンのみが公式なサポート対象です。9.x や 11.x などの奇数バージョンは動作しますが、公式なサポート対象ではありません。

Node 4 または Node 6 のバージョンは、dd-trace-js トレーサーのバージョン 0.13 でサポートされています。このバージョンは 2020 年 4 月 30 日までサポートされますが、今後新機能は追加されません。

: グローバルポリシーでは、Datadog JS トレーサーはバージョンリリース後発売終了まで 1 年間 Node をサポートします (バグの修正のみ)。

インテグレーション

APM は、プラグインシステムを使用することで追加設定なしで使用できる装置を多くの一般的なフレームワークやライブラリ向けに提供しています。一覧にないモジュールのサポートをご希望の場合は、サポートにお問い合わせになり、ご希望をお伝えください。

プラグインの切り替え方法と構成方法の詳細については、API ドキュメントをご確認ください。

Web フレームワークの互換性

モジュールバージョンサポートの種類Notes
connect2 以降完全対応
express4 以降完全対応Sails、Loopback、その他に対応
fastify1 以降完全対応
graphql0.10 以降完全対応Apollo Server および express-graphql に対応
gRPC>=1.13完全対応
hapi2 以降完全対応
koa2 以降完全対応
paperplane2.3 以降完全対応serverless-mode では非対応
restify3 以降完全対応

ネイティブモジュールの互換性

モジュールサポートの種類
dns完全対応
fs完全対応
http完全対応
https完全対応
net完全対応

データストアの互換性

モジュールバージョンサポートの種類Notes
cassandra-driver3 以降完全対応
couchbase2.4.2 以降完全対応
elasticsearch10 以降完全対応バージョン 5 以降の @elastic/elasticsearch に対応
ioredis2 以降完全対応
knex0.8 以降完全対応このインテグレーションはコンテキストの伝搬のみが目的
memcached2.2 以降完全対応
mongodb-core2 以降完全対応Mongoose に対応
mysql2 以降完全対応
mysql21 以降完全対応
pg4 以降完全対応pg と共に使用した場合 pg-native に対応
redis0.12 以降完全対応
tedious1 以降完全対応mssql および sequelize 用の SQL Server ドライバー

ワーカーの互換性

モジュールバージョンサポートの種類Notes
amqp103 以降完全対応AMQP 1.0 ブローカー (ActiveMQ、Apache Qpid など) に対応
amqplib0.5 以降完全対応AMQP 0.9 ブローカー (RabbitMQ、Apache Qpid など) に対応
generic-pool2 以降完全対応
kafka-node間もなく対応
rhea1 以降完全対応

Promise ライブラリの互換性

モジュールバージョンサポートの種類
bluebird2 以降完全対応
promise7 以降完全対応
promise-js0.0.3 以降完全対応
q1 以降完全対応
when3 以降完全対応

ロガーの互換性

モジュールバージョンサポートの種類
bunyan1 以降完全対応
paperplane2.3.2 以降完全対応
pino2 以降完全対応
winston1 以降完全対応

その他の参考資料