次の方法で共有


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

この記事では、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"
          }
        ]
      }
    ]
  }
}

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

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

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

  • 属性 (envdev など) がスパン内に存在する必要があります。
  • スパンには、キー 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 以降、テレメトリ プロセッサは、文字列以外の型が指定された属性 booleandoublelongboolean-arraydouble-arraylong-arraystring-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 をサポートします。

次の例では、属性 longRegexpAttributeKey400 から 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.svcoperation、および 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 ベースのインストルメンテーションでのみ機能します。