Sdílet prostřednictvím

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

  • Článek

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í.

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.

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

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

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 exclude spanNames, 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:

  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

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.

Připojení k databázi Java zahrnuje

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

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řipojovací ř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:

  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.

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 Insights Classic SDK a procesory protokolů fungují jenom s novou instrumentací založenou na OpenTelemetry.