テレメトリ プロセッサ (プレビュー) - 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) パターン文字列です。
抽出された属性名によって値がどのように置き換えられるかを次に示します。
- 正規表現に対してスパン名がチェックされます。
- 正規表現に一致する場合、正規表現のすべての名前付き部分式が属性として抽出されます。
- 抽出された属性がスパンに追加されます。
- 各部分式名が属性名になります。
- 部分式の一致する部分が属性値になります。
- 抽出された属性名によって、スパン名の一致する部分が置き換えられます。 属性がスパン内に既に存在する場合は、上書きされます。
すべての規則について、指定した順序で、このプロセスが繰り返されます。 後続の各規則は、前の規則の出力であるスパン名に対して処理されます。
"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)」を参照してください。 |
X |
\Memory\Available Bytes |
既定のメトリック | 「OperatingSystemMXBean.getFreePhysicalMemorySize()」を参照してください。 | いいえ |
よく寄せられる質問
ログ プロセッサが TelemetryClient.trackTrace() を使用してログ ファイルを処理しないのはなぜですか?
TelemetryClient.trackTrace() は Application Insights Classic SDK ブリッジの一部であり、ログ プロセッサは新しい OpenTelemetry ベースのインストルメンテーションでのみ機能します。