Python アプリケーションのビジネスパラメーターの抽出 - Cloud Monitor

Application Real-Time Monitoring Service (ARMS) は、Python アプリケーションの呼び出しトレースからビジネスパラメーターを非侵入型で抽出できます。ARMS コンソールで抽出ルールを設定することで、アプリケーションコードを変更することなく、HTTP リクエストおよびレスポンスから指定されたパラメーターをスパン属性に書き込むことができます。抽出された属性は、根本原因の特定、リクエスト情報の追跡、および一致するスパンでのカスタムエラーマーキングのトリガーに役立ちます。

前提条件

Python アプリケーションに ARMS Python エージェントがインストールされていること。
Python エージェントのバージョンが 3.1.0 以降であること。

サポート範囲

次の表に、Python バージョンでサポートされているパラメーター抽出タイプとソースを示します。

パラメーター抽出タイプ	パラメーターソース	サポートされているフレームワーク	説明
HTTP サーバーリクエスト	ヘッダー、クエリパラメーター、Cookie、ボディ	Flask、Django、FastAPI	ボディは JSON フォーマットである必要があります。詳細については、「よくある質問」をご参照ください。
HTTP サーバーレスポンス	ヘッダー、ボディ、Cookie	Flask、Django、FastAPI	ボディは JSON フォーマットである必要があります。Cookie ソースはリクエスト側の Cookie を読み取ります。
HTTP クライアントリクエスト	ヘッダー、クエリパラメーター	requests、httpx、aiohttp、urllib3	クライアントはボディまたは Cookie ソースをサポートしていません。
HTTP クライアントレスポンス	ヘッダー	requests、httpx、aiohttp、urllib3	-

必要なパラメーターソースがサポート範囲にない場合は、OpenTelemetry SDK を使用してカスタムイベントトラッキングを追加し、ビジネスパラメーターを属性としてスパンに書き込んでください。

設定ページへのアクセス

ARMS コンソールにログインします。
左側のナビゲーションウィンドウで、[アプリケーションモニタリング] > [アプリケーションリスト] を選択します。トップメニューバーで対象のリージョンを選択し、対象の Python アプリケーションの名前をクリックします。
左側のナビゲーションウィンドウで アプリケーションの設定 をクリックし、次に ビジネスパラメータ抽出ルール タブをクリックします。

設定ページには 2 つのセクションがあります：

ビジネスパラメータ抽出ルール：ビジネスパラメーター抽出ルールの作成、表示、変更を行います。ARMS エージェントはルールの変更を動的に検出し、有効になっているすべてのルールに基づいてビジネスパラメーターを抽出します。
カスタムエラーの設定：抽出されたビジネスパラメーター値に一致するカスタムエラールールを設定します。一致が見つかった場合、対応するスパンはエラーとしてマークされます。

抽出ルールの作成

ビジネスパラメータ抽出ルール セクションで、次の手順を実行します。

新規ルールの作成 をクリックします。
ルール名と属性名を入力します。
パラメーター抽出タイプを選択し、アクティブなインターフェイスを設定して、ルールのインターフェイス範囲を指定します。
パラメーター抽出ルールセクションで、パラメーターソースを追加し、パラメーター処理ステップを設定します。複数のパラメーターソースと処理ステップを設定できます。複数のソースがパラメーターを抽出できる場合、最初にリストされているソースがより高い優先度を持ちます。
ルールを有効にするかどうかを設定し、[保存] をクリックします。

重要

初めて抽出ルールを作成する場合、この機能を有効にするにはアプリケーションを再起動する必要があります。その後のルールの追加や変更では、再起動は不要です。ルールはエージェントのホットコンフィグレーション更新を通じて動的に配信され、1〜2 分以内に有効になります。

ルールが作成され有効になると、リアルタイムで ARMS Python エージェントに配信されます。抽出されたビジネスパラメーターは、対応する呼び出しトレースのスパンの属性に記録されます。トレース分析ページでパラメーターをフィルターおよびクエリできます。属性名にはデフォルトで biz. プレフィックスが付きます。重複する属性名は許可されません。

ルールの設定

パラメーター	説明
ルール名	ルールの人間が判読可能な名前。
属性名	抽出された値のスパン属性名。名前はデフォルトで `biz.` で始まり、複数の単語が続きます。各単語には、文字、数字、ハイフン (-)、アンダースコア (_) のみを含めることができます。単語はピリオド (.) で区切る必要があります。最大 10 単語まで許可されます。
パラメーター抽出タイプ	抽出するパラメーターのタイプ (HTTP サーバーリクエスト/レスポンス、HTTP クライアントリクエスト/レスポンス)。
アクティブなインターフェイス	ルールのインターフェイス範囲。エージェントは、このルールに一致するインターフェイスからのみパラメーターを抽出します。詳細については、「アクティブなインターフェイスのマッチング方法」をご参照ください。
パラメーター抽出ルール	パラメーターのソースと処理メソッド。複数のパラメーターソースと抽出ステップを設定できます。複数のソースがパラメーターを抽出できる場合、最初にリストされているソースがより高い優先度を持ちます。
パラメーターソース	パラメーターの実際のソース (ヘッダー、クエリパラメーター、Cookie、またはボディ)。
パラメーター処理ステップ	パラメーターソースを解析し、最終的な値を抽出するための一連の処理ステップ。複数のステップを追加できます。前のステップの出力が次のステップの入力になります。処理ステップが追加されない場合、抽出された値はソースオブジェクトの JSON テキストになります。
有効化	ルールを有効にするかどうかを指定します。

パラメーター処理メソッド

次の表に、Python バージョンでサポートされているパラメーター処理メソッドを示します。

処理メソッド	入力	出力	説明
JsonPath	JSON 文字列または JSON オブジェクト	文字列	ドット表記の JsonPath 文をサポートします。複数の値が一致する場合、最初の値が使用されます。例：`$.data.code`。
正規表現	文字列	文字列	名前付きグループを持つ正規表現をサポートします。抽出する部分文字列は、`res` という名前のグループに対応します。完全一致セマンティクスが使用されます (正規表現は入力全体に一致する必要があり、部分文字列検索ではありません)。例：`.from:(?<res>[a-z]+).`。

アクティブなインターフェイスのマッチング方法

マッチングターゲットはスパン名で、フォーマットは リクエストメソッドルート です。例：POST /api/order または GET /api/user/{id}。次の点にご注意ください：

「次と等しい /api/order」 は一致しません。代わりに 「次と等しい POST /api/order」 として設定してください。
または、後方一致 /api/order を使用します。
あるいは、正規表現 .*/api/order を使用します (正規表現も完全一致セマンティクスを使用します)。

値の処理

切り捨て：抽出された値が最大長制限 (デフォルトで 100 文字) を超える場合、... を付けて切り捨てられます。より長いボディフィールドを抽出するには、抽出値の長さ制限を増やしてください。
複数値のマージ：同じヘッダーまたはクエリパラメーター名に対して複数の値が存在する場合、それらは [a,b,c] のフォーマットの文字列にマージされます。
非機密化 — 非機密化が有効な場合、抽出された値は *** に置き換えられます。
Cookie：同じ名前の Cookie が複数ある場合、最後の値が使用されます。レスポンスフェーズの Cookie ソースは、リクエスト側の Cookie を読み取ります。

設定の検証

パラメーター抽出ルールを設定した後、(最初のルールでアプリケーションの再起動が必要な場合を除き) すぐに有効になります。抽出が機能していることを確認するには、次の手順を実行します。

新しいルールの属性名を見つけます。たとえば、属性名を orderCode に設定した場合、完全な属性名は biz.orderCode です。
トレース分析ページで、attributes.<属性名> (例：attributes.biz.orderCode) のフォーマットで属性名をクエリ条件として追加し、関連するスパンをフィルターします。
トレースをクリックし、スパン属性パネルを確認します。biz.orderCode 属性が期待される抽出値とともに表示されていれば、抽出ルールは有効になっています。

ルールの管理

ルールの有効化または無効化：対象のルールの右側にある [有効化] スイッチを切り替えます。
ルールの編集または削除：対象のルールの右側にある [編集] または [削除] をクリックします。
一括削除：削除する抽出ルールを選択し、[一括削除] をクリックします。
一括コピー：コピーする抽出ルールを選択し、[他のアプリケーションに一括コピー] をクリックします。ダイアログボックスで、ルールを他のすべてのアプリケーションにコピーするか、指定したアプリケーションにコピーするかを選択します。
- 一括コピーが有効になるまで 1〜2 分かかります。
- パラメーター抽出ルールのみがコピーされます。関連するカスタムエラールールは、ターゲットアプリケーションにはコピーされません。
- ターゲットアプリケーションに同じ属性名のルールが既に存在する場合、そのルールはコピーされません。

よくある質問

パラメーター抽出が失敗する原因

パラメーター抽出タイプまたはソースがサポート範囲にありません (例：クライアントのボディまたは Cookie ソース)。「サポート範囲」を参照して、現在のフレームワークとソースがサポートされているか確認してください。
アクティブなインターフェイスのマッチングルールが誤って設定されています。マッチングターゲットは、リクエストメソッドルート のフォーマットのスパン名です。「次と等しい /api/order」 のようなルールは一致しません。「アクティブなインターフェイスのマッチング方法」をご参照ください。
パラメーター処理ステップの構文が正しくないか、入力タイプが処理メソッドの要件と一致していません：
- 正規表現には res という名前の名前付きグループが含まれている必要があり、完全一致セマンティクスを使用します。部分文字列を一致させるには、両側に .* を追加します。
- JsonPath の入力は、JSON オブジェクトまたは JSON テキストである必要があります。プレーンな文字列 (例：ヘッダー値 abc) に対して JsonPath を実行しても結果は生成されません。
Python エージェントのバージョンが 3.1.0 より前で、ビジネスパラメーター抽出をサポートしていません。
最初のルールを作成した後にアプリケーションが再起動されていません。

ボディ抽出が失敗する原因

アプリケーション自身のリクエストまたはレスポンスボディの読み取りに影響を与えないように、エージェントはボディを読み取る前に受け入れチェックを実行します。次のいずれかの条件が満たされない場合、ボディソースは完全にスキップされます (解析前に切り捨てられることはありません)：

Content-Type が JSON ではない：application/json または +json で終わるメディアタイプのみがサポートされます。text/plain、application/x-www-form-urlencoded、multipart/form-data、およびバイナリタイプなどは抽出されません。
Content-Length がないか、制限を超えている：リクエストヘッダーに Content-Length が含まれていない場合 (例：チャンク転送エンコーディング)、またはボディ長が上限 (デフォルトで 64 KB) を超える場合、ボディ全体がスキップされます。
ボディが有効な UTF-8 エンコードの JSON ではない：デコードまたは JSON 解析に失敗した場合、ボディはスキップされます。
ストリーミングレスポンス：Flask のストリーミングまたは direct_passthrough レスポンス、Django の StreamingHttpResponse、および FastAPI/Starlette の StreamingResponse (SSE を含む) では、レスポンスボディは抽出されません。

以下は、フレームワーク固有のシナリオです：

FastAPI：リクエストボディは、アプリケーションが実際にそれを読み取った場合にのみ表示されます。つまり、エンドポイントがボディパラメーター (Pydantic モデルや Body() など) を宣言しているか、コードが await request.body() または await request.json() を呼び出した場合です。エンドポイントがリクエストボディを読み取らない場合、エージェントはリクエストストリームを能動的に消費せず、ボディは抽出できません。
Django：アプリケーションが最初に request.read() を使用してリクエストストリームを消費した場合 (RawPostDataException をトリガー)、またはボディが Django の DATA_UPLOAD_MAX_MEMORY_SIZE 制限を超えた場合 (RequestDataTooBig をトリガー)、ボディは抽出できません。request.body を介した通常の読み取りは影響を受けません (Django はボディをキャッシュするため、アプリケーションは引き続き正常に読み取ることができます)。
Flask：エージェントは request.get_data(cache=True) を使用してリクエストボディを読み取り、キャッシュします。アプリケーションはその後も正常にボディを読み取ることができ、追加の制限はありません。

抽出された値が期待と一致しない場合

値が ... で終わる：値が抽出値の長さ制限 (デフォルトで 100 文字) を超え、切り捨てられました。長さ制限を増やしてください。
値が***の場合、このルールまたはグローバルで秘匿化が有効になっています。
値が [a,b] のフォーマットである：同じヘッダーまたはクエリパラメーターに対して複数の値が存在し、マージされました。
JsonPath が複数のノードに一致する場合、最初の結果のみが返されます。
複数のルールが同じ属性名に書き込む場合、後から適用されたルールが前のルールを上書きします。

クエリパラメーターソースを使用して、フォームエンコードされたリクエストボディからフォームフィールドを抽出できますか？

いいえ。リクエストの Content-Type が application/x-www-form-urlencoded の場合、エージェントがフレームワークのフォーム解析をトリガーし、アプリケーション自身のリクエストボディの読み取りに影響を与えるのを防ぐため、クエリパラメーターソースは完全にスキップされます。このようなパラメーターの場合は、代わりに URL クエリ文字列またはヘッダーを介して渡すか、次の質問で説明するようにカスタムイベントトラッキングを追加してください。

Python バージョンでサポートされていないビジネスパラメーターソースを抽出するにはどうすればよいですか？

Python アプリケーション用の OpenTelemetry SDK を使用してカスタムイベントトラッキングを追加し、ビジネスパラメーターを属性としてスパンに書き込みます。