テレメトリプロセッサの例 - Azure Monitor Application Insights for Java

[アーティクル]
03/11/2024

この記事では、Application Insights for Java のテレメトリプロセッサの例を示します。include 構成と exclude 構成のサンプルが含まれます。属性プロセッサとスパンプロセッサのサンプルも含まれています。

include と exclude の Span サンプル

このセクションでは、スパンを含める方法と除外する方法について説明します。また、複数のスパンを除外し、選択的処理を適用する方法についても説明します。

スパンを含める

このセクションでは、属性プロセッサに対してスパンを含める方法について説明します。このプロセッサでは、プロパティに一致しないスパンは処理されません。

一致が成立するためには、スパン名が spanA または spanB と同じである必要があります。

次のスパンは include プロパティと一致し、プロセッサアクションが適用されます。

Span1 Name: 'spanA' Attributes: {env: dev, test_request: 123, credit_card: 1234}
Span2 Name: 'spanB' Attributes: {env: dev, test_request: false}
Span3 Name: 'spanA' Attributes: {env: 1, test_request: dev, credit_card: 1234}

次のスパンは include プロパティと一致しないため、プロセッサアクションは適用されません。

Span4 Name: 'spanC' Attributes: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

スパンを除外する

このセクションでは、属性プロセッサに対してスパンを除外する方法を示します。このプロセッサでは、プロパティに一致するスパンは処理されません。

一致が成立するためには、スパン名が spanA または spanB と同じである必要があります。

次のスパンは exclude プロパティと一致するため、プロセッサアクションは適用されません。

Span1 Name: 'spanA' Attributes: {env: dev, test_request: 123, credit_card: 1234}
Span2 Name: 'spanB' Attributes: {env: dev, test_request: false}
Span3 Name: 'spanA' Attributes: {env: 1, test_request: dev, credit_card: 1234}

次のスパンは exclude プロパティと一致しないため、プロセッサアクションが適用されます。

Span4 Name: 'spanC' Attributes: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

複数の条件を使用してスパンを除外する

一致が成立するためには、次の条件が満たされる必要があります。

属性 (env や dev など) がスパン内に存在する必要があります。
スパンには、キー test_request を持つ属性が必要です。

次のスパンは exclude プロパティと一致するため、プロセッサアクションは適用されません。

Span1 Name: 'spanB' Attributes: {env: dev, test_request: 123, credit_card: 1234}
Span2 Name: 'spanA' Attributes: {env: dev, test_request: false}

次のスパンは exclude プロパティと一致しないため、プロセッサアクションが適用されます。

Span3 Name: 'spanB' Attributes: {env: 1, test_request: dev, credit_card: 1234}
Span4 Name: 'spanC' Attributes: {env: dev, dev_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ],
          "attributes": [
            {
              "key": "env",
              "value": "dev"
            },
            {
              "key": "test_request"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

選択的処理

このセクションでは、どのスパンに対してこのプロセッサを適用するかを示す、スパンプロパティのセットを指定する方法について説明します。 include プロパティでは、処理する必要があるスパンを示します。 exclude プロパティでは、処理しないスパンが除外されます。

以下の構成の場合、次のスパンはプロパティと一致するため、プロセッサアクションが適用されます。

Span1 Name: 'spanB' Attributes: {env: production, test_request: 123, credit_card: 1234, redact_trace: "false"}
Span2 Name: 'spanA' Attributes: {env: staging, test_request: false, redact_trace: true}

次のスパンは include プロパティと一致しないため、プロセッサアクションは適用されません。

Span3 Name: 'spanB' Attributes: {env: production, test_request: true, credit_card: 1234, redact_trace: false}
Span4 Name: 'spanC' Attributes: {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "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"
          }
        ]
      }
    ]
  }
}

属性プロセッサのサンプル

挿入

次の例では、キー attribute1 が存在しないスパンおよびログに新しい属性 {"attribute1": "attributeValue1"} を挿入します。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "attribute1",
            "value": "attributeValue1",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

別のキーから挿入する

次の例では、属性 anotherkey からの値を使用して、キー newKey が存在しないスパンおよびログに新しい属性 {"newKey": "<value from attribute anotherkey>"} を挿入します。属性 anotherkey が存在しない場合、新しい属性はスパンおよびログに挿入されません。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "newKey",
            "fromAttribute": "anotherKey",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

更新

次の例では、属性を {"db.secret": "redacted"} に更新します。属性 foo からの値を使用して、属性 boo を更新します。属性 boo を持たないスパンおよびログは変更されません。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "db.secret",
            "value": "redacted",
            "action": "update"
          },
          {
            "key": "boo",
            "fromAttribute": "foo",
            "action": "update" 
          }
        ]
      }
    ]
  }
}

削除

次の例では、キー credit_card を持つ属性を削除する方法が示されています。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

ハッシュインデックス

次の例では、既存の属性値をハッシュする方法が示されています。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "user.email",
            "action": "hash"
          }
        ]
      }
    ]
  }
}

Extract

次の例では、正規表現 (regex) を使用して、別の属性の値に基づいて新しい属性を作成する方法が示されています。たとえば、url.path = /path?queryParam1=value1,queryParam2=value2 が指定された場合、以下の属性が挿入されます。

httpProtocol: http
httpDomain: example.com
httpPath: path
httpQueryParams: queryParam1=value1,queryParam2=value2
url.path: no change

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
            "action": "extract"
          }
        ]
      }
    ]
  }
}

マスク

たとえば、指定された url.path = https://example.com/user/12345622 は、次のいずれかの構成を使用して url.path = https://example.com/user/**** に更新されます。

最初の構成例:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "user\\/\\d+",
            "replace": "user\\/****",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

正規表現グループ名を使用した 2 番目の構成例:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
            "replace": "${userGroupName}**",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

文字列以外の型が指定された属性の例

3.4.19 GA 以降、テレメトリプロセッサは、文字列以外の型が指定された属性 boolean、double、long、boolean-array、double-array、long-array、string-array をサポートします。

attributes.type が json で指定されていない場合、既定値は string になります。

次の例では、属性が以下の例と一致するスパンとログに新しい属性 {"newAttributeKeyStrict": "newAttributeValueStrict"} を挿入します: {"longAttributeKey": 1234}{"booleanAttributeKey": true}{"doubleArrayAttributeKey": [1.0, 2.0, 3.0, 4.0]}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "longAttributeKey",
              "value": 1234,
              "type": "long"
            },
            {
              "key": "booleanAttributeKey",
              "value": true,
              "type": "boolean"
            },
            {
              "key": "doubleArrayAttributeKey",
              "value": [1.0, 2.0, 3.0, 4.0],
              "type": "double-array"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyStrict",
            "value": "newAttributeValueStrict",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyStrict"
      }
    ]
  }
}

さらに、文字列以外の型が指定された属性は regexp をサポートします。

次の例では、属性 longRegexpAttributeKey が 400 から 499 の値と一致するスパンとログに、新しい属性 {"newAttributeKeyRegexp": "newAttributeValueRegexp"} を挿入します。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "regexp",
          "attributes": [
            {
              "key": "longRegexpAttributeKey",
              "value": "4[0-9][0-9]",
              "type": "long"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyRegexp",
            "value": "newAttributeValueRegexp",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyRegexp"
      }
    ]
  }
}

スパンプロセッサのサンプル

スパンに名前を付ける

次の例では、属性 db.svc、operation、および id の値を指定しています。これらの属性をこの順番で使用し、値 :: で区切ることによって、スパンの新しい名前が形成されます。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "fromAttributes": [
            "db.svc",
            "operation",
            "id"
          ],
          "separator": "::"
        }
      }
    ]
  }
}

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

入力スパン名が /api/v1/document/12345678/update であると仮定しましょう。次の例では、/api/v1/document/{documentId}/update という出力スパン名が生成されます。スパンに新しい属性 documentId=12345678 が追加されます。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "toAttributes": {
            "rules": [
              "^/api/v1/document/(?<documentId>.*)/update$"
            ]
          }
        }
      }
    ]
  }
}

include および exclude を使用してスパン名から属性を抽出する

次の例では、スパン名を {operation_website} に変更する方法を示します。スパンが次のプロパティを持つ場合に、キーが operation_website、値が {oldSpanName} の属性が追加されます。

スパン名の文字列の任意の場所に / が含まれる。
スパン名が donot/change でない。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "regexp",
          "spanNames": [
            "^(.*?)/(.*?)$"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "donot/change"
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [
              "(?<operation_website>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

スパンプロセッサのサンプル

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

入力ログメッセージの本文が Starting PetClinicApplication on WorkLaptop with PID 27984 (C:\randompath\target\classes started by userx in C:\randompath) であると仮定します。次の例では、Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath) という出力メッセージ本体が生成されます。ログに新しい属性 PIDVALUE=27984 が追加されます。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
            ]
          }
        }
      }
    ]
  }
}

ログメッセージ内の機密データのマスキング

次の例は、ログプロセッサと属性プロセッサの両方を使用して、ログメッセージ本文の機密データをマスクする方法を示しています。入力ログメッセージの本文が User account with userId 123456xx failed to login であると仮定します。ログプロセッサは出力メッセージ本文を User account with userId {redactedUserId} failed to login に更新し、属性プロセッサは前の手順で追加した新しい redactedUserId 属性を削除します。

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "userId (?<redactedUserId>[0-9a-zA-Z]+)"
            ]
          }
        }
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "redactedUserId",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

よく寄せられる質問

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

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

テレメトリ プロセッサの例 - Azure Monitor Application Insights for Java

include と exclude の Span サンプル

スパンを含める

スパンを除外する

複数の条件を使用してスパンを除外する

選択的処理

属性プロセッサのサンプル

挿入

別のキーから挿入する

更新

削除

ハッシュ インデックス

Extract

マスク

文字列以外の型が指定された属性の例

スパン プロセッサのサンプル

スパンに名前を付ける

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

include および exclude を使用してスパン名から属性を抽出する

スパン プロセッサのサンプル

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

ログ メッセージ内の機密データのマスキング

よく寄せられる質問

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

その他のリソース

テレメトリプロセッサの例 - Azure Monitor Application Insights for Java

ハッシュインデックス

スパンプロセッサのサンプル

スパンプロセッサのサンプル

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

ログメッセージ内の機密データのマスキング

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