Application Real-Time Monitoring Service:Java アプリケーションのカスタム設定

前提条件

ご利用のアプリケーションに ARMS エージェントがインストールされていること。

操作手順

1. ARMS コンソールにログインします。左側のナビゲーションウィンドウで、アプリケーションモニタリング > アプリケーションリスト を選択します。

3. 上部のナビゲーションバーで、アプリケーション設定 > カスタム構成 を選択します。

4. カスタム構成パラメーターを設定し、[保存] をクリックします。

サンプリング設定

[サンプリング設定] セクションでは、トレースのサンプリングポリシー、サンプリングレート、およびフルサンプリングインターフェイスの特性を設定できます。また、低トラフィックサンプリングを有効化または無効化することもできます。詳細については、「トレースサンプリングモードを選択する (エージェント v3.2.8 以降)」をご参照ください。

エージェントスイッチ設定

[エージェントスイッチ設定] セクションでは、アプリケーションモニタリングの開始または停止、および個々のプラグインスイッチの切り替えができます。

スレッド分析設定

[スレッド分析設定] セクションでは、スレッド分析のメインスイッチを有効または無効にできます。

アプリケーションログの関連付け設定

[アプリケーションログの関連付け設定] セクションでは、アプリケーションのログソース情報を設定し、TraceId と SpanId を自動的に含めることができます。詳細については、「ログ分析」をご参照ください。

• TraceId と SpanId を自動的に挿入：有効にすると、ログ設定ファイルを変更することなく、TraceId と SpanId がログに自動的に挿入されます。

  効果：

  次の図に示すように、log4j、log4j2、および logback は、ログ設定ファイルを変更することなく、ログに TraceId と SpanId を自動的に出力します。

  

• TraceId をログ MDC に追加：デフォルトでは、エージェント v4.x 以降は org.slf4j.MDC.get(“EagleEye-TraceID”) を使用した TraceId の取得をサポートしていません。このメソッドを引き続き使用する必要がある場合は、このスイッチを有効にできます。

URL 収束設定

[URL 収束設定] セクションでは、URL 収束を有効化または無効化し、収束のしきい値と収束ルールを設定できます。 URL 収束は、一連の類似した URL をグループ化し、単一の項目として表示します。 たとえば、/service/demo/ で始まる一連の URL はまとめて表示できます。 収束のしきい値は、収束をトリガーするために必要な URL の最小数を指定します。 たとえば、しきい値が 100 の場合、少なくとも 100 個の URL が正規表現に一致する場合にのみ URL は収束されます。 詳細については、「ARMS の収束メカニズム」をご参照ください。

Arthas モニタリング

[Arthas モニタリング] セクションでは、Arthas 診断機能を有効または無効にし、それが有効になる IP アドレスを指定できます。 詳細については、「Arthas 診断」をご参照ください。

継続的なプロファイリング設定

[継続的なプロファイリング設定] セクションでは、メインスイッチ、CPU ホットスポット、メモリホットスポット、コードホットスポットの各機能を有効または無効にできます。また、これらの設定を適用する IP アドレスまたは CIDR ブロックを指定することもできます。詳細については、「Java アプリケーションの継続的なプロファイリング」をご参照ください。

情報のマスキング設定

[情報非機密化設定] セクションでは、データ収集中にエージェントが JVM システムパラメーター、K8s YAML、メソッド入力パラメーター、Arthas 環境変数、システム変数などのコンテンツを非機密化するための、非機密化ルールを設定できます。 非機密化ルールの要素はカンマで区切られ、各要素は大文字と小文字を区別しない正規表現を表します。 たとえば、ルール password は、正規表現 .*password.* に相当します。

エージェントがデータを収集する際、指定された式に基づいてデータキーをフィルタリングします。キーが式に一致する場合、それは機密情報と見なされ、その値はマスキングされます。次の図に示すように、マスキングルールが licenseKey の場合、キー -Darms.licenseKey の値はマスキングされます。

次の図は、IP アドレスのマスキングを有効にした場合の効果を示しています。

API 呼び出し設定

[インターフェイス呼び出し設定] セクションでは、低速呼び出しのしきい値、例外ホワイトリスト、HTTP ステータスコードのホワイトリスト、および無効なインターフェイス呼び出しのフィルタリングポリシーを設定できます。

• 低速呼び出しのしきい値：デフォルト値は 500 ms です。インターフェイス呼び出しの応答時間がこのしきい値を超えると、低速呼び出しとしてマークされます。

• HTTP ステータスコードのホワイトリスト：

  デフォルトでは、400 以上の HTTP ステータスコードはエラーと見なされます。特定のステータスコードがエラーとして分類されないようにするには、それらをホワイトリストに追加します。

  この設定は、アプリケーションモニタリングでサポートされている HTTP フレームワークにのみ影響します。

  影響を受けるデータ：HTTP サーバーおよびクライアントのエラーカウントメトリック (arms_http_requests_error_count、arms_http_client_requests_error_count、arms_app_requests_error_count) およびスパンのステータス。

  影響を受ける機能: [概要]、[提供サービス]、および [依存関係] タブのエラー数、ならびに [トレースエクスプローラー] ページのスパンステータスとエラー数アラート。

  フォーマット：単一のステータスコード、またはカンマ (,) で区切られた複数のステータスコードを入力します。ワイルドカードマッチングはサポートされていません。

  例：403,502

  デフォルト：なし

• 無効なインターフェイス呼び出しのフィルタリング：

  [提供サービス] タブから特定の呼び出しを非表示にする場合は、非表示にするインターフェイスの名前を入力できます。エージェントは、これらのインターフェイスの可観測性データのレポートを停止します。

  説明

  • Java エージェントの 4.2.0 より前のバージョンでは、この機能は提供サービスに表示されるインターフェイスに対してのみ有効です。

  • Java エージェント v4.2.0 以降では、この機能は任意の LocalRootSpan に適用されます。

  影響を受けるデータ：一致するインターフェイスのすべてのメトリックとスパンは無視されます。

  影響を受ける機能: [概要]、[提供サービス]、および[依存関係]タブにおける該当インターフェイスの全メトリック、ならびに[トレースエクスプローラー]ページにおける該当インターフェイスのスパン数、呼び出しボリューム、エラー数、および低速呼び出しアラート。

  フォーマット：文字列または AntPath 式を使用して、無効なインターフェイスの完全名を照合します。複数のルールはカンマ (,) で区切ります。デフォルトの AntPath 式は下位互換性のためのものであり、削除しないでください。既存のルールの後に新しいルールを追加してください。

  例：/api/test/*,/api/playground/create

  デフォルト：/**/*.jpg,/**/*.png,/**/*.js,/**/*.jpeg,/**/*.pdf,/**/*.xlsx,/**/*.txt,/**/*.docs,/**/*.gif,/**/*.csv

• 上流インターフェイス名を記録および上流アプリケーション名を記録：

  目的：このインターフェイスを呼び出した上流のアプリケーションとインターフェイスをインターフェイスメトリックに記録するかどうかを制御します。これは、[提供サービス] タブの上流および下流データの可用性に影響します。アプリケーションに多数の上流アプリケーションがある場合、この情報を記録すると、レポートされるメトリックの量が大幅に増加し、コストが高くなる可能性があります。

  効果：図に示すように、上流のアプリケーションとインターフェイスの記録を無効にすると、対応するデータはゼロに低下します。

  

• 元のステータスコードを記録：

  目的：HTTP インターフェイス関連のメトリックに元の応答コードを記録します。

  効果：

  

• インターフェイス呼び出しにおける HTTP メソッド名の記録: このスイッチを有効にすると、[インターフェイス呼び出し] ページの展開されたインターフェイス名に HTTP リクエストメソッドが含まれます。たとえば、/api/v1/use/{userId} は GET /api/v1/use/{userId} になります。

データベース呼び出し設定

[データベース呼び出し設定] セクションでは、低速 SQL しきい値と収集される SQL ステートメントの最大長を設定できます。また、SQL ステートメントに変数バインディング値と定数値を表示するかどうか、および MySQL クエリの戻り値のサイズを記録するかどうかも設定できます。

• SQL に変数バインディング値を表示：PreparedStatement にバインドされた変数値を取得します。この変更は、アプリケーションを再起動しなくてもすぐに有効になります。

  エージェントは PreparedStatement からバインドされた変数の値を記録し、対応するデータベース呼び出しスパンの属性に保存します。属性キーは db.bindvalue で、値はカンマで区切られた変数値のリストです。この変更は、アプリケーションを再起動しなくてもすぐに有効になります。

  • この設定は、ARMS がサポートするすべての JDBC ベースのフレームワークでサポートされています。

  • サポートされているデータベース変数タイプ：Boolean、Byte、Short、Int、Long、Float、Double、BigDecimal、および Date。

  • このスイッチを有効にすると、SQL ステートメント内の変数の数に比例して追加のオーバーヘッドが発生します。公式ストレステストでは (変数が 1 つの場合)、このスイッチを有効にすると、CPU オーバーヘッドが 0.5% 未満増加し、メモリオーバーヘッドはごくわずかでした。

  次の図は、スイッチを有効にした場合の効果を示しています。

  

• SQL に定数値を表示：この設定は、追加の処理を行わずに SQL ステートメントを切り捨てるだけで、アプリケーションを再起動しなくても有効になります。異なる SQL ステートメントに異なる定数値が含まれている場合、高カーディナリティの SQL ステートメントが作成され、{ARMS_OTHERS} に集約される可能性があります。このオプションを有効にすることは推奨しません。

• 元の JDBC 接続文字列を記録：デフォルトでは、エージェントは限られた種類の JDBC 接続文字列しか解析できません。正しく解析できない接続文字列は UnknownEndpoint として記録されます。このスイッチを有効にすると、元の JDBC 接続文字列が記録されます。次の図に示すように、jdbc:h2:file のような接続文字列は以前は認識されず、UnknownEndpoint として記録されていました。このスイッチを有効にすると、接続文字列は正しく記録されます。

トレースコンテキスト伝播プロトコル設定

[トレースコンテキスト伝播プロトコルの設定項目] セクションでは、ニーズに合った トレースコンテキスト伝播プロトコル を選択できます。

デフォルトでは、ARMS エージェントは、リクエストヘッダーに特定のプロトコルヘッダーが含まれているかどうかに基づいて、トレースコンテキスト伝播プロトコルを選択します。詳細については、「ARMS トレースコンテキスト伝播プロトコルの選択ポリシー」をご参照ください。

このページでは、優先プロトコルを選択できます。プロトコルを選択して設定を保存すると、ARMS はそのプロトコルで定義されたリクエストヘッダーの検出を優先します。たとえば、次の設定では、ARMS エージェントは Jaeger、EagleEye、W3C、SkyWalking、Zipkin の順にプロトコルコンテキストヘッダーをチェックします。

特定のプロトコルの使用を強制することもできます。たとえば、次の設定では、呼び出しが到着すると、ARMS エージェントは Jaeger プロトコルで定義されたリクエストヘッダーのみを検出します。ヘッダーが見つからない場合、エージェントは他のプロトコルをチェックせずに、新しいトレースコンテキストを生成します。

トレースコンテキストの抽出および挿入戦略：デフォルトの動作は、上流リクエストからトレースコンテキストを抽出し、下流リクエストに挿入することです。この抽出および挿入の動作を設定できます。

目的：

これにより、次のユースケースに合わせて、優先または強制するトレースコンテキスト伝播プロトコルを選択できます。

• リクエストが複数のフォーマットのトレースコンテキストを保持しており、デフォルトの解析順序が要件を満たさない場合。優先するプロトコルを指定できます。たとえば、リクエストが W3C と Zipkin の両方のトレースコンテキストを保持している場合、ARMS はデフォルトで W3C コンテキストの解析を優先します。伝播プロトコルを Zipkin に設定して、代わりに Zipkin コンテキストの解析を優先させることができます。

• リクエストがトレースプロトコルヘッダーを保持しているが、既存のものを再利用する代わりに、別のプロトコルで新しいトレースコンテキストを生成したい場合。たとえば、リクエストが Zipkin トレースコンテキストを保持している場合、ARMS はデフォルトでそれを解析します。伝播プロトコルを W3C に設定し、伝播モードを「強制」に設定できます。これにより、ARMS は Zipkin コンテキストを無視し、W3C 仕様に基づいて新しいコンテキストを生成するように強制されます。伝播モードが「強制」に設定されていない場合、ARMS は W3C コンテキストの解析に失敗した場合でも Zipkin コンテキストの解析を試みることに注意してください。

効果：

設定後、トレース内の各 LocalRootSpan には、キーが trace.protocol.type で、現在のトレースに使用されているトレースプロトコルを示す値を持つ属性が含まれます。

メッセージキュー設定

[メッセージキュー設定] セクションでは、コンシューマー情報をカスタマイズできます。

• カスタム RabbitMQ コンシューマー：カスタムコンシューマーのクラス名、または匿名内部コンシューマーを含むクラスを設定することで、コンシューマーのトレースを表示できます。複数のコンシューマー名はカンマ (,) で区切ります。

• カスタム Kafka 消費メソッド：カスタム消費メソッドを定義することで、ネイティブ Kafka SDK を使用してメッセージが消費されるシナリオでトレースとメトリックデータを表示できます。

• Kafka メッセージでコンテキストを自動的に伝播：メッセージが送信されると、送信トレースと消費トレースを関連付けるために、いくつかのヘッダーが Kafka メッセージに自動的に追加されます。

エージェント収集設定

[エージェント収集設定] セクションでは、1 秒あたりに収集されるトレースの最大数、最大 QPS しきい値、およびエージェントのログレベルを設定できます。

• トレースの収集：トレースデータをレポートするかどうかを制御します。これはデフォルトで有効になっています。無効にすると、トレースデータはレポートされなくなります。

• 1 秒あたりの最大スパン数：エージェントが 1 秒あたりにレポートできるスパンの数。パフォーマンス上の理由から、実際に有効なしきい値は設定値から最大 5% ずれることがあります。この制限を超えるスパンはレポートされません。

• 最大 QPS しきい値：エージェントが 1 秒あたりに処理できるリクエストの数。パフォーマンス上の理由から、実際に有効なしきい値は設定値から最大 5% ずれることがあります。このしきい値を超えるリクエストは監視されず、スパンやメトリックが生成されず、TraceId ログ関連付け機能も機能しません。

• エントリポイントのない内部呼び出しを収集：ARMS では、HTTP サービス、RPC サービス、定期タスク、メッセージ消費がエントリポイントと見なされます。これらのエントリポイントのビジネスロジック内で発生するデータベース呼び出しや HTTP リクエストは、エントリポイントを持つ内部呼び出しと見なされます。逆に、JDK スレッドプールによって開始される定期的な HTTP 呼び出し、データベース呼び出し、NoSQL 呼び出し、メッセージ送信、RPC 呼び出しは、エントリポイントを持たない内部呼び出しと見なされます。エージェント v4.2.2 以降では、このタイプのデータをフィルタリングできます。たとえば、Lettuce フレームワークは、Redis サーバーとの健全な接続を維持するために定期的にコマンドを実行します。これらの呼び出しは、エントリポイントを持たない内部呼び出しです。次の図に示すように、このデータの収集を無効にすると、関連データは収集されなくなります。

  

• エージェントのログレベル：トラブルシューティングのためにエージェントのログレベルを調整します。

• エージェントログのレポート：エージェントが自身の運用ログを ARMS サーバーにレポートできるようにし、迅速なトラブルシューティングを可能にします。通常の状態では、1 分あたりにレポートされるログはごく少量です。

• HTTPS レポートを有効にする：有効にすると、エージェントは HTTPS を使用してデータをレポートします。

• デフォルトのメトリック収集フィルター：指定されたタイプのメトリックのレポートをフィルタリングします。次のオプションから複数のタイプを選択できます。

  • custom_entry：メソッドモニタリングのカスタムメトリック

  • http：HTTP サーバーメトリック

  • http_client：HTTP クライアントメトリック

  • rpc：RPC サーバーメトリック

  • rpc_client：RPC クライアントメトリック

  • sql：データベースアクセスメトリック

  • nosql：NoSQL サービスアクセスメトリック

  • cache：キャッシュサービスアクセスメトリック

  • producer：メッセージ送信メトリック

  • consumer：メッセージ消費メトリック

  • schedule：スケジューリングサービスメトリック

• カスタムメトリック収集設定：収集のために OpenTelemetry SDK によって定義されたメトリックを設定します。詳細については、「OpenTelemetry Java SDK を使用したメトリックのカスタマイズ」をご参照ください。

• 収集するバゲージ項目：ビジネスで バゲージを使用する場合、この設定は特定バゲージ項目をスパン属性に書き込み、特定のトレースの検索を容易にします。

高度な例外フィルタリング設定

[高度な例外フィルタリング設定] セクションでは、例外収集ルールを設定できます。

• プラグイン例外の収集：プラグイン例外を収集するかどうかを指定します。

• 類似の例外を区別するためのスタックの深さ：デフォルト値は 2 です。このスタックの深さは、類似タイプの例外を識別するために使用されます。この設定を変更すると、予期しない統計動作が発生する可能性があります。操作には十分ご注意ください。

• 例外フィルタリングホワイトリスト：

  [例外分析] タブから特定の例外を非表示にする場合は、カウント対象としない例外の完全修飾クラス名を入力することで、ページから非表示にできます。

  影響を受けるデータ：例外カウントメトリック (arms_exception_requests_count_raw、arms_exception_requests_seconds_raw) およびスパン内の例外情報。

  影響を受ける特徴: [例外分析] タブの対応する例外のメトリック。

  フォーマット：フィルタリングする例外を識別するために、完全修飾クラス名を使用します。複数の例外名はカンマ (,) で区切ります。

  例：java.lang.InterruptedException,java.lang.IndexOutOfBoundsException

  デフォルト：なし

• 親クラスによる例外のフィルタリング：有効にすると、例外が例外フィルタリングホワイトリストで設定された例外クラスのサブクラスである場合もフィルタリングされます。

  効果：フィルタリング基準を満たす例外は ARMS コンソールに表示されません。

• 例外メッセージフィルタリング：設定後、指定されたタイプの例外は、そのメッセージフィールドが設定された条件を満たす場合にもフィルタリングされます。

  • 例外名：フィルターを適用する例外を指定します。

  • メッセージ条件：例外メッセージの条件。startsWith、endsWith、または contains を指定できます。

  • メッセージキーワード：キーワード文字列。

  効果：フィルタリング基準を満たす例外は ARMS コンソールに表示されません。

プールモニタリング設定

[プールモニタリング設定] セクションでは、スレッドプールと接続プールの収集ルールを設定できます。

• スレッドプールと接続プールのモニタリング：Tomcat、Dubbo、HSF などのフレームワークのスレッドプールメトリックのモニタリングをサポートします。エージェントを最新バージョンにアップグレードする必要があります。

• スレッドプールのスレッド名パターンの抽出ポリシー：デフォルトでは、この機能はスレッドプール内の実行中のスレッドの名前にあるすべての数字を * に置き換えます。また、ポリシーを調整して、スレッド名の末尾の文字のみを * に置き換えることもできます。たとえば、アプリケーションが異なるポートでリッスンする複数の Dubbo プロバイダーを起動する場合、抽出されたスレッド名テンプレートが同一であるため、デフォルトのポリシーではこれらのプロバイダーのスレッドプールが単一のプールに集約されます。この場合、ポリシーを調整して 2 つのスレッドプールを区別できます。

  たとえば、一般的な Tomcat スレッドプールの場合、スレッド名はデフォルトで http-nio-*-exec-* です。調整後、スレッド名は http-nio-9099-exec-* になります。

  

• スレッドプールの使用シナリオによるフィルタリングおよびスレッドプール名パターンによるフィルタリング：これらの設定は、特定のスレッドプールの使用シナリオと名前パターンに基づいて、監視メトリックをフィルタリングします。

  説明

  この構成は、Java エージェント v4.2.0 以降でのみ有効です。

  • スレッドプールの使用シナリオ：スレッドプールが使用されるコンテキスト。サポートされているシナリオには、Tomcat、Vert.x、Undertow、Dubbo、Jetty、AliyunJavaAgent、および default があります。AliyunJavaAgent はエージェントが使用するスレッドプールを表し、default はその他の分類されていないスレッドプールを表します。

  • スレッドプール名パターン：スレッドプール内のスレッド名を処理して得られるパターン。たとえば、http-nio-*-exec-* は、実際のスレッド名の数字部分をアスタリスク (*) に置き換えて得られるパターンです。

  影響を受けるデータ：スレッドプールメトリック

  影響を受ける機能: スレッドプール監視タブ、およびスレッドプール監視メトリクスに基づいて設定されたアラート。

  フォーマット：

  • スレッドプールの使用シナリオによるフィルタリング：スレッドプールモニタリングタブに表示される使用シナリオを入力します。複数のシナリオはカンマ (,) で区切ります。

  • スレッドプール名パターンによるフィルタリング：スレッドプールモニタリングタブに表示されるスレッド名パターンを入力します。複数のパターンはカンマ (,) で区切ります。この機能は完全一致を使用し、ルールベースのマッチングはサポートしていません。

  例：

  • スレッドプールの使用シナリオによるフィルタリング：AliyunJavaAgent,Jetty

  • スレッドプール名パターンによるフィルタリング：Catalina-utility-*,DubboServerHandler-*-thread-*

  これは、AliyunJavaAgent シナリオではすべてのスレッドプールのデータがレポートされず、他のシナリオでもスレッドプール名が Catalina-utility-* に一致する場合はデータがレポートされないことを意味します。

  デフォルト：なし

スパン属性設定

• OpenTelemetry の規則に基づいて属性を記録：OpenTelemetry 仕様では、各プラグインタイプによって生成されるスパンに含めるべき属性が定義されています。レポートされるデータ量を削減するため、ARMS エージェントはデフォルトではこれらの属性を記録しません。必要に応じてこの設定を有効にできます。各フレームワークの追加属性については、「OpenTelemetry 仕様」をご参照ください。

  次の例は、HTTP サーバースパンを示しています。赤枠内の属性は、このスイッチを有効にした後に追加されます。

  

• スパンとアプリケーションタグの関連付け: この設定は、アプリケーション ページで設定したアプリケーションタグと関連付けるスパンをコントロールします。デフォルトでは、すべてのスパンにアプリケーションタグが含まれます。データ使用量を削減するには、アプリケーションタグをエントリースパンにのみアタッチすることを選択できます。エントリースパンは、通常、HTTP サーバー、RPC サーバー、メッセージキューコンシューマー、定期タスクなどのエントリーポイントからのスパンです。

  次の図は、test1:value1 のようなアプリケーションタグのペアをエントリスパンにアタッチした結果を示しています。

  

  エントリスパンの場合、対応するタグ属性を確認できます。

  

  エントリではないスパンの場合、属性には test1:value は含まれません。

  

詳細設定

[詳細設定] セクションでは、フィルタリングするインターフェイスやメソッドスタックの最大長などの設定を構成できます。

• 分位数統計：分位数統計を有効または無効にします。

• メソッドスタックの最大長：デフォルト値は 128、最大値は 400 です。

• トレース圧縮：for ループ内のような反復的な呼び出しを圧縮して、トレースを簡素化します。

• リクエストパラメーターの最大表示長：デフォルトの長さは 512 文字、最大長は 2048 文字です。

• 非同期コンテキスト伝播のためのパッケージ：非同期タスクを監視するために、非同期伝播のためのスキャンパッケージを追加します。このパッケージで Runnable、Callable、または Supplier インターフェイスの新しいオブジェクトが作成されると、システムは現在のスレッドのトレースコンテキストを自動的にキャプチャします。このコンテキストは、非同期スレッドが実行されるときに使用され、トレースが正しくリンクされることを保証します。

• HTTP レスポンスに TraceId を含める：有効にすると、この設定は HTTP レスポンスヘッダーに eagleeye-traceid フィールドを追加します。

• JVM GC トリガーの根本原因: 有効にすると、JVM ガベージコレクション (GC) トリガーの根本原因を表示できます。モニタリングの詳細は、[JVM モニタリング] ページで表示できます。詳細については、「GC 関連のメトリック」をご参照ください。

他のアプリケーションへの設定のコピー

同じ設定を他のアプリケーションに適用する必要がある場合は、設定をコピーできます。

グローバルデフォルト設定

現在の設定をグローバルデフォルト設定として保存できます。この設定は、新しく作成されたすべてのアプリケーションにデフォルトで適用されます。

1. ページの下部で、[現在のアプリ設定をグローバルデフォルト設定として保存] をクリックします。

2. [現在の設定は保存されていません] ダイアログボックスが表示された場合は、[OK] をクリックして現在のアプリケーションの設定を保存し、再度 [現在のアプリ設定をグローバルデフォルト設定として保存] をクリックします。

3. 表示されたダイアログボックスで、[確認] をクリックします。

よくある質問