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

[アーティクル]
11/15/2023

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) パターン文字列です。

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

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

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

"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) パターン文字列です。

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

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

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

"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 ベースのインストルメンテーションでのみ機能します。

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

用語

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

作業の開始

属性プロセッサ

insert

update

delete

hash

extract

mask

include 条件と exclude 条件

使用例

スパン プロセッサ

スパンに名前を付ける

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

共通のスパン属性

HTTP スパン

Java Database Connectivity スパン

include 条件と exclude 条件

使用例

ログ プロセッサ

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

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

include 条件と exclude 条件

使用例

メトリック フィルター

使用例

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

よく寄せられる質問

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

その他のリソース

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

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

`insert`

`update`

`delete`

`hash`

`extract`

`mask`

スパンプロセッサ

ログプロセッサ

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

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

メトリックフィルター

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