Java アプリケーションのフィルタリング設定

オンラインで編集

Java アプリケーションのトレースデータ量を削減するには、属性を基に特定のスパンスをフィルタリングできます。 この機能は、データ取り込みコストの最適化を支援し、アプリケーション監視のニーズに最も関連性の高いトレースに焦点を当てます。

Java アプリケーションでは、 HTTP および JDBC のスパンに対して、属性ベースのフィルタリングが利用可能です。 トレースから取り込まれるデータの削減に関する詳細については、 『 Instana 』の「データ取り込みの最適化」 を参照してください。

フィルター・オプション

オンラインで編集

Java のアプリケーショントレースは、以下の方法でフィルタリングできます：

  • メソッドベースのフィルタリング ： DynamoDB,、 Redis、および Kafka からのスパンをフィルタリングするには、 「エンドポイントの無視」 を参照してください。 この機能を使用すると、メソッド名（例： GET、 consume、など query）やエンドポイント（例： Kafka トピック名など）に基づいてトレースを除外することができます。
  • スパン属性に基づくフィルタリング ： HTTP および JDBC のスパンをフィルタリングするには、スパン属性に基づくフィルタリング手法を使用します。 この機能では、URL、SQL文、 HTTP メソッドなど、複数のスパン属性に基づいた高度なフィルタリング機能を提供します。 このアプローチは、柔軟なパターンマッチング（strict, startswith, endswith, および contains）をサポートしており、1つのルール内で複数の属性を組み合わせることが可能です。

スパン属性に基づくフィルタリングの詳細な設定手順については、以下のセクションを参照してください。

参照トレースの例

オンラインで編集

以下の例は、フィルタリングを一切適用していない完全なトレースを示しており、このドキュメント全体を通じて参照として使用されます：

Span属性に基づくフィルタリング

オンラインで編集

Java アプリケーションのSpan属性に基づくフィルタリングは、agent configuration.yaml ファイルを通じてのみ設定可能です。 環境変数およびシステムプロパティは、フィルタリング構成ではサポートされていません。

注記： 設定変更は、初期設定後にアプリケーションの再起動を必要とせず、動的に適用されます。

フィルタ設定

オンラインで編集

URL、SQL文、または HTTP メソッドなどの属性に基づいて、 HTTP および JDBC のスパンを除外するフィルタリングルールを設定できます。

フィルタリングルールは、エージェント configuration.yaml ファイル（instanaAgentDir/etc/instana/configuration.yaml）の com.instana.tracing.filter セクションで定義されます。この設定では、 YAML 構造体を使用して、スパン属性に基づいたフィルタリングルールを定義します。

フィルタールールを定義するには、以下の設定を使用してください：

com.instana.tracing:
  filter:
    deactivate: <boolean>
    exclude:
      - name: <string>
        attributes:
          - key: <string>
            values: [<string>, ...]
            match_type: <string>
重要: ポリシー exclude 内で複数のフィルタールールを定義できます。 各ルールには複数の属性が設定可能であり、ルールを適用するにはそれらの属性がすべて一致する必要があります。
フィールド 必須 説明
filter 必須 すべてのフィルタリングルールのルートノード。
deactivate オプション 設定済みのフィルタ規則を削除せずにフィルタリングを無効化する機能トグル。 に設定すると true、フィルタリングは無効になります。 デフォルト値は （フィルタリングは false 有効のまま）です。
exclude 必須 トレースからスパンを除外するための除外ルールを保持するポリシー。 現在、ポリシー exclude のみがサポートされています。
name 必須 フィルタルールを説明する人間が理解できる名前。
attributes 必須 ルールが適用されるために全て一致しなければならないspan属性のリスト。
key 必須 span属性のキー
values 必須 span属性に一致 keyさせる値のリスト。 属性が一致するとは、その属性のいずれかが values 一致することを指す。 ワイルドカードとして '*' 使用し、指定された属性キーの任意の値に一致します（値に関係なく属性の有無に基づくフィルタリングに有用です）。
match_type オプション span values 属性のマッチング方法を定義します。 有効な値: strict (デフォルト)、 startswith、 endswith、および contains。

抑制行動

フィルタリングルールによってスパンが除外される場合、 HTTP と JDBC では抑制動作が異なります：
  • HTTP フィルタリング : 抑制がデフォルトで適用されます。 HTTP スパンが除外されると、すべての子スパンと下流トレースが自動的に抑制されます。 除外された HTTP リクエストによってトリガーされるデータベース呼び出し、外部サービス呼び出し、その他の操作に対しては、スパンが生成されません。
  • JDBC フィルタリング : 抑制は適用されません。 JDBC スパンが除外された場合でも、子スパンおよびトレース内の後続の操作は引き続きキャプチャされます。
重要: この suppression 設定パラメータは設定できません。 抑制動作はスパンタイプに基づいて自動的に決定されます。

ワイルドカードの使用方法

特定のspan属性の値に一致させるには、フィールド values 内で "*" ワイルドカードを使用できます。 これは、属性の値に関係なく、属性の有無に基づいてスパンをフィルタリングしたい場合に便利です。 ワイルドカードは、 HTTP と JDBC の両方のフィルタリングに使用できます。

例: エラー属性を持つすべてのスパン（エラーメッセージの内容に関わらず）を除外するには、次の設定を使用します:

com.instana.tracing:
  filter:
    exclude:
      - name: exclude all HTTP error spans
        attributes:
          - key: http.error
            values: ["*"]
            match_type: strict
      - name: exclude all JDBC error spans
        attributes:
          - key: jdbc.error
            values: ["*"]
            match_type: strict

ルールの実行順序

フィルタールールは、設定に記述されている順序で評価されます。 スパンがフィルタルールに一致した場合、そのルールが適用され、そのスパンに対して以降のルールは評価されません。 ポリシー exclude 内で最初に一致するルールがフィルタリング動作を決定します。

重要： 正しいフィルタリングが適用されるよう、ルールを最も具体的なものから最も一般的なものの順に並べてください。

例:

com.instana.tracing:
  filter:
    exclude:
      - name: exclude specific internal health endpoint
        attributes:
          - key: http.url
            values: [/api/internal/health]
            match_type: strict
      - name: exclude all health endpoints
        attributes:
          - key: http.url
            values: [/health]
            match_type: contains

この例では、スパンが に一致する場合 /api/internal/health、最初のルールが適用されます。 スパンが に一致するが /health に一致しない場合 /api/internal/health、2番目のルールが適用される。 順序が重要なのは、最初の一致ルールが使用されるためです。

HTTP エンドポイントフィルタリング

オンラインで編集

HTTP のエンドポイントフィルタリングを使用すると、 URL、メソッド、ヘッダーなどの属性に基づいて HTTP スパンを除外できます。 この機能は、以下の HTTP フレームワークでサポートされています：

  • サーブレット : Java サーブレットを使用するアプリケーション API
  • Spring Web : Spring MVC および Spring Boot を使用するアプリケーション
重要: HTTP スパンが除外された場合、デフォルトで抑制が適用されます。 すべての子スパンおよび下流トレースは自動的に抑制されます。これには、除外された HTTP リクエストによってトリガーされたデータベース呼び出し、外部サービス呼び出し、その他の操作も含まれます。

HTTP エンドポイントフィルタリングのSpan属性

以下のspan属性を使用して、 HTTP エンドポイントをフィルタリングできます。 「UI表示名」列には、スパンの詳細を表示する際に Instana のUIで各属性がどのように表示されるかが示されます。

重要： 以下の表に表示されているUIの表示名は英語です。 Instana のUIを他の言語で使用している場合、これらのラベルは言語設定に従って翻訳されます。 ただし、（フィルタリング設定で使用される）span属性のキーは、すべての言語で共通です。 UIの表示名は、この表に示されているマッピングと異なる場合があります。
Span属性 UI表示名 説明 値の例 フィルタリングサポート
http.url URL URL またはパス /api/users はい
http.method メソッド HTTP メソッド GET はい
http.status 状況コード HTTP 応答ステータスコード 200 限定*
http.host ホスト ホスト名とポート localhost:8080 はい
http.path 要求パス 要求パス /api/users はい
http.path_tpl パス・テンプレート ルートテンプレートまたはパターン /api/users/{id} はい
http.params パラメーター HTTP 照会ストリング action=edit&id=5 はい
http.error エラー エラー・メッセージ エラーの説明 限定*
http.header.<header-name> ヘッダー HTTP リクエストヘッダー header-value はい
http.header.<response-header-name> ヘッダー HTTP 応答ヘッダー header-value 限定*
* フィルタリング機能の制限 : HTTP リクエスト完了後にのみ利用可能なスパン属性（例: http.status およびレスポンスヘッダー http.header.<response-header-name>）は、フィルタリング機能が制限されています。 これらの属性に基づくフィルタ規則はスパンを除外できますが、子スパンや下流トレースの抑制を強制することはできません。抑制の決定が行われる時点では属性値が不明であるためです。

UI表示のバリエーション

フィルタリング設定においてspan属性のキーは一定ですが、 Instana UI上の実際の表示値はコンテキストによって異なる場合があります：

  • http.statusステータスコードに人間が理解できる説明文を付加して表示します（例：、 200 – OK 404 – Not Found、 など 500 – Internal Server Error）。 フィルタリング時には、数値のステータスコード値のみを使用してください。
  • http.errorエラー値が空でない文字列の場合にのみ、UIに表示されます。 さらに、この属性は、 Java Tracerの機密データ設定で定義された機密データを含む場合、編集される可能性があります。 空または編集済みのエラーはUIに表示されません。
  • http.paramsクエリ文字列が空または空白の場合、UIは空の値ではなく を <no query parameters> 表示します。 フィルタリング時には、実際のクエリ文字列の値と照合するか、空の文字列を使用してください。
  • http.urlUIに表示されるのは、と異なる場合 http.pathのみです。 両方の値が同一の場合、冗長性を避けるためパスのみが表示されます。
重要： これらの表示の違いは、フィルタリングの動作には影響しません。 フィルタリングルールは常に、UIに表示されるフォーマット済みの表示値ではなく、バックエンドに保存されている生のスパン属性値に対して照合されます。

HTTP エンドポイントフィルタリング設定の例

以下の例は、 HTTP エンドポイントのフィルタリング設定を示しています：

com.instana.tracing:
  filter:
    exclude:
      - name: exclude HTTP health check endpoints
        attributes:
          - key: http.url
            values: [/health, /ping, /ready]
            match_type: endswith
      - name: exclude HTTP OPTIONS requests
        attributes:
          - key: http.method
            values: [OPTIONS]
            match_type: strict

前の例では、フィルタリング構成により以下のルールが適用されます：

  • 以下の条件を満たす HTTP スパンを除外します： URL が /health, /ping,またはで /ready終わるもの。 子スパンと下流トレースは自動的に抑制されます。
  • HTTP メソッドを持つ OPTIONSHTTP スパンを除外します。 子スパンと下流トレースは自動的に抑制されます。

以下の例は、抑制を伴う HTTP フィルタリングの効果を示しています。 このトレースをフィルタリングなしの完全なトレース（図1）と比較すると、 HTTPauthor=test2 の呼び出しがパラメータと共にフィルタリングされ、それらの子スパンもすべて除外されていることがわかります：

JDBC スパンフィルタリング

オンラインで編集

JDBC のスパンフィルタリング機能では、SQL文、接続文字列、エラーメッセージなどの属性に基づいてデータベーススパンを除外できます。

重要：HTTP によるフィルタリングとは異なり、 JDBC によるフィルタリングでは、下流のトレースは抑制されません。 JDBC スパンが除外された場合でも、子スパンおよびトレース内の後続の操作は引き続きキャプチャされます。

JDBC のspan属性によるフィルタリング

以下のspan属性を使用して、 JDBC のスパンをフィルタリングできます。 「UI表示名」列は、スパンの詳細を表示する際に Instana のUIで各属性がどのように表示されるかを示します。

注： 以下の表に表示されるUI表示名は英語です。 Instana UI を別の言語で使用している場合、これらのラベルは言語設定に従って翻訳されますが、span 属性キー（フィルタリング設定で使用される）は全言語で共通です。
Span属性 UI表示名 説明 値の例
jdbc.connection 接続 JDBC 接続ストリング jdbc:mysql://localhost:3306/mydb
jdbc.statement 記述 SQL ステートメント SELECT * FROM users
jdbc.error エラー エラー・メッセージ SQLエラーの説明

UI表示のバリエーション

HTTP スパンと同様に、 JDBC スパン属性は、 Instana UI でバリエーションが表示される場合があります：

  • jdbc.errorエラー値が空でない文字列の場合にのみ、UIに表示されます。 この属性は、 Java Tracerの機密データ設定で定義された機密データを含む場合、編集される可能性があります。 空または編集済みのエラーはUIに表示されません。
  • jdbc.statementSQL文は、表示目的で一定の長さを超えた場合にUI上で切り詰められる場合がありますが、フィルタリング評価には完全な文が使用されます。
重要： これらの表示の違いは、フィルタリングの動作には影響しません。 フィルタリングルールは常に、バックエンドに保存されている生のスパン属性値に対して照合されます。

JDBC の例：スパンフィルタリング設定

以下の例は、 JDBC のスパンフィルタリング設定を示しています：

com.instana.tracing:
  filter:
    exclude:
      - name: exclude JDBC spans for audit tables
        attributes:
          - key: jdbc.statement
            values: [audit_log, session_data]
            match_type: contains
      - name: exclude SELECT queries on MySQL database
        attributes:
          - key: jdbc.statement
            values: [SELECT]
            match_type: startswith
          - key: jdbc.connection
            values: [mysql]
            match_type: contains
      - name: exclude all JDBC error spans
        attributes:
          - key: jdbc.error
            values: ['*']
            match_type: strict

前の例では、フィルタリング構成により以下のルールが適用されます：

  • JDBC スパンで、SQL文に または audit_log を含むものは session_data除外します。
  • JDBC スパンで、SQL文が``で始まるもの SELECT 、および接続文字列に``が含まれるものは除外 mysqlされます。
  • エラーメッセージを含むすべての JDBC スパンを除外する（ '*' ワイルドカードを使用して任意のエラー値に一致させるもの）。

以下の例は、 JDBC フィルタリングの効果を示しています。 このトレースをフィルタリングなしの完全なトレース（図1）と比較すると、 JDBCselect book0_.id as id1_0_, book0_.author as author2_0_, book0_.title as title3_0_ from book book0_ where book0_.author=? ステートメントがフィルタリングされ、トレースから2つのスパンが削除されていることがわかります：

HTTP と JDBC の組み合わせフィルタリング例

オンラインで編集

以下の例は、 HTTP と JDBC の両方のフィルタリングルールを同時に設定する方法を示しています：

com.instana.tracing:
  filter:
    exclude:
      - name: exclude HTTP health check endpoints
        attributes:
          - key: http.url
            values: [/health, /status, /metrics]
            match_type: strict
      - name: exclude JDBC queries for temporary tables
        attributes:
          - key: jdbc.statement
            values: [temp_, tmp_]
            match_type: contains

この例では、

  • HTTP ヘルスチェックのエンドポイントに一致するスパンは自動抑制により除外されます（子スパンおよび下流トレースは抑制されます）。
  • JDBC 一時テーブルのスパンは抑制なしで除外されます（子スパンおよび下流トレースは引き続きキャプチャされます）。

フィルタリングの限界

オンラインで編集
  • ポリシーサポート ：現在、以下の exclude ポリシーのみをサポートしています。 ポリシー include はまだ利用できません。
  • 抑制行動 ：
    • HTTP フィルタリングはデフォルトで抑制を適用します（子スパンと下流トレースは抑制されます）。
    • 構成 suppression パラメータは設定できません。
  • 特定の HTTP 属性に対する限定的な抑制サポート : HTTP リクエスト完了後にのみ判明するスパン属性（例: http.statusや http.header.<response-header-name> などの http.errorレスポンスヘッダー）に基づくフィルタールールは、子スパンおよび下流トレースの抑制を強制できません。 これらの属性は、親の HTTP スパンをトレースから除外するために依然として使用できます。 ただし、子スパンや下流の操作は引き続きキャプチャされるため、UI上で親スパンが欠落した状態でスパンが表示される可能性があります。
  • フィルタールールは、 http.params span属性は、以下の場合には機能しない可能性があります。 values Java Tracer によって HTTP URL から削除される可能性のある秘密が含まれています。
  • フィルタリング設定の変更は、初期設定後にアプリケーションの再起動を必要とせず、動的に適用されます。