次の方法で共有

テレメトリ プロセッサ (プレビュー) - Azure Monitor Application Insights for Java

  • [アーティクル]

Note

テレメトリ プロセッサ機能は、属性 セマンティック規則の試験的状態に起因してリリース間の下位互換性を保証できないため、プレビューとして指定されます。 ただし、この機能はテストされており、運用環境でサポートされています。

Application Insights Java 3.x では、テレメトリ データがエクスポートされる前にそのデータを処理することができます。

いくつかのユースケース:

  • 機密データをマスクする。
  • 条件付きでカスタム ディメンションを追加する。
  • スパン名を更新する。これは、Azure portal で同様のテレメトリを集計するために使用されます。
  • インジェスト コストを制御するために特定のスパン属性を削除する。
  • インジェスト コストを制御するために、いくつかのメトリックを除外する。

Note

インジェスト コストを制御するために特定の (全体の) スパンを削除しようとしている場合は、「サンプリング オーバーライド」参照してください。

用語

テレメトリ プロセッサについて学習する前に、"スパン" と "ログ" という用語を理解しておく必要があります。

スパンは、次のいずれかを表すテレメトリの種類です。

  • 着信要求。
  • 送信依存関係 (別のサービスへのリモート呼び出しなど)。
  • プロセス内の依存関係 (サービスのサブコンポーネントによって実行される操作など)。

ログは、次のものを表すテレメトリの種類です。

  • Log4j、Logback、java.util.logging から取り込まれるログ データ

テレメトリ プロセッサには、次のスパンまたはログのコンポーネントが重要です。

  • Name
  • 本文
  • 属性

スパン名は、Azure portal における要求と依存関係の主要な表示です。 スパン属性は、特定の要求または依存関係の、標準とカスタムの両方のプロパティを表します。

トレース メッセージまたは本文は、Azure portal でのログの主要な表示です。 ログ属性は、特定のログの標準とカスタムの両方のプロパティを表します。

テレメトリ プロセッサの種類

現在、4 種類のテレメトリ プロセッサがあります。

  • 属性プロセッサ
  • スパン プロセッサ
  • ログ プロセッサ
  • メトリック フィルター

属性プロセッサを使用すると、テレメトリ項目の属性 (span または log) を挿入、更新、削除、またはハッシュすることができます。 正規表現を使用して、既存の属性から 1 つ以上の新しい属性を抽出することもできます。

スパン プロセッサを使用すると、要求と依存関係のテレメトリ名を更新できます。 正規表現を使用して、スパン名から 1 つ以上の新しい属性を抽出することもできます。

ログ プロセッサを使用すると、ログのテレメトリ名を更新することができます。 正規表現を使用して、ログ名から 1 つ以上の新しい属性を抽出することもできます。

メトリック フィルターを使用すると、メトリックを除外してインジェスト コストの制御に役立てることができます。

Note

現在、テレメトリ プロセッサによって処理されるのは、文字列型の属性のみです。 ブール値または数値型の属性は処理されません。

作業の開始

開始するには、applicationinsights.json という名前の構成ファイルを作成します。 これを、applicationinsights-agent-*.jar と同じディレクトリに保存します。 次に示すテンプレートを使用します。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        ...
      },
      {
        "type": "attribute",
        ...
      },
      {
        "type": "span",
        ...
      },
      {
        "type": "log",
        ...
      },
      {
        "type": "metric-filter",
        ...
      }
    ]
  }
}

属性プロセッサ

属性プロセッサを使用すると、span または log の属性を変更できます。 span または log を含めたり除外したりする機能をサポートできます。 受け取ったアクションのリストが、構成ファイルで指定された順序で実行されます。 プロセッサでは、次のアクションがサポートされています。

  • insert
  • update
  • delete
  • hash
  • extract
  • mask

insert

insert アクションにより、key がまだ存在しないテレメトリ項目に新しい属性が挿入されます。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "value1",
        "action": "insert"
      }
    ]
  }
]

insert アクションには、次の設定が必要です。

  • key
  • value または fromAttribute のいずれか
  • action: insert

update

update アクションにより、key が既に存在するテレメトリ項目の属性が更新されます。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "value": "newValue",
        "action": "update"
      }
    ]
  }
]

update アクションには、次の設定が必要です。

  • key
  • value または fromAttribute のいずれか
  • action: update

delete

delete アクションにより、テレメトリ項目から属性が削除されます。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "delete"
      }
    ]
  }
]

delete アクションには、次の設定が必要です。

  • key
  • action: delete

hash

hash アクションでは、既存の属性値がハッシュ (SHA1) されます。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "action": "hash"
      }
    ]
  }
]

hash アクションには、次の設定が必要です。

  • key
  • action: hash

extract

注意

extract 機能は、バージョン 3.0.2 以降でのみ使用できます。

extract アクションでは、正規表現規則を使用して、入力キーから規則で指定したターゲット キーに、値が抽出されます。 ターゲット キーが既に存在する場合、extract アクションによってターゲット キーがオーバーライドされます。 このアクションは、既存の属性がソースである、スパン プロセッサの toAttributes 設定と同様に動作します。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attribute1",
        "pattern": "<regular pattern with named matchers>",
        "action": "extract"
      }
    ]
  }
]

extract アクションには、次の設定が必要です。

  • key
  • pattern
  • action: extract

mask

Note

mask 機能は、バージョン 3.2.5 以降でのみ使用できます。

mask アクションは、pattern と replace で指定された正規表現規則を使用して属性値をマスクします。

"processors": [
  {
    "type": "attribute",
    "actions": [
      {
        "key": "attributeName",
        "pattern": "<regular expression pattern>",
        "replace": "<replacement value>",
        "action": "mask"
      }
    ]
  }
]

mask アクションには、次の設定が必要です。

  • key
  • pattern
  • replace
  • action: mask

pattern には、?< と >: で挟むことで名前付きグループを含めることができます。 例: (?<userGroupName>[a-zA-Z.:\/]+)\d+? グループは (?<userGroupName>[a-zA-Z.:\/]+) であり、userGroupName はグループの名前です。 次に、${ と } の間に配置され、後ろにマスクが続く同じ名前付きグループを pattern に含めることができます。 (マスクが ** である例: ${userGroupName}**)。

マスクの例については、「テレメトリ プロセッサの例」を参照してください。

include 条件と exclude 条件

属性プロセッサでは、省略可能な include と exclude の条件がサポートされています。 属性プロセッサが適用されるのは、その include 条件 (使用可能な場合) に一致していて、"かつ" exclude 条件 (指定されている場合) に一致しないテレメトリに対してのみです。

このオプションを構成するには、include または exclude (またはその両方) の下に、少なくとも 1 つの matchType と、spanNames または attributes のいずれかを指定します。 include または exclude 構成では、複数の条件を指定できます。 一致が成立するためには、指定したすべての条件が true と評価される必要があります。

  • 必須フィールド:

    • matchType では、spanNames 配列および attributes 配列内の項目をどのように解釈するかを制御します。 設定可能な値は regexp および strict です。 正規表現の一致は、属性値全体に対して実行されます。そのため、その中のどこかに abc が含まれる値に一致することが望まれる場合、.*abc.* を使用する必要があります。

  • 省略可能なフィールド:

    • spanNames は少なくとも 1 つの項目に一致する必要があります。
    • attributes では、照合対象の属性の一覧を指定します。 一致が成立するためには、これらの属性すべてが完全に一致する必要があります。

Note

include と exclude の両方が指定されている場合は、exclude プロパティをチェックする前に include プロパティがチェックされます。

Note

include または exclude の構成で spanNames が指定されていない場合、一致条件は spans と logs の両方に適用されます。

使用例

"processors": [
  {
    "type": "attribute",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "redact_trace",
          "value": "false"
        }
      ]
    },
    "actions": [
      {
        "key": "credit_card",
        "action": "delete"
      },
      {
        "key": "duplicate_key",
        "action": "delete"
      }
    ]
  }
]

詳細については、テレメトリ プロセッサの例に関する記事を参照してください。

スパン プロセッサ

スパン プロセッサにより、スパン名、またはそのスパン名に基づくスパンの属性が変更されます。 スパンを含めたり除外したりする機能がサポートされます。

スパンに名前を付ける

name セクションには fromAttributes 設定が必要です。 これらの属性の値は新しい名前を作成するために使用され、構成で指定した順序に従って連結されます。 プロセッサによってスパン名が変更されるのは、これらの属性すべてがスパンに存在する場合のみです。

separator 設定は省略可能です。 この設定は文字列であり、分割値を使用できます。

Note

名前の変更が、属性プロセッサによる属性の変更に依存している場合は、パイプライン仕様で属性プロセッサの後にスパン プロセッサを指定するようにしてください。

"processors": [
  {
    "type": "span",
    "name": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

スパン名から属性を抽出する

toAttributes セクションには、スパン名と照合する正規表現の一覧を含めます。 部分式に基づいて属性が抽出されます。

rules 設定は必須です。 この設定では、スパン名から属性値を抽出するために使用される規則の一覧を指定します。

抽出された属性名によって、スパン名の値が置き換えられます。 一覧内の各規則は、正規表現 (regex) パターン文字列です。

抽出された属性名によって値がどのように置き換えられるかを次に示します。

  1. 正規表現に対してスパン名がチェックされます。
  2. 正規表現に一致する場合、正規表現のすべての名前付き部分式が属性として抽出されます。
  3. 抽出された属性がスパンに追加されます。
  4. 各部分式名が属性名になります。
  5. 部分式の一致する部分が属性値になります。
  6. 抽出された属性名によって、スパン名の一致する部分が置き換えられます。 属性がスパン内に既に存在する場合は、上書きされます。

すべての規則について、指定した順序で、このプロセスが繰り返されます。 後続の各規則は、前の規則の出力であるスパン名に対して処理されます。

"processors": [
  {
    "type": "span",
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

共通のスパン属性

このセクションでは、テレメトリ プロセッサで使用できるいくつかの共通のスパン属性を一覧表示します。

HTTP スパン

属性 Type 説明
http.request.method (以前の http.method) string HTTP 要求メソッド。
url.full (クライアント スパン) または url.path (サーバー スパン) (以前の http.url) string scheme://host[:port]/path?query[#fragment] 形式の完全な HTTP 要求 URL。 通常、フラグメントは HTTP 経由で送信されません。 しかし、フラグメントがわかっている場合は、含める必要があります。
http.response.status_code (以前の http.status_code) 数値 HTTP 応答状態コード.
network.protocol.version (以前の http.flavor) string HTTP プロトコルの種類。
user_agent.original (以前の http.user_agent) string クライアントから送信された HTTP ユーザー エージェント ヘッダーの値。

Java Database Connectivity スパン

次の表では、Java Database Connectivity (JDBC) スパンで使用できる属性について説明します。

属性 Type 説明
db.system string 使用されているデータベース管理システム (DBMS) 製品の識別子。 データベース操作のセマンティック規約に関するページを参照してください。
db.connection_string string データベースへの接続に使用された接続文字列。 埋め込みの資格情報は削除することをお勧めします。
db.user string データベースにアクセスするためのユーザー名
db.name string アクセス対象のデータベースの名前を報告するために使用される文字列。 データベースを切り替えるコマンドの場合、この文字列はターゲット データベースに設定する必要があります (コマンドが失敗する場合でも)。
db.statement string 実行されているデータベース ステートメント。

include 条件と exclude 条件

スパン プロセッサでは、省略可能な include と exclude の条件がサポートされています。 スパン プロセッサが適用されるのは、その include 条件 (使用可能な場合) に一致していて、"かつ" exclude 条件 (指定されている場合) に一致しないテレメトリに対してのみです。

このオプションを構成するには、include または exclude (またはその両方) の下で、少なくとも 1 つの matchType と、spanNames またはスパン attributes のいずれかを指定します。 include または exclude 構成では、複数の条件を指定できます。 一致が成立するためには、指定したすべての条件が true と評価される必要があります。

  • 必須フィールド:

    • matchType では、spanNames 配列および attributes 配列内の項目をどのように解釈するかを制御します。 設定可能な値は regexp および strict です。 正規表現の一致は、属性値全体に対して実行されます。そのため、その中のどこかに abc が含まれる値に一致することが望まれる場合、.*abc.* を使用する必要があります。

  • 省略可能なフィールド:

    • spanNames は少なくとも 1 つの項目に一致する必要があります。
    • attributes では、照合対象の属性の一覧を指定します。 一致が成立するためには、これらの属性すべてが完全に一致する必要があります。

Note

include と exclude の両方が指定されている場合は、exclude プロパティをチェックする前に include プロパティがチェックされます。

使用例

"processors": [
  {
    "type": "span",
    "include": {
      "matchType": "strict",
      "spanNames": [
        "spanA",
        "spanB"
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "attributeValue1"
        }
      ]
    },
    "name": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

詳細については、テレメトリ プロセッサの例に関する記事を参照してください。

ログ プロセッサ

Note

ログ プロセッサは、バージョン 3.1.1 以降で使用できます。

ログ プロセッサは、ログ メッセージ本文またはログ メッセージ本文に基づいてログの属性を変更します。 ログを含めたり除外したりする機能をサポートできます。

ログ メッセージ本文を更新する

body セクションには fromAttributes 設定が必要です。 これらの属性の値は新しい本文を作成するために使用され、構成で指定した順序に従って連結されます。 プロセッサによってログ本文が変更されるのは、これらの属性すべてがログに存在する場合のみです。

separator 設定は省略可能です。 この設定は文字列です。 これには分割値を指定できます。

Note

名前の変更が、属性プロセッサによる属性の変更に依存している場合は、パイプライン仕様で属性プロセッサの後にログ プロセッサを指定するようにしてください。

"processors": [
  {
    "type": "log",
    "body": {
      "fromAttributes": [
        "attributeKey1",
        "attributeKey2",
      ],
      "separator": "::"
    }
  }
]

ログ メッセージ本文から属性を抽出する

toAttributes セクションには、ログ メッセージ本文と照合する正規表現が一覧表示されます。 部分式に基づいて属性が抽出されます。

rules 設定は必須です。 この設定では、本文から属性値を抽出するために使用される規則の一覧を指定します。

抽出された属性名によって、ログ メッセージ本文の値が置き換えられます。 一覧内の各規則は、正規表現 (regex) パターン文字列です。

抽出された属性名によって値がどのように置き換えられるかを次に示します。

  1. ログ メッセージ本文が正規表現に対してチェックされます。
  2. 正規表現に一致する場合、正規表現のすべての名前付き部分式が属性として抽出されます。
  3. 抽出された属性がログに追加されます。
  4. 各部分式名が属性名になります。
  5. 部分式の一致する部分が属性値になります。
  6. 抽出された属性名によって、ログ名の一致する部分が置き換えられます。 属性がログ内に既に存在する場合は、上書きされます。

すべての規則について、指定した順序で、このプロセスが繰り返されます。 後続の各規則は、前の規則の出力であるログ名に対して処理されます。

"processors": [
  {
    "type": "log",
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

include 条件と exclude 条件

ログ プロセッサでは、省略可能な include と exclude の条件がサポートされています。 ログ プロセッサが適用されるのは、その include 条件 (使用可能な場合) に一致していて、"かつ" exclude 条件 (指定されている場合) に一致しないテレメトリに対してのみです。

このオプションを構成するには、include または exclude (またはその両方) の下で、matchType と attributes を指定します。 include または exclude 構成では、複数の条件を指定できます。 一致が成立するためには、指定したすべての条件が true と評価される必要があります。

  • 必須フィールド:
    • matchType は、attributes 配列内の項目をどのように解釈するかを制御します。 設定可能な値は regexp および strict です。 正規表現の一致は、属性値全体に対して実行されます。そのため、その中のどこかに abc が含まれる値に一致することが望まれる場合、.*abc.* を使用する必要があります。
    • attributes では、照合対象の属性の一覧を指定します。 一致が成立するためには、これらの属性すべてが完全に一致する必要があります。

Note

include と exclude の両方が指定されている場合は、exclude プロパティをチェックする前に include プロパティがチェックされます。

Note

ログ プロセッサでは、spanNames はサポートされていません。

使用例

"processors": [
  {
    "type": "log",
    "include": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute1",
          "value": "value1"
        }
      ]
    },
    "exclude": {
      "matchType": "strict",
      "attributes": [
        {
          "key": "attribute2",
          "value": "value2"
        }
      ]
    },
    "body": {
      "toAttributes": {
        "rules": [
          "rule1",
          "rule2",
          "rule3"
        ]
      }
    }
  }
]

詳細については、テレメトリ プロセッサの例に関する記事を参照してください。

メトリック フィルター

Note

メトリック フィルターは、バージョン 3.1.1 以降で使用できます。

メトリック フィルターを使用して、インジェスト コストの管理に役立てるためにいくつかのメトリックを除外します。

メトリック フィルターでは、exclude 条件のみがサポートされています。 その exclude 条件に一致するメトリックは、エクスポートされません。

このオプションを構成するには、exclude で matchType に 1 つ以上の metricNames を指定します。

  • 必須フィールド:
    • matchType は、metricNames 内の項目の照合方法を制御します。 設定可能な値は regexp および strict です。 正規表現の一致は、属性値全体に対して実行されます。そのため、その中のどこかに abc が含まれる値に一致することが望まれる場合、.*abc.* を使用する必要があります。
    • metricNames は少なくとも 1 つの項目に一致する必要があります。

使用例

次のサンプルは、"metricA" と "metricB" という名前のメトリックを除外する方法を示しています。

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "strict",
      "metricNames": [
        "metricA",
        "metricB"
      ]
    }
  }
]

次のサンプルは、CPU やメモリなどの既定の自動収集パフォーマンス メトリックを含め、すべてのメトリックをオフにする方法を示しています。

"processors": [
  {
    "type": "metric-filter",
    "exclude": {
      "matchType": "regexp",
      "metricNames": [
        ".*"
      ]
    }
  }
]

Java エージェントによってキャプチャされる既定のメトリック

メトリックの名前 メトリックの種類 説明 フィルターの適用
Current Thread Count カスタム メトリック 「ThreadMXBean.getThreadCount()」を参照してください。 yes
Loaded Class Count カスタム メトリック 「ClassLoadingMXBean.getLoadedClassCount()」を参照してください。 yes
GC Total Count カスタム メトリック すべての GarbageCollectorMXBean インスタンスのカウントの合計 (最後に報告されてからの差分)。 「GarbageCollectorMXBean.getCollectionCount()」を参照してください。 yes
GC Total Time カスタム メトリック すべての GarbageCollectorMXBean インスタンスの時間の合計 (最後に報告されてからの差分)。 「GarbageCollectorMXBean.getCollectionTime()」を参照してください。 yes
Heap Memory Used (MB) カスタム メトリック 「MemoryMXBean.getHeapMemoryUsage().getUsed()」を参照してください。 yes
% Of Max Heap Memory Used カスタム メトリック java.lang:type=Memory / メモリの最大量 (バイト単位) 「MemoryUsage」を参照してください yes
\Processor(_Total)\% Processor Time 既定のメトリック 所与の時間間隔において、システム全体の CPU 負荷ティック カウンター (ユーザーとシステムのみ) の差異を、論理プロセッサ カウントの数で割ったもの いいえ
\Process(??APP_WIN32_PROC??)\% Processor Time 既定のメトリック 「OperatingSystemMXBean.getProcessCpuTime() (前回報告以後の差分、時間と CPU 数で正規化)」を参照してください。 ×
\Process(??APP_WIN32_PROC??)\Private Bytes 既定のメトリック MemoryMXBean.getHeapMemoryUsage() と MemoryMXBean.getNonHeapMemoryUsage() の合計。 ×
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec 既定のメトリック /proc/[pid]/io プロセスによって読み取られ、書き込まれたバイトの合計 (前回報告以後の差分)。 「proc(5)」を参照してください。 Ｘ
\Memory\Available Bytes 既定のメトリック 「OperatingSystemMXBean.getFreePhysicalMemorySize()」を参照してください。 いいえ

よく寄せられる質問

ログ プロセッサが TelemetryClient.trackTrace() を使用してログ ファイルを処理しないのはなぜですか?

TelemetryClient.trackTrace() は Application Insights Classic SDK ブリッジの一部であり、ログ プロセッサは新しい OpenTelemetry ベースのインストルメンテーションでのみ機能します。