自動計装
自動計装 (Auto-instrumentation) とは、Datadog の SDK (トレーシングライブラリ) を読み込んだ時点で、対応するフレームワークやライブラリの呼び出しが自動でスパンになる仕組みのこと。コードを書き換えずにトレースが取れる一方、独自の処理の区間は自分で計装する。
概要
自動計装は、Datadog APM の SDK がアプリケーションに読み込まれた時点で既定で働き、対応するフレームワークやライブラリの呼び出しをスパンとして記録する仕組みです。SDK が知っている呼び出しは自動で取れますが、独自のビジネスロジックの区間や業務上の属性は自分でスパンを足します。Single Step Instrumentation は、この SDK の組み込みまで Agent 側から自動で行う方式です。気にするのは、トレースは出ているのに自前の処理が見えないときと、コードに触らず計装を広げたいときです。
SDK を読み込んだ瞬間から始まる計装
自動計装 (Auto-instrumentation) は、Datadog APM の SDK (トレーシングライブラリ) を読み込んだ時点で働き、対応するフレームワークやライブラリの呼び出しを スパン にする仕組みです。公式ドキュメントは、SDK が読み込まれるとスパンは既定で自動生成され、多くの利用者にはこれで十分な可視性が得られる、と説明しています (2026 年 9 月時点・出典: Application Instrumentation)。計装 (instrumentation) はトレースを取るためのコードを加える作業を指し、自動計装はその大部分を SDK 側が肩代わりします。対応言語と導入の流れは APM の解説に譲ります。
どこまで自動で、どこから自分で書くか
境目は「SDK が知っている呼び出しか、自分で書いた処理か」です。対応する呼び出しは自動でスパンになりますが、独自のビジネスロジックの区間やアプリケーション固有の属性は SDK には分かりません。そこを見たいときの手段は 2 つあります。Dynamic Instrumentation は Datadog の画面で計装ルールを定義し、コード変更も再デプロイもせずに実行中のプロセスへカスタムスパンを足します。コードベースのカスタム計装はコードにスパンを直接書く方法で、複雑な計装ロジックや恒久的に残したいスパンに向きます (2026 年 9 月時点・出典: Application Instrumentation)。3 つは重ねて使えます。自動計装のスパンの名前や属性は SDK が決めるので、業務の言葉で区間を名付けたいという要求が出た時点がカスタム計装の出番です。
Single Step Instrumentation - SDK の組み込みまで自動にする
自動計装は SDK がプロセスに読み込まれていることが前提です。その組み込み自体を自動にするのが Single Step Instrumentation (SSI) です (2026 年 9 月時点・出典: Single Step APM Instrumentation)。APM Instrumentation を有効にして Datadog Agent を導入すると、Agent が対応するプロセスに SDK を読み込ませます。中で働くのは injector という共有ライブラリで、プロセスに載る経路が環境ごとに違います。
| 環境 | 経路 |
|---|---|
| Linux ホスト | LD_PRELOAD (/etc/ld.so.preload) で、動的リンクされる全プロセスに読み込まれる |
| Docker | Datadog 提供の runc シムが既定のコンテナランタイムを置き換え、コンテナ内のプロセスに LD_PRELOAD を設定する |
| Kubernetes | Datadog Admission Controller が mutating webhook として Pod の spec を書き換え、init コンテナで injector と SDK を配る |
| Windows | Datadog のカーネルドライバーが、新規プロセスに injector の DLL を読み込む |
Kubernetes の経路は Cluster Agent 側の部品が担うため、SSI を広げる前に Cluster Agent の稼働を見ておくと迷いが減ります。
injector はプロセスの中で何を判断するか
injector がプロセスのメモリに載った後の動きは、どの環境でも同じ順で進みます。
- アプリケーションのランタイムを検出する (Python / Node.js / PHP / Java / .NET / Ruby / NGINX)
- 計装対象かを判定する (既定で除外されるプロセスがあり、ルールで許可と拒否も定義できる)
- 環境変数やコマンドライン引数を書き換えて、ランタイムに合う SDK を読み込む (Java は
JAVA_TOOL_OPTIONSに-javaagent、Python はPYTHONPATH) - 状態を示すテレメトリを送る
- 失敗した場合や対応ランタイムでない場合は、計装なしでアプリケーションを動かし続ける
最後の一点が実務では重要です。計装が効かなくてもアプリケーションは止まらないので、「トレースが出ない」は障害ではなく設定の問題として静かに現れます。無効化にも癖があり、injector は SDK が環境変数を評価する前に動くため、DD_TRACE_ENABLED=false では SSI を止められません。止めるには各プラットフォームの手順で SSI 自体を無効にします (2026 年 9 月時点・出典: Understanding Injector Behavior)。
カスタム計装が残っていると SSI は自動で止まる
SSI を使う前提として、公式は既存のカスタム計装コードを取り除いて再起動することを求めています。カスタム計装が検出されると SSI は自動で無効になるためです (2026 年 9 月時点・出典: Single Step APM Instrumentation)。ベンダー中立を選ぶなら OpenTelemetry で計装して Datadog へ送る経路もあり、受け口は OpenTelemetry の解説 で扱っています。自動計装という語を意識するのは 2 つの場面です。1 つは、サービス の画面にスパンは並ぶのに自前の処理の区間だけ見えないときで、自動計装の範囲外なのでカスタムスパンを足す判断になります。2 つ目は トレース が全く出ないときで、対応ランタイムか、除外ルールに当たっていないか、カスタム計装の残骸で SSI が止まっていないか、の順に見ます。