Telemetriai processzorok (előzetes verzió) – Azure Monitor-alkalmazás Elemzések Java-hoz

Feljegyzés

A telemetriai processzorok funkció előzetes verzióként van kijelölve, mivel az attribútum szemantikai konvencióinak kísérleti állapota miatt nem garantálhatjuk a kiadástól a kiadásig való visszamenőleges kompatibilitást. A funkciót azonban tesztelték, és éles környezetben is támogatott.

Az alkalmazás Elemzések Java 3.x képes a telemetriai adatok feldolgozására az adatok exportálása előtt.

Néhány használati eset:

  • Bizalmas adatok maszkolása.
  • Feltételesen adjon hozzá egyéni dimenziókat.
  • Frissítse a span nevet, amely az Azure Portal hasonló telemetriai adatainak összesítésére szolgál.
  • Adott span attribútumok elvetése a betöltési költségek szabályozásához.
  • Szűrjön ki néhány metrikát a betöltési költségek szabályozásához.

Feljegyzés

Ha konkrét (egész) időtartamokat szeretne elvetni a betöltési költségek szabályozásához, tekintse meg a mintavételezési felülbírálásokat.

Terminológia

A telemetriai processzorok megismerése előtt ismernie kell a kifejezéseketés a naplókat.

A span egy telemetriai típus, amely az alábbiak egyikét jelöli:

  • Bejövő kérés.
  • Kimenő függőség (például egy másik szolgáltatás távoli hívása).
  • Folyamaton belüli függőség (például a szolgáltatás alösszetevői által végzett munka).

A naplók a telemetria olyan típusai, amelyek a következőt jelölik:

  • log data captured from Log4j, Logback, and java.util.logging

A telemetriai processzorok esetében ezek a span/log összetevők fontosak:

  • Név
  • Törzs
  • Attribútumok

A span név a kérelmek és függőségek elsődleges megjelenítése az Azure Portalon. A span attribútumok egy adott kérés vagy függőség szabványos és egyéni tulajdonságait is jelölik.

A nyomkövetési üzenet vagy törzs az Azure Portal naplóinak elsődleges megjelenítése. A naplóattribútumok egy adott napló szabványos és egyéni tulajdonságait egyaránt képviselik.

Telemetriai processzortípusok

Jelenleg a telemetriai processzorok négy típusa

  • Attribútumprocesszorok
  • Span processzorok
  • Naplófeldolgozók
  • Metrikaszűrők

Az attribútumfeldolgozók beszúrhatnak, frissíthetnek, törölhetnek vagy kivonatoló attribútumokat egy telemetriai elemhez (span vagy log). Egy reguláris kifejezéssel is kinyerhet egy vagy több új attribútumot egy meglévő attribútumból.

A span processzor frissítheti a kérések és függőségek telemetriai nevét. Egy reguláris kifejezéssel is kinyerhet egy vagy több új attribútumot a span névből.

A naplófeldolgozók frissíthetik a naplók telemetriai nevét. Egy reguláris kifejezéssel is kinyerhet egy vagy több új attribútumot a napló nevéből.

A metrikaszűrők kiszűrhetik a metrikákat a betöltési költségek szabályozásához.

Feljegyzés

A telemetriai processzorok jelenleg csak a sztring típusú attribútumokat dolgozzák fel. Nem dolgozzák fel a logikai vagy szám típusú attribútumokat.

Első lépések

Először hozzon létre egy applicationinsights.json nevű konfigurációs fájlt. Mentse ugyanabban a könyvtárban, mint az applicationinsights-agent-*.jar. Használja az alábbi sablont.

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

Attribútumfeldolgozó

Az attribútumfeldolgozó módosítja egy vagy egy span attribútum attribútumait log. Támogatja a belefoglalás vagy kizárás vagy logkizárás span lehetőségét. A konfigurációs fájl által megadott sorrendben végrehajtott műveletek listáját veszi fel. A processzor a következő műveleteket támogatja:

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

insert

A insert művelet új attribútumot szúr be a telemetriai elembe, ahol még key nem létezik.

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

A insert művelethez a következő beállítások szükségesek:

  • key
  • Vagy vagy valuefromAttribute
  • action: insert

update

A update művelet frissíti az attribútumot a telemetriai elemben, ahol a key már létezik.

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

A update művelethez a következő beállítások szükségesek:

  • key
  • Vagy vagy valuefromAttribute
  • action: update

delete

A delete művelet egy attribútumot töröl egy telemetriai elemből.

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

A delete művelethez a következő beállítások szükségesek:

  • key
  • action: delete

hash

A hash művelet kivonata (SHA1) egy meglévő attribútumérték.

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

A hash művelethez a következő beállítások szükségesek:

  • key
  • action: hash

extract

Feljegyzés

A extract funkció csak a 3.0.2-es és újabb verziókban érhető el.

A extract művelet egy reguláris kifejezési szabály használatával nyeri ki az értékeket a bemeneti kulcsból a szabály által megadott célkulcsokhoz. Ha már létezik célkulcs, a extract művelet felülírja a célkulcsot. Ez a művelet úgy viselkedik, mint a span processzorbeállítástoAttributes , ahol a meglévő attribútum a forrás.

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

A extract művelethez a következő beállítások szükségesek:

  • key
  • pattern
  • action: extract

mask

Feljegyzés

A mask funkció csak a 3.2.5-ös és újabb verziókban érhető el.

A mask művelet maszkolja az attribútumértékeket az és replacea pattern .

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

A mask művelethez a következő beállítások szükségesek:

  • key
  • pattern
  • replace
  • action: mask

pattern tartalmazhat egy elnevezett csoportot, amely az ?< és >:a között van elhelyezve. Példa: (?<userGroupName>[a-zA-Z.:\/]+)\d+? A csoport a (?<userGroupName>[a-zA-Z.:\/]+) csoport neve és userGroupName neve. pattern ezután a maszk közé ${ helyezett és } azt követő elnevezett csoportot is tartalmazhatja. Példa arra, hogy a maszk **: ${userGroupName}**.

A Telemetria-processzorra vonatkozó példák a maszkolásra vonatkozó példákat ismertetik.

Feltételek belefoglalása és feltétel kizárása

Az attribútumprocesszorok támogatják az opcionális include és exclude a kritériumokat. Az attribútumfeldolgozó csak olyan telemetriára lesz alkalmazva, amely megfelel a include feltételeknek (ha elérhető), és nem felel meg a feltételeknek exclude (ha elérhető).

A beállítás includeexclude konfigurálásához adjon meg legalább egyet matchTypespanNamesattributesvagy mindkettőt. A include vagy exclude konfiguráció több megadott feltételt is lehetővé tesz. Minden megadott feltételnek igaz értékre kell értékelnie, hogy egyezést eredményezjen.

  • Kötelező mezők:

    • matchType A tömbök és spanNamesattributes tömbök elemeinek értelmezését szabályozza. A lehetséges értékek a következők: regexp és strict. A reguláris kifejezésegyezések a teljes attribútumértéken lesznek végrehajtva, ezért ha egy tetszőleges helyen lévő abc értéket szeretne egyezni, akkor a függvényt kell használnia .*abc.*.
  • Választható mezők:

    • spanNames legalább egy elemnek meg kell egyeznie.
    • attributes az egyező attribútumok listáját adja meg. Ezeknek az attribútumoknak pontosan egyezniük kell ahhoz, hogy egyezést eredményezhessenek.

Feljegyzés

Ha mindkettő include meg exclude van adva, a include tulajdonságok ellenőrzése előtt a rendszer ellenőrzi a exclude tulajdonságokat.

Feljegyzés

Ha a vagy exclude a include konfiguráció nincs spanNames megadva, akkor a rendszer a megfelelő feltételeket alkalmazza mind a kettőre, mind spanslogsa .

Mintahasználat

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

További információ: Telemetriafeldolgozó példák.

Span processzor

A span processzor a span neve alapján módosítja a span nevét vagy attribútumait. Támogatja a spanok belefoglalását vagy kizárását.

Span elnevezése

A name szakaszhoz szükség van a beállításra fromAttributes . Az attribútumok értékei egy új név létrehozásához használatosak, a konfiguráció által megadott sorrendben összefűzve. A processzor csak akkor módosítja a span nevet, ha az összes attribútum megtalálható a spanon.

A separator beállítás nem kötelező. Ez a beállítás egy sztring, és használhat felosztott értékeket.

Feljegyzés

Ha az átnevezés az attribútum-feldolgozóra támaszkodik az attribútumok módosításához, győződjön meg arról, hogy a span processzor a folyamat specifikációjában szereplő attribútumok processzora után van megadva.

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

Attribútumok kinyerése a span névből

A toAttributes szakasz felsorolja azokat a reguláris kifejezéseket, amelyek megfelelnek a span névnek. Alkifejezések alapján nyeri ki az attribútumokat.

A rules beállítás megadása kötelező. Ez a beállítás felsorolja azokat a szabályokat, amelyek attribútumértékeket nyernek ki a span névből.

A kinyert attribútumnevek felülírják a span név értékeit. A lista minden szabálya egy regex mintasztring.

A kinyert attribútumnevek így cserélik le az értékeket:

  1. A tartománynév a regexben van bejelölve.
  2. A regex összes elnevezett alkifejezése attribútumként lesz kinyerve, ha a regex egyezik.
  3. A kinyert attribútumok hozzá lesznek adva a spanhoz.
  4. Minden alexpressziós név attribútumnévvé válik.
  5. A szubexpresszióval egyező rész lesz az attribútum értéke.
  6. A kinyert attribútum neve lecseréli a span név egyező részét. Ha az attribútumok már léteznek a spanban, felülírja őket.

Ez a folyamat a megadott sorrendben ismétlődik az összes szabály esetében. Minden további szabály az előző szabály kimenetét képező span névvel működik.

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

Gyakori span attribútumok

Ez a szakasz felsorol néhány gyakori span attribútumot, amelyeket a telemetriai processzorok használhatnak.

HTTP-tartományok

Attribútum Típus Leírás
http.request.method (régen http.method) húr HTTP-kérési módszer.
url.full (ügyfél span) vagy url.path (kiszolgálói span) (korábban http.url) húr Teljes HTTP-kérelem URL-címe az űrlapon scheme://host[:port]/path?query[#fragment]. A töredék általában nem HTTP-en keresztül kerül továbbításra. Ha azonban a töredék ismert, azt is bele kell foglalni.
http.response.status_code (régen http.status_code) szám HTTP-válasz állapotkódja.
network.protocol.version (régen http.flavor) húr A HTTP protokoll típusa.
user_agent.original (régen http.user_agent) húr Az ügyfél által küldött HTTP User-Agent fejléc értéke.

Java Database Csatlakozás ivity spans

Az alábbi táblázat a Java Database Csatlakozás ivity (JDBC) esetében használható attribútumokat ismerteti:

Attribútum Típus Leírás
db.system húr A használt adatbázis-kezelő rendszer (DBMS) termék azonosítója. Lásd az adatbázis-műveletek szemantikai konvencióit.
db.connection_string húr az adatbázishoz való csatlakozáshoz használt Csatlakozás ion sztring. Javasoljuk, hogy távolítsa el a beágyazott hitelesítő adatokat.
db.user húr Felhasználónév az adatbázis eléréséhez.
db.name húr A hozzáférés alatt álló adatbázis nevének jelentésére használt sztring. Az adatbázist kapcsoló parancsok esetében ezt a sztringet a céladatbázisra kell állítani, még akkor is, ha a parancs meghiúsul.
db.statement húr Futtatott adatbázis-utasítás.

Feltételek belefoglalása és feltétel kizárása

A span processzorok támogatják az opcionális include és exclude a kritériumokat. A span processzor csak olyan telemetriára lesz alkalmazva, amely megfelel a include feltételeknek (ha elérhető), és nem felel meg a feltételeknek exclude (ha elérhető).

Ennek a beállításnak includeexclude a konfigurálásához adjon meg legalább egyet matchTypespanNames vagy mindkettőt attributes. A include vagy exclude konfiguráció több megadott feltételt is lehetővé tesz. Minden megadott feltételnek igaz értékre kell értékelnie, hogy egyezést eredményezjen.

  • Kötelező mezők:

    • matchType A tömbök és spanNamesattributes tömbök elemeinek értelmezését szabályozza. A lehetséges értékek a következők: regexp és strict. A reguláris kifejezésegyezések a teljes attribútumértéken lesznek végrehajtva, ezért ha egy tetszőleges helyen lévő abc értéket szeretne egyezni, akkor a függvényt kell használnia .*abc.*.
  • Választható mezők:

    • spanNames legalább egy elemnek meg kell egyeznie.
    • attributes az egyező attribútumok listáját adja meg. Ezeknek az attribútumoknak pontosan egyezniük kell ahhoz, hogy egyezést eredményezhessenek.

Feljegyzés

Ha mindkettő include meg exclude van adva, a include tulajdonságok ellenőrzése előtt a rendszer ellenőrzi a exclude tulajdonságokat.

Mintahasználat

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

További információ: Telemetriafeldolgozó példák.

Naplófeldolgozó

Feljegyzés

A naplófeldolgozók a 3.1.1-es verziótól érhetők el.

A naplófeldolgozó módosítja a naplóüzenet törzsét vagy a napló attribútumait a naplóüzenet törzse alapján. Támogatja a naplók belefoglalását vagy kizárását.

Naplóüzenet törzsének frissítése

A body szakaszhoz szükség van a beállításra fromAttributes . Az attribútumok értékei egy új törzs létrehozására szolgálnak, a konfiguráció által megadott sorrendben összefűzve. A processzor csak akkor módosítja a napló törzsét, ha az összes attribútum megtalálható a naplóban.

A separator beállítás nem kötelező. Ez a beállítás egy sztring. Megadhatja az értékek felosztásához.

Feljegyzés

Ha az átnevezés az attribútum-feldolgozóra támaszkodik az attribútumok módosításához, győződjön meg arról, hogy a naplófeldolgozó a folyamat specifikációjában szereplő attribútumfeldolgozó után van megadva.

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

Attribútumok kinyerése a naplóüzenet törzséből

A toAttributes szakasz felsorolja a naplóüzenet törzsének megfelelő reguláris kifejezéseket. Alkifejezések alapján nyeri ki az attribútumokat.

A rules beállítás megadása kötelező. Ez a beállítás felsorolja az attribútumértékek törzsből való kinyeréséhez használt szabályokat.

A kinyert attribútumnevek felülírják a naplóüzenet törzsében lévő értékeket. A lista minden szabálya egy regex mintasztring.

A kinyert attribútumnevek így cserélik le az értékeket:

  1. A rendszer ellenőrzi a naplóüzenet törzsét a regexen.
  2. A regex összes elnevezett alkifejezése attribútumként lesz kinyerve, ha a regex egyezik.
  3. A kinyert attribútumok hozzá lesznek adva a naplóhoz.
  4. Minden alexpressziós név attribútumnévvé válik.
  5. A szubexpresszióval egyező rész lesz az attribútum értéke.
  6. A kinyert attribútum neve lecseréli a naplónév egyező részét. Ha az attribútumok már léteznek a naplóban, a rendszer felülírja őket.

Ez a folyamat a megadott sorrendben ismétlődik az összes szabály esetében. Minden további szabály az előző szabály kimenetét képező naplónéven működik.

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

Feltételek belefoglalása és feltétel kizárása

A naplófeldolgozók támogatják az opcionális include és exclude a feltételek megadását. A naplófeldolgozó csak olyan telemetriára lesz alkalmazva, amely megfelel a include feltételeknek (ha elérhető), és nem felel meg a feltételeknek exclude (ha elérhető).

A beállítás includeexclude konfigurálásához adja meg a és attributesa matchType (vagy mindkettő) beállítást. A include vagy exclude konfiguráció több megadott feltételt is lehetővé tesz. Minden megadott feltételnek igaz értékre kell értékelnie, hogy egyezést eredményezjen.

  • Kötelező mező:
    • matchType A tömbök elemeinek attributes értelmezését szabályozza. A lehetséges értékek a következők: regexp és strict. A reguláris kifejezésegyezések a teljes attribútumértéken lesznek végrehajtva, ezért ha egy tetszőleges helyen lévő abc értéket szeretne egyezni, akkor a függvényt kell használnia .*abc.*.
    • attributes az egyező attribútumok listáját adja meg. Ezeknek az attribútumoknak pontosan egyezniük kell ahhoz, hogy egyezést eredményezhessenek.

Feljegyzés

Ha mindkettő include meg exclude van adva, a include tulajdonságok ellenőrzése előtt a rendszer ellenőrzi a exclude tulajdonságokat.

Feljegyzés

A naplófeldolgozók nem támogatják spanNamesa .

Mintahasználat

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

További információ: Telemetriafeldolgozó példák.

Metrikaszűrő

Feljegyzés

A metrikaszűrők a 3.1.1-es verziótól érhetők el.

A metrikaszűrők bizonyos metrikák kizárására szolgálnak a betöltési költségek szabályozásához.

A metrikaszűrők csak a feltételeket támogatják exclude . A feltételeknek megfelelő exclude metrikák nem lesznek exportálva.

Ennek a beállításnak a konfigurálásához adja excludemeg az egyiket vagy többetmetricNames.matchType

  • Kötelező mező:
    • matchType a beszúrt metricNames elemek egyeztetését szabályozza. A lehetséges értékek a következők: regexp és strict. A reguláris kifejezésegyezések a teljes attribútumértéken lesznek végrehajtva, ezért ha egy tetszőleges helyen lévő abc értéket szeretne egyezni, akkor a függvényt kell használnia .*abc.*.
    • metricNames legalább egy elemnek meg kell egyeznie.

Mintahasználat

Az alábbi minta bemutatja, hogyan zárhat ki "metricA" és "metricB" nevű metrikákat:

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

Az alábbi minta bemutatja, hogyan kapcsolhatja ki az összes metrikát, beleértve az alapértelmezett automatikusan kiszúrt teljesítménymetrikákat, például a processzort és a memóriát.

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

A Java-ügynök által rögzített alapértelmezett metrikák

Metrika neve Metrika típusa Leírás Szűrhető
Current Thread Count egyéni metrikák Lásd: ThreadMXBean.getThreadCount(). igen
Loaded Class Count egyéni metrikák Lásd: ClassLoadingMXBean.getLoadedClassCount(). igen
GC Total Count egyéni metrikák A GarbageCollectorMXBean összes példányának száma (a legutóbbi jelentés óta diff). Lásd: GarbageCollectorMXBean.getCollectionCount(). igen
GC Total Time egyéni metrikák Az összes GarbageCollectorMXBean-példány időösszege (diff a legutóbbi jelentés óta). Lásd: GarbageCollectorMXBean.getCollectionTime(). igen
Heap Memory Used (MB) egyéni metrikák Lásd: MemoryMXBean.getHeapMemoryUsage().getUsed(). igen
% Of Max Heap Memory Used egyéni metrikák java.lang:type=Memória / maximális memóriamennyiség bájtban. Lásd: MemoryUsage igen
\Processor(_Total)\% Processor Time alapértelmezett metrikák A rendszerszintű processzorterhelés-számlálók (csak felhasználó és rendszer) különbsége a logikai processzorok számával egy adott időintervallumban nem
\Process(??APP_WIN32_PROC??)\% Processor Time alapértelmezett metrikák Lásd: OperatingSystemMXBean.getProcessCpuTime() (diff a legutóbbi jelentés óta, idő és cpu-k száma normalizálva). nem
\Process(??APP_WIN32_PROC??)\Private Bytes alapértelmezett metrikák A MemoryMXBean.getHeapMemoryUsage() és a MemoryMXBean.getNonHeapMemoryUsage()összege. nem
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec alapértelmezett metrikák /proc/[pid]/io A folyamat által beolvasott és írt bájtok összege (diff a legutóbbi jelentés óta). Lásd: proc(5). nem
\Memory\Available Bytes alapértelmezett metrikák Lásd: OperatingSystemMXBean.getFreePhysicalMemorySize(). nem

Gyakori kérdések

Miért nem dolgozza fel a naplófeldolgozó a naplófájlokat a TelemetryClient.trackTrace() használatával?

A TelemetryClient.trackTrace() az alkalmazás Elemzések klasszikus SDK-híd része, és a naplóprocesszorok csak az új OpenTelemetry-alapú eszközkészlettel működnek.