ダイナミックインスツルメンテーション

概要

ダイナミックインスツルメンテーションを使用すると、再起動することなく、サードパーティのライブラリを含むアプリケーションのコードの任意の場所で、実行中の本番システムにインスツルメンテーションを追加することができます。Datadog の UI から、ログ、メトリクス、スパン、および対応するタグ付けのテレメトリーを追加または変更することができます。ダイナミックインスツルメンテーションはオーバーヘッドが少なく、システムに副作用を与えません。

ダイナミックインスツルメンテーションの最新のユーザーエクスペリエンス改善を試したい場合は、オートコンプリートと検索の公開ベータ版への参加をご検討ください。

はじめに

前提条件

ダイナミックインスツルメンテーションには、以下のものが必要です。

Datadog Agent 7.45.0 以降がサービスと一緒にインストールされていること。
その Agent でリモート構成が有効になっていること。
Java アプリケーションの場合、トレーシングライブラリ dd-trace-java 1.34.0 以降。
Python アプリケーションの場合、トレーシングライブラリ dd-trace-py 2.2.0 以降。
.NET アプリケーションの場合、トレーシングライブラリ dd-trace-dotnet 2.54.0 以降。
PHP アプリケーションの場合、トレーシングライブラリ dd-trace-php 1.4.0 以降。
統合サービスタグ付けのタグ service、env、version がデプロイメントに適用されていること。
オートコンプリートと検索 (オープンベータ) が有効になっていること (推奨事項)。
サービスにソースコードインテグレーションが設定されていること (推奨事項)。
ダイナミックインスツルメンテーションページにアクセスするには、ダイナミックインスツルメンテーションの読み取り構成 (debugger_read) 権限が必要です。
インスツルメンテーションを作成または変更するには、Dynamic Instrumentation Write Configuration (debugger_write) 権限が必要です。
Capture method parameters and local variables (メソッドパラメーターとローカル変数をキャプチャする) オプションを使用するには、Dynamic Instrumentation Capture Variables (debugger_capture_variables) 権限が必要です。

ロールの詳細と、ユーザーにロールを割り当てる方法については、ロールベースのアクセス制御を参照してください。

ログのインデックスを作成する

ダイナミックインスツルメンテーションは、Datadog に送信され、通常のアプリケーションログと共に表示される「ダイナミックログ」を作成します。

除外フィルターを使用する場合は、ダイナミックインスツルメンテーションのログがフィルターされないようにします。

ログインデックスを作成し、サンプリングなしで希望する保存期間まで構成します。
source:dd_debugger タグに一致するようにフィルターを設定します。すべてのダイナミックインスツルメンテーションログはこのソースを持ちます。
新しいインデックスが、そのタグに一致する他のフィルターよりも優先されることを確認してください。最初に一致したものが優先されるためです。

ダイナミックインスツルメンテーションを有効にする

サービスでダイナミックインスツルメンテーションを有効にするには、アプリ内設定ページにアクセスしてください。

より詳細な説明については、以下のランタイムを選択してください。

制限

ダイナミックインスツルメンテーションは、Azure App Services やサーバーレス環境にはまだ対応していません。
サポートは Python、Java、.NET、PHP で構築されたアプリケーションに限定されます。

ダイナミックインスツルメンテーションを見る

ダイナミックインスツルメンテーションは、アプリケーションがランタイムに何をしているかを理解するのに役立ちます。ダイナミックインスツルメンテーションのプローブを追加することで、コードを変更したり再デプロイすることなく、アプリケーションから追加のデータをエクスポートすることができます。

プローブの使用

プローブを使用すると、プログラムの実行を停止することなく、コード内の特定のポイントからデータを収集できます。

プローブの使用は、コードの変更、デプロイ、サービスの再起動を行うことなく、実行中のアプリケーションに動的なログ、メトリクス、スパンを追加して観測可能性を強化することと考えてください。ユーザーエクスペリエンスを妨げたり、長時間のデプロイを必要とすることなく、即座にデータを収集することができます。

開発者としては、プローブを「ブレークしないブレークポイント」と考えることもできます。従来のデバッグでは、ブレークポイントとはプログラムの実行を停止するポイントのことで、開発者はその時点でのプログラムの状態を検査することができます。しかし、実際の本番環境では、プログラムの実行を停止することは現実的ではありませんし、不可能です。プローブは、非侵入的な方法で本番環境の変数状態を検査できるようにすることで、このギャップを埋めます。

プローブの作成

どのプローブタイプでも、初期設定は同じです。

ダイナミックインスツルメンテーションのページへ移動します。
右上の Create Probe をクリックするか、サービス上で 3 つの点のメニューをクリックし、Add the probe for this service を選択します。
あらかじめ入力されていない場合は、サービス、ランタイム、環境、バージョンを選択します。
ソースコードで、クラスとメソッド、またはソースファイルと行のいずれかを選択して、プローブを設定する場所を指定します。オートコンプリートと検索の公開ベータ版に参加している場合は、オートコンプリートがクラスまたはメソッドを選択するための候補を表示します。

各プローブタイプの具体的な作成手順については、以下の各プローブタイプを参照してください。

または、これらの他のコンテキストからプローブを作成することもできます。

プロファイリング: プロファイラーのフレームグラフで、フレームのコンテキストメニューから Instrument this frame with a probe を選択すると、メソッドのプローブを作成できます。
エラー追跡: スタックトレース上で、スタックフレームにカーソルを合わせ、** Instrument** をクリックします。これにより、プローブ作成フォームに問題のコンテキストが入力されます。

ログプローブの作成

ログプローブは、実行時にログを出力します。

ログプローブを作成するには

プローブタイプとして Log を選択します。
一般的なプローブのセットアップを完了します (サービス、環境、バージョン、プローブの場所を選択します)。
ログメッセージテンプレートを定義します。ダイナミックインスツルメンテーション式言語を使用して、実行コンテキストから値を参照することができます。
オプションで、プローブからの追加データキャプチャを有効にします。(ベータ版)
オプションで、ダイナミックインスツルメンテーション式言語を使用して、条件を定義します。式が真と評価された場合にログが出力されます。

ログプローブは、指定された環境とバージョンに一致するすべてのサービスインスタンスでデフォルトで有効になっています。また、サービスの各インスタンスで 1 秒間に最大 5000 回まで実行されるようレート制限されています。

すべてのログプローブにログメッセージテンプレートを設定する必要があります。テンプレートは、中括弧内に式を埋め込むことをサポートします。例: User {user.id} purchased {count(products)} products

式言語を使用してログプローブに条件を設定することもできます。式はブール値で評価される必要があります。式が true の場合、プローブは実行され、式が false の場合、データはキャプチャも出力もされません。

ベータ版: ログプローブで Capture method parameters and local variables (メソッドパラメーターとローカル変数をキャプチャする) を有効にすると、すべての実行コンテキストがログイベントに追加されます。

メソッド引数、ローカル変数*、フィールド*。以下のデフォルトの制限があります。
- 3 段階の深さのリファレンスをフォローします (UI で構成可能)。
- コレクション内の最初の 100 項目。
- 文字列値で最初の 255 文字。
- オブジェクト内の 20 個のフィールド。静的フィールドは収集されません。
スタックトレースを呼び出します。
捕捉される場合と捕捉されない場合の例外。

この設定を有効にしたプローブは、1 秒間に 1 回のヒットにレート制限されます。

警告: キャプチャされたデータには、個人情報、パスワード、シークレット (例: AWS キー) などの機密情報が含まれている可能性があります。

この情報が適切にマスキングされるようにするには

Datadog ダイナミックインスツルメンテーションは、機密情報をマスキングするために、いくつかのテクニックを採用しています。デフォルトのメカニズムや、ニーズに合わせて拡張する方法の詳細については、機密データスクラビングを参照してください。
Capture method parameters and local variables オプションをオフにし、ログメッセージテンプレートに含める変数を明示的に選択します。こうすることで、ログプローブには、明確に指定した変数に関連するデータのみが含まれるようになり、意図しない機密データ漏えいのリスクを低減できます。
Datadog アカウントの管理者で、他のユーザーが Capture method parameters and local variables オプションを使用できないようにしたい場合は、Dynamic Instrumentation Capture Variables (debugger_capture_variables) 権限を取り消すことができます。

また、このデータをログに記録する必要があるが、Datadog 製品でアクセスできることに関連するリスクを軽減したい場合は、source:dd_debugger に Restriction クエリを設定することで、組織内のどのユーザーがキャプチャデータを表示できるかを制限できます。

メトリクスプローブの作成

メトリクスプローブは、実行時にメトリクスを出力します。

メトリクスプローブを作成するには

プローブタイプとして Metric を選択します。
一般的なプローブのセットアップを完了します (サービス、環境、バージョン、プローブの場所を選択します)。
メトリクスの名前を指定します。この名前には dynamic.instrumentation.metric.probe. がプレフィックスとして付きます。
メトリクスタイプ (カウント、ゲージ、ヒストグラム) を選択します。
ダイナミックインスツルメンテーション式言語を使用してメトリクスの値を選択します。メソッドパラメーター、ローカル変数、クラスフィールド、または数値を返す式など、実行コンテキストから任意の数値を使用できます。カウントメトリクスの場合、これはオプションで、省略するとすべての呼び出しでカウントが 1 つ増加されます。

メトリクスプローブは、構成された環境とバージョンに一致するすべてのサービスインスタンスで自動的に有効になります。メトリクスプローブはレート制限を受けず、メソッドまたは行が呼び出されるたびに実行されます。

ダイナミックインスツルメンテーションメトリクスプローブは、以下のメトリクスタイプをサポートしています。

カウント: 指定されたメソッドや行が何回実行されたかを数えます。カウントを増加させるために変数の値を使用するためにメトリクス式と組み合わせることができます。
ゲージ: 変数の最後の値に基づいてゲージを生成します。このメトリクスはメトリクス式を必要とします。
ヒストグラム: 変数の統計的分布を生成します。このメトリクスはメトリクス式を必要とします。