Procesory telemetrie (Preview) – Azure Monitor Application Insights pro Javu

Application Insights Java 3.x může zpracovávat telemetrická data před exportem dat.

Některé případy použití:

• Maskovat citlivá data.
• Podmíněně přidejte vlastní dimenze.
• Aktualizujte název rozsahu, který se používá k agregaci podobné telemetrie na webu Azure Portal.
• Zahoďte konkrétní atributy rozsahu, abyste mohli řídit náklady na příjem dat.
• Vyfiltrujte některé metriky, abyste mohli řídit náklady na příjem dat.

Terminologie

Než se seznámíte s procesory telemetrie, měli byste porozumět rozsahu termínů a protokolům.

Rozsah je typ telemetrie, která představuje jednu z těchto možností:

• Příchozí požadavek.
• Odchozí závislost (například vzdálené volání do jiné služby).
• Závislost v procesu (například práce provedená dílčími součástmi služby)

Protokol je typ telemetrie, která představuje:

• Data protokolu zachycená z Log4j, Logback a java.util.logging

Pro procesory telemetrie jsou důležité tyto součásti rozsahu a protokolů:

• Název
• Text
• Atributy

Název rozsahu je primárním zobrazením požadavků a závislostí na webu Azure Portal. Atributy Span představují standardní i vlastní vlastnosti daného požadavku nebo závislosti.

Zpráva nebo text trasování je primárním zobrazením protokolů na webu Azure Portal. Atributy protokolu představují standardní i vlastní vlastnosti daného protokolu.

Typy procesoru telemetrie

V současné době jsou čtyři typy procesorů telemetrie

• Procesory atributů
• Procesory span
• Procesory protokolů
• Filtry metrik

Procesor atributů může vkládat, aktualizovat, odstraňovat nebo hashovat atributy položky telemetrie (span nebo log). Může také použít regulární výraz k extrahování jednoho nebo více nových atributů z existujícího atributu.

Procesor spanu může aktualizovat název telemetrie požadavků a závislostí. Může také použít regulární výraz k extrahování jednoho nebo více nových atributů z názvu rozsahu.

Procesor protokolů může aktualizovat název telemetrie protokolů. Může také použít regulární výraz k extrahování jednoho nebo více nových atributů z názvu protokolu.

Filtr metrik může vyfiltrovat metriky, které pomáhají řídit náklady na příjem dat.

Začínáme

Začněte vytvořením konfiguračního souboru s názvem applicationinsights.json. Uložte ho do stejného adresáře jako applicationinsights-agent-*.jar. Použijte následující šablonu.

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

Procesor atributů

Procesor atributu upravuje atributy nebo span log. Může podporovat možnost zahrnout nebo vyloučit span nebo log. Provede seznam akcí prováděných v pořadí, v jakém konfigurační soubor určuje. Procesor podporuje tyto akce:

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

insert

Akce insert vloží nový atribut do položky telemetrie, kde key ještě neexistuje.

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

Akce insert vyžaduje následující nastavení:

• key
• Buďto value nebo fromAttribute
• action: insert

update

Akce update aktualizuje atribut v položce telemetrie, kde key již existuje.

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

Akce update vyžaduje následující nastavení:

• key
• Buďto value nebo fromAttribute
• action: update

delete

Akce delete odstraní atribut z položky telemetrie.

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

Akce delete vyžaduje následující nastavení:

• key
• action: delete

hash

Akce hash hashuje (SHA1) existující hodnotu atributu.

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

Akce hash vyžaduje následující nastavení:

• key
• action: hash

extract

Akce extract extrahuje hodnoty pomocí pravidla regulárního výrazu ze vstupního klíče do cílových klíčů, které pravidlo určuje. Pokud cílový klíč již existuje, extract akce přepíše cílový klíč. Tato akce se chová jako nastavení procesoru toAttributes span, kde existující atribut je zdrojem.

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

Akce extract vyžaduje následující nastavení:

• key
• pattern
• action: extract

mask

Akce mask maskuje hodnoty atributů pomocí pravidla regulárního výrazu zadaného v a pattern replace.

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

Akce mask vyžaduje následující nastavení:

• key
• pattern
• replace
• action: mask

pattern může obsahovat pojmenovanou skupinu umístěnou mezi ?< a >:. Příklad: (?<userGroupName>[a-zA-Z.:\/]+)\d+? Skupina je (?<userGroupName>[a-zA-Z.:\/]+) a userGroupName je název skupiny. pattern pak může obsahovat stejnou pojmenovanou skupinu umístěnou mezi ${ maskou a } za ní masku. Příklad, kde maska je **: ${userGroupName}**.

Příklady maskování najdete v příkladech procesoru telemetrie.

Zahrnout kritéria a vyloučit kritéria

Procesory atributů podporují volitelné include a exclude kritéria. Procesor atributů se použije jenom na telemetrii, která odpovídá jeho include kritériím (pokud je k dispozici) a neodpovídá jeho exclude kritériím (pokud je k dispozici).

Chcete-li tuto možnost nakonfigurovat, zadejte v části include nebo exclude (nebo obojí) alespoň jednu a jednu matchType spanNames nebo attributes. Konfigurace include umožňuje exclude více než jednu zadanou podmínku. Všechny zadané podmínky musí být vyhodnoceny jako true, aby výsledkem byla shoda.

• Povinná pole:

  • matchType určuje, jak se položky v spanNames polích a attributes polích interpretují. Možné hodnoty jsou regexp a strict. Porovnávání regulárních výrazů se provádí s celou hodnotou atributu, takže pokud chcete shodovat s hodnotou, která obsahuje abc kdekoli v ní, je potřeba použít .*abc.*.

• Volitelná pole:

  • spanNames musí odpovídat alespoň jedné z položek.
  • attributes určuje seznam atributů, které se mají shodovat. Všechny tyto atributy musí přesně odpovídat výsledku shody.

Ukázkové využití

"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"
      }
    ]
  }
]

Další informace najdete v příkladech procesoru telemetrie.

Procesor span

Procesor span upraví název rozsahu nebo atributy rozsahu na základě názvu rozsahu. Může podporovat možnost zahrnout nebo vyloučit rozsahy.

Pojmenujte rozsah.

Oddíl name vyžaduje fromAttributes nastavení. Hodnoty z těchto atributů se používají k vytvoření nového názvu zřetězení v pořadí, v jakém konfigurace určuje. Procesor změní název rozsahu pouze v případě, že jsou všechny tyto atributy přítomné na rozsahu.

Nastavení separator je volitelné. Toto nastavení je řetězec a můžete použít rozdělené hodnoty.

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

Extrahování atributů z názvu rozsahu

Oddíl toAttributes obsahuje seznam regulárních výrazů, které odpovídají názvu rozsahu. Extrahuje atributy na základě dílčích výrazů.

Nastavení rules je povinné. Toto nastavení uvádí pravidla, která se používají k extrakci hodnot atributů z názvu rozsahu.

Extrahované názvy atributů nahrazují hodnoty v názvu rozsahu. Každé pravidlo v seznamu je řetězec vzoru regulárního výrazu (regex).

Takto extrahované názvy atributů nahrazují hodnoty:

1. Název rozsahu se kontroluje u regulárního výrazu.
2. Všechny pojmenované dílčí výrazy regulárního výrazu se extrahují jako atributy, pokud regulární výraz odpovídá.
3. Extrahované atributy se přidají do rozsahu.
4. Každý název dílčího výrazu se stane názvem atributu.
5. Dílčí výraz odpovídající části se stane hodnotou atributu.
6. Extrahovaný název atributu nahradí odpovídající část v názvu rozsahu. Pokud už atributy v rozsahu existují, přepíšou se.

Tento proces se opakuje pro všechna pravidla v pořadí, v jakém jsou zadaná. Každé další pravidlo funguje na názvu rozsahu, který je výstupem předchozího pravidla.

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

Běžné atributy spanu

V této části jsou uvedeny některé běžné atributy rozsahu, které můžou používat procesory telemetrie.

Rozsahy HTTP

Připojení k databázi Java zahrnuje

Následující tabulka popisuje atributy, které můžete použít v JDBC (Java Database Connectivity):

Zahrnout kritéria a vyloučit kritéria

Procesory span podporují volitelné include a exclude kritéria. Procesor spanu se použije jenom na telemetrii, která odpovídá jeho include kritériím (pokud je k dispozici) a neodpovídá jeho exclude kritériím (pokud je k dispozici).

Chcete-li tuto možnost nakonfigurovat, zadejte v části include nebo exclude (nebo obojí) alespoň jednu a jednu matchType nebo spanNames rozsah attributes. Konfigurace include umožňuje exclude více než jednu zadanou podmínku. Všechny zadané podmínky musí být vyhodnoceny jako true, aby výsledkem byla shoda.

• Povinná pole:

  • matchType určuje, jak se položky v spanNames polích a attributes polích interpretují. Možné hodnoty jsou regexp a strict. Porovnávání regulárních výrazů se provádí s celou hodnotou atributu, takže pokud chcete shodovat s hodnotou, která obsahuje abc kdekoli v ní, je potřeba použít .*abc.*.

• Volitelná pole:

  • spanNames musí odpovídat alespoň jedné z položek.
  • attributes určuje seznam atributů, které se mají shodovat. Všechny tyto atributy musí přesně odpovídat výsledku shody.

Ukázkové využití

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

Další informace najdete v příkladech procesoru telemetrie.

Procesor protokolů

Procesor protokolu upravuje tělo zprávy protokolu nebo atributy protokolu na základě textu zprávy protokolu. Může podporovat možnost zahrnout nebo vyloučit protokoly.

Text zprávy protokolu aktualizace

Oddíl body vyžaduje fromAttributes nastavení. Hodnoty z těchto atributů se používají k vytvoření nového těla zřetězení v pořadí, v jakém konfigurace určuje. Procesor změní tělo protokolu pouze v případě, že jsou v protokolu přítomny všechny tyto atributy.

Nastavení separator je volitelné. Toto nastavení je řetězec. Můžete ho zadat pro rozdělení hodnot.

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

Extrahování atributů z textu zprávy protokolu

Oddíl toAttributes obsahuje seznam regulárních výrazů, které odpovídají textu zprávy protokolu. Extrahuje atributy na základě dílčích výrazů.

Nastavení rules je povinné. Toto nastavení uvádí pravidla, která se používají k extrakci hodnot atributů z těla.

Extrahované názvy atributů nahrazují hodnoty v textu zprávy protokolu. Každé pravidlo v seznamu je řetězec vzoru regulárního výrazu (regex).

Takto extrahované názvy atributů nahrazují hodnoty:

1. Text zprávy protokolu se kontroluje proti regulárnímu výrazu.
2. Všechny pojmenované dílčí výrazy regulárního výrazu se extrahují jako atributy, pokud regulární výraz odpovídá.
3. Extrahované atributy se přidají do protokolu.
4. Každý název dílčího výrazu se stane názvem atributu.
5. Dílčí výraz odpovídající části se stane hodnotou atributu.
6. Extrahovaný název atributu nahrazuje odpovídající část v názvu protokolu. Pokud už atributy v protokolu existují, přepíšou se.

Tento proces se opakuje pro všechna pravidla v pořadí, v jakém jsou zadaná. Každé další pravidlo funguje na názvu protokolu, který je výstupem předchozího pravidla.

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

Zahrnout kritéria a vyloučit kritéria

Procesory protokolů podporují volitelné include a exclude kritéria. Procesor protokolů se použije jenom na telemetrii, která odpovídá jeho include kritériím (pokud je k dispozici) a neodpovídá jeho exclude kritériím (pokud je k dispozici).

Chcete-li tuto možnost nakonfigurovat, v části include nebo exclude (nebo obojí) zadejte matchType attributes Konfigurace include umožňuje exclude více než jednu zadanou podmínku. Všechny zadané podmínky musí být vyhodnoceny jako true, aby výsledkem byla shoda.

• Povinné pole:
  • matchType určuje, jak se položky v attributes polích interpretují. Možné hodnoty jsou regexp a strict. Porovnávání regulárních výrazů se provádí s celou hodnotou atributu, takže pokud chcete shodovat s hodnotou, která obsahuje abc kdekoli v ní, je potřeba použít .*abc.*.
  • attributes určuje seznam atributů, které se mají shodovat. Všechny tyto atributy musí přesně odpovídat výsledku shody.

Ukázkové využití

"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"
        ]
      }
    }
  }
]

Další informace najdete v příkladech procesoru telemetrie.

Filtr metrik

Filtry metrik se používají k vyloučení některých metrik, aby bylo možné řídit náklady na příjem dat.

Filtry metrik podporují exclude pouze kritéria. Metriky, které odpovídají kritériím exclude , se neexportují.

Chcete-li tuto možnost nakonfigurovat, v části excludezadejte matchType jednu nebo více metricNames.

• Povinné pole:
  • matchType určuje, jak se položky ve metricNames shodě nacházejí. Možné hodnoty jsou regexp a strict. Porovnávání regulárních výrazů se provádí s celou hodnotou atributu, takže pokud chcete shodovat s hodnotou, která obsahuje abc kdekoli v ní, je potřeba použít .*abc.*.
  • metricNames musí odpovídat alespoň jedné z položek.

Ukázkové využití

Následující ukázka ukazuje, jak vyloučit metriky s názvy metricA a metricB:

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

Následující ukázka ukazuje, jak vypnout všechny metriky včetně výchozích automatickycollectovaných metrik výkonu, jako je procesor a paměť.

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

Výchozí metriky zachycené agentem Java

Nejčastější dotazy

Proč procesor protokolu zpracovává soubory protokolu pomocí TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() je součástí mostu Application Insights Classic SDK a procesory protokolů fungují jenom s novou instrumentací založenou na OpenTelemetry.