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

概要

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

Join the Beta!

ダイナミックインスツルメンテーションはベータ版です。

はじめに

前提条件

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

Datadog Agent 7.44.0 以降がサービスと一緒にインストールされていること。
その Agent でリモート構成が有効になっていること。
Java アプリケーションの場合、トレーシングライブラリ dd-trace-java 1.15.0 以降。
Python アプリケーションの場合、トレーシングライブラリ dd-trace-py 1.15.0 以降。
.NET アプリケーションの場合、トレーシングライブラリ dd-trace-dotnet 2.32.0 以降。
統合サービスタグ付けタグ service、env、version がデプロイメントに適用されていること。
オプションで、サービスにソースコードインテグレーションが設定されていること。
ダイナミックインスツルメンテーションページにアクセスするには、ダイナミックインスツルメンテーションの読み取り構成 (debugger_read) 権限が必要です。
インスツルメンテーションを作成または変更するには、ダイナミックインスツルメンテーションの書き込み構成 (debugger_write) 権限が必要です。ロールの詳細とユーザーにロールを割り当てる方法については、ロールベースアクセス制御を参照してください。

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

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

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

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

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

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

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

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

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

プローブの使用

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

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

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

プローブの作成

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

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

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

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

プロファイリング : プロファイラーのフレームグラフで、フレームのコンテキストメニューから Instrument this frame with a probe を選択すると、メソッドのプローブを作成できます。

エラー追跡 : スタックトレース上で、スタックフレームにカーソルを合わせ、** Instrument** をクリックします。これにより、プローブ作成フォームに問題のコンテキストが入力されます。

ログプローブの作成

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

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

ログプローブで Capture method parameters and local variables (メソッドのパラメーターとローカル変数のキャプチャ) を有効にすると、以下のデバッグデータがキャプチャされ、ログイベントに追加されます。

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

実行コンテキストのキャプチャはパフォーマンスに影響するため、デフォルトでは、指定した環境とバージョンに一致するサービスの 1 つのインスタンスでのみ有効になっています。この設定を有効にしたプローブは、1 秒間に 1 回のヒットにレートが制限されます。

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

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

警告: キャプチャされたデータには、個人データ、パスワード、AWS キーなどの秘密をはじめとした機密情報が含まれる可能性があります。

この情報が Datadog に送信されないようにするには、以下のいずれかのオプションを実行してください。

正規表現のパターンに基づいて機密データを検出して除外するように、機密データスキャナーを構成する。
Capture method parameters and local variables (メソッドのパラメーターとローカル変数のキャプチャ) オプションを無効にし、ログメッセージテンプレートに含めたい変数を明示的に選択する。これを行うことにより、具体的に特定した変数に関連するデータのみがログプローブに含まれるようになります。

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

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

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

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

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

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

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

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

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

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