Application Real-Time Monitoring Service:Java アプリケーションのビジネスパラメーター抽出

パラメーター抽出ルール

抽出するパラメーターを含むソースと抽出方法を指定します。複数のパラメーターソースと処理ステップに対応しています。複数のソースからパラメーターを抽出する場合、定義した順序でステップが実行されます。詳細については、「抽出ルールの例」をご参照ください。

• [パラメーターソース]：パラメーターを抽出するソースです。Header、Cookie、または Parameter を選択した場合は、初期抽出のキーを入力します。Body または Message を選択した場合、パラメーターはボディまたはメッセージ全体から抽出されます。

• [パラメーター処理ステップを追加]：1 つ以上のソースからパラメーター値を解析するステップを定義します。各ステップの出力は、次のステップの入力になります。ステップが指定されていない場合は、ソースの未加工の JSON テキストが使用されます。詳細については、「パラメーター抽出ステップ」をご参照ください。次の抽出方法がサポートされています。

  方法	説明	例
  OGNL	入力は Java オブジェクトである必要があります。ドット記法を使用した OGNL 式をサポートします。	#this.data.getCode()
  JsonPath	入力は JSON 文字列である必要があります。ドット記法を使用した JsonPath 式をサポートします。	$.data.code
  Regex	入力は文字列である必要があります。名前付きキャプチャグループを使用し、抽出する部分文字列は res という名前のキャプチャグループに対応している必要があります。	.*from:(?<res>[a-z]+).*

カスタムエラーコードルールの作成

1. [エラー設定のカスタマイズ] セクションで、[カスタムエラーコード] スイッチをオンにします。

2. [一致ルールを追加] をクリックします。

3. 抽出ルールを選択し、フィルター条件を設定します。

   [カスタムエラーコード] スイッチをオンにした後、biz.resp.body 属性の値が 200 より大きい場合、および biz.exception 属性の値が 0 より大きい場合にスパンがエラーとしてマークされるように、一致ルールを追加します。

4. [保存] をクリックします。アプリケーションの再起動は不要で、ルールは 1～2 分以内に有効になります。

カスタムエラーコードルールの検証

ルールを設定した後、[トレースエクスプローラー] ページで、ルールの条件に一致する失敗したスパンを確認してください。

1. ルールで使用される属性名と条件を確認します。

2. [トレースエクスプローラー] ページで、失敗したスパンを絞り込みます。

   [トレースエクスプローラー] ページで、左側のクイックフィルター領域を使用して、ステータスがエラーのスパンをフィルターします。結果のクエリ条件は serviceName="arms-custom-extraction-demoextracted" AND statusCode IN (2, 3) AND spanName="/api/v1/http_server/body" です。この例では、クエリは期間が 0 ms でエラーステータスの 3,642 件のエラーコールを返します。

3. トレースをクリックして、属性値がルール条件に一致するかどうかを確認します。 次の例では、biz.resp.body 属性値は 670 で、エラーマッチングルールで指定されたしきい値である 499 を超えています。

4. [概要] ページで、エラー数がエラーダッシュボードに正しく反映されていることを確認します。

   

OGNL

Object-Graph Navigation Language (OGNL) は、Java オブジェクトのプロパティを読み取り、設定します。@ResponseBody または @RequestBody アノテーションが付与されたオブジェクトからフィールドを抽出するために使用します。結果は文字列に変換されます。抽出された値が Java オブジェクトの場合、後続のステップで抽出できるよう、JSON 文字列にシリアル化されます。

@RestController
@RequestMapping("/components/api/v1/mall")
public class MallController {
  @RequestMapping("/product")
  @ResponseBody
  public ResponseBody product(@RequestBody RequestBody req) {
    // ビジネスコード
  }

  static class RequestBody {
    String requestId;
    Map<String, String> queryParam;

    public String getQueryJsonStr() {
      return JSON.toJsonString(queryParam);
    }
  }

  static class ResponseBody {
    int code;
    boolean success;
    String message;
  }
}

RequestBody からrequestIdフィールドを抽出

ResponseBody からcodeフィールドを抽出

getter メソッドを呼び出しgetQueryJsonStr() の結果を抽出します。

JsonPath

JsonPath 式は、JSON 文字列からプロパティを抽出します。

{
  "code": 200,
  "message": "Query success.",
  "success": true,
  "data": {
    "name": "John",
    "age": 21
  }
}

JSON データからdata.ageを抽出

Regex

正規表現は、文字列内の文字の組み合わせに一致します。抽出結果を指定するには、res という名前のキャプチャグループを使用します。

https://test.aliyun.com/v2/workitem#requestId=0c978f115b6f7&cityCode=34&env=online

URL からcityCodeの値を抽出

複数ステップの抽出

この例では、OGNL、JsonPath、および Regex を連鎖させて、レスポンスボディからネストされた値を抽出します。

次のクラスには、レスポンスボディオブジェクトが含まれています。

class DemoResponse {
    int code = 200;
    boolean success = true;
    String message = "text content";
    String extraInfo = "{\"id\": 15, \"cityInfo\": \"from:hangzhou,to:beijing\"}";

    public String getExtraInfo() {
        return this.extraInfo;
    }
}

目的: extraInfo のサブフィールド cityInfo から、"from" で示される都市名を抽出します。

ARMS エージェントは、次の手順で抽出処理を実行します。

1. レスポンスボディから DemoResponse オブジェクトを取得します。

2. extraInfo フィールドを取得するには、#this.getExtraInfo() (OGNL) を実行します。

3. $.cityInfo (JsonPath) を実行して extraInfo を JSON として解析し、cityInfo サブフィールドを取得します。

4. ^from:(?<res>[a-z]+).* (正規表現) を実行すると、res という名前のキャプチャグループがマッチし、hangzhou が返されます。

5. span の属性値として hangzhou を記述します。

ステップの仕組み

抽出ステップは、ソースデータから値を取得して解析します。ステップはパイプラインを形成し、各ステップの出力は次のステップの入力として使用されます。

各メソッドには、特定の入力タイプが必要です。入力が一致しない場合、パイプラインは停止し、現在の結果を最終値として記録します。

構文の制限

ARMS は、セキュリティを維持するために、オープンソースの OGNL、JsonPath、および正規表現よりも厳格な構文制限を課しています。

パフォーマンスに関する考慮事項

抽出ステップには、シリアル化とデシリアル化、Java リフレクション、および正規表現処理が含まれます。これらは、抽出パイプラインで最もリソースを消費する操作です。レイテンシ要件が厳しいインターフェースの場合、次の代替案を検討してください。

• ビジネスコードで HTTP ヘッダーにパラメーターを書き込みます (セキュリティコンプライアンス上、許可される場合)。

• OpenTelemetry SDK for Java を使用して、属性をスパンに直接書き込みます。詳細については、「OpenTelemetry SDK for Java を使用してアプリケーションにカスタム計装コードを追加する」をご参照ください。

パラメーター抽出が失敗した場合はどうすればよいですか?

原因は、パラメーターソースによって異なります。

• Body：Spring MVC が使用されているか、クラスに @Controller アノテーションが付与されているか、メソッドに @RequestBody または @ResponseBody アノテーションが付与されているかを確認してください。

• レスポンス Cookie：Tomcat v7.0.4-9.x または Undertow v1.4.0.Final+ を使用していることを確認してください。それ以外の場合は、代わりにリクエスト Cookie を使用してください。

例外抽出の範囲は何ですか?

ARMS Agent for Java は、スパンの外側でスローされたカスタム例外のみをキャプチャします。スパン内の主要な呼び出しメソッドから例外を抽出し、エラーとしてマークするには、呼び出しメソッドを計装します。詳細については、「監視用のカスタムメソッドを追加する」をご参照ください。

Spring MVC アノテーションを抽出ルールにマッピングするにはどうすればよいですか?

サポートされていないパラメータータイプを抽出するにはどうすればよいですか?

OpenTelemetry SDK を使用してアプリケーションを計装し、パラメーターをスパン属性として直接書き込みます。詳細については、「OpenTelemetry SDK for Java を使用してトレースにカスタム計装コードを追加する」をご参照ください。

抽出は、RequestBodyAdvice および ResponseBodyAdvice を使用した Body オブジェクトをサポートしていますか?

はい。ARMS エージェントは、ユーザー定義の BodyAdvice が実行された後、Spring の組み込み BodyAdvice の前にパラメーターを抽出します。