Procesory telemetrie (Preview) – Přehledy aplikací služby Azure Monitor pro Javu

Článek
03/15/2024

Poznámka:

Funkce procesorů telemetrie je určená jako verze Preview, protože nemůžeme zaručit zpětnou kompatibilitu od vydání do vydání kvůli experimentálnímu stavu sémantických konvencí atributů. Tato funkce se ale otestovala a je podporována v produkčním prostředí.

Aplikace Přehledy 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.

Poznámka:

Pokud hledáte pokles konkrétních (celých) rozsahů pro řízení nákladů na příjem dat, podívejte se na přepsání vzorkování.

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.

Poznámka:

Procesory telemetrie v současné době zpracovávají pouze atributy typu string. Nezpracovávají atributy typu logická hodnota nebo číslo.

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 spanlog. 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`

Poznámka:

Tato extract funkce je dostupná pouze ve verzi 3.0.2 a novější.

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`

Poznámka:

Tato mask funkce je dostupná jenom ve verzi 3.2.5 a novější.

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

"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 matchTypespanNames 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.

Poznámka:

Pokud jsou zadány obě include a exclude jsou zadány, include vlastnosti jsou kontrolovány před kontrolou exclude vlastností.

Poznámka:

include Pokud není zadána konfigurace excludespanNames, použije se odpovídající kritéria pro obě spans a logs.

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.

Poznámka:

Pokud přejmenování využívá procesor atributů k úpravě atributů, zajistěte, aby byl procesor span zadán za procesorem atributů ve specifikaci kanálu.

"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:

Název rozsahu se kontroluje u regulárního výrazu.
Všechny pojmenované dílčí výrazy regulárního výrazu se extrahují jako atributy, pokud regulární výraz odpovídá.
Extrahované atributy se přidají do rozsahu.
Každý název dílčího výrazu se stane názvem atributu.
Dílčí výraz odpovídající části se stane hodnotou atributu.
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

Atribut	Typ	Popis
`http.request.method`(používá se)`http.method`	string	Metoda požadavku HTTP.
`url.full` (rozsah klienta) nebo `url.path` (rozsah serveru) (použitý k `http.url`)	string	Úplná adresa URL požadavku HTTP ve formuláři `scheme://host[:port]/path?query[#fragment]`. Fragment se obvykle nepřenáší přes protokol HTTP. Pokud je ale fragment známý, měl by být zahrnut.
`http.response.status_code`(používá se)`http.status_code`	Číslo	Stavový kód odpovědi HTTP.
`network.protocol.version`(používá se)`http.flavor`	string	Typ protokolu HTTP.
`user_agent.original`(používá se)`http.user_agent`	string	Hodnota hlavičky HTTP User-Agent odeslané klientem.

Rozsahy Připojení ivity v Javě Database

Následující tabulka popisuje atributy, které můžete použít ve službě Java Database Připojení ivity (JDBC):

Atribut	Typ	Description
`db.system`	string	Identifikátor používaného produktu DBMS (Database Management System). Viz sémantické konvence pro databázové operace.
`db.connection_string`	string	Připojení ion řetězec použitý k připojení k databázi. Doporučujeme odebrat vložené přihlašovací údaje.
`db.user`	string	Uživatelské jméno pro přístup k databázi.
`db.name`	string	Řetězec použitý k hlášení názvu databáze, ke které se přistupuje. U příkazů, které přepínají databázi, by měl být tento řetězec nastaven na cílovou databázi, i když příkaz selže.
`db.statement`	string	Příkaz databáze, který se spouští.

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.

Poznámka:

Pokud jsou zadány obě include a exclude jsou zadány, include vlastnosti jsou kontrolovány před kontrolou exclude vlastností.

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ů

Poznámka:

Procesory protokolů jsou dostupné od verze 3.1.1.

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.

Poznámka:

Pokud přejmenování využívá procesor atributů k úpravě atributů, ujistěte se, že je procesor protokolu zadaný za procesorem atributů ve specifikaci kanálu.

"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:

Text zprávy protokolu se kontroluje proti regulárnímu výrazu.
Všechny pojmenované dílčí výrazy regulárního výrazu se extrahují jako atributy, pokud regulární výraz odpovídá.
Extrahované atributy se přidají do protokolu.
Každý název dílčího výrazu se stane názvem atributu.
Dílčí výraz odpovídající části se stane hodnotou atributu.
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 matchTypeattributes 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.

Poznámka:

Pokud jsou zadány obě include a exclude jsou zadány, include vlastnosti jsou kontrolovány před kontrolou exclude vlastností.

Poznámka:

Procesory protokolů nepodporují spanNames.

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

Poznámka:

Filtry metrik jsou dostupné od verze 3.1.1.

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

Název metriky	Typ metriky	Popis	Filterable
`Current Thread Count`	vlastní metriky	Viz ThreadMXBean.getThreadCount().	ano
`Loaded Class Count`	vlastní metriky	Viz ClassLoadingMXBean.getLoadedClassCount().	ano
`GC Total Count`	vlastní metriky	Součet počtů napříč všemi instancemi GarbageCollectorMXBean (rozdíl od posledního nahlášení). Viz GarbageCollectorMXBean.getCollectionCount().	ano
`GC Total Time`	vlastní metriky	Součet času napříč všemi instancemi GarbageCollectorMXBean (rozdíl od posledního nahlášení). Viz GarbageCollectorMXBean.getCollectionTime().	ano
`Heap Memory Used (MB)`	vlastní metriky	Viz MemoryMXBean.getHeapMemoryUsage().getUsed().	ano
`% Of Max Heap Memory Used`	vlastní metriky	java.lang:type=Paměť / maximální množství paměti v bajtech. Viz MemoryUsage	ano
`\Processor(_Total)\% Processor Time`	výchozí metriky	Rozdíl v čítačích zatížení procesoru v celém systému (pouze uživatel a systém) vydělený počtem logických procesorů v daném časovém intervalu	ne
`\Process(??APP_WIN32_PROC??)\% Processor Time`	výchozí metriky	Viz OperatingSystemMXBean.getProcessCpuTime() (rozdíl od posledního nahlášeného stavu normalizovaný podle času a počtu procesorů).	ne
`\Process(??APP_WIN32_PROC??)\Private Bytes`	výchozí metriky	Sum of MemoryMXBean.getHeapMemoryUsage() and MemoryMXBean.getNonHeapMemoryUsage().	ne
`\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec`	výchozí metriky	`/proc/[pid]/io` Součet bajtů přečtených a zapsaných procesem (rozdíl od posledního nahlášení). Viz proc(5).	ne
`\Memory\Available Bytes`	výchozí metriky	Viz OperatingSystemMXBean.getFreePhysicalMemorySize().	ne

Nejčastější dotazy

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

TelemetryClient.trackTrace() je součástí mostu Application Přehledy Classic SDK a procesory protokolů pracují pouze s novou instrumentací založenou na OpenTelemetry.

Procesory telemetrie (Preview) – Přehledy aplikací služby Azure Monitor pro Javu

Terminologie

Typy procesoru telemetrie

Začínáme

Procesor atributů

insert

update

delete

hash

extract

mask

Zahrnout kritéria a vyloučit kritéria

Ukázkové využití

Procesor span

Pojmenujte rozsah.

Extrahování atributů z názvu rozsahu

Běžné atributy spanu

Rozsahy HTTP

Rozsahy Připojení ivity v Javě Database

Zahrnout kritéria a vyloučit kritéria

Ukázkové využití

Procesor protokolů

Text zprávy protokolu aktualizace

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

Zahrnout kritéria a vyloučit kritéria

Ukázkové využití

Filtr metrik

Ukázkové využití

Výchozí metriky zachycené agentem Java

Nejčastější dotazy

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

Další materiály

`insert`

`update`

`delete`

`hash`

`extract`

`mask`