Telemetrieprocessors (preview) - Azure Monitor Application Insights voor Java
Notitie
De functie telemetrieprocessors is aangewezen als preview omdat we geen compatibiliteit met eerdere versies kunnen garanderen van release naar release vanwege de experimentele status van de semantische kenmerkconventies. De functie is echter getest en wordt ondersteund in productie.
Application Insights Java 3.x kan telemetriegegevens verwerken voordat de gegevens worden geëxporteerd.
Enkele gebruiksvoorbeelden:
- Gevoelige gegevens maskeren.
- Aangepaste dimensies voorwaardelijk toevoegen.
- Werk de spannaam bij, die wordt gebruikt voor het aggregeren van vergelijkbare telemetrie in Azure Portal.
- Verwijder specifieke spankenmerken om de opnamekosten te beheren.
- Filter enkele metrische gegevens om de opnamekosten te beheren.
Notitie
Als u specifieke (hele) periodes wilt verwijderen voor het beheren van opnamekosten, raadpleegt u steekproefoverschrijvingen.
Terminologie
Voordat u meer te weten komt over telemetrieprocessors, moet u inzicht krijgen in de termenspanne en het logboek.
Een bereik is een type telemetrie dat een van de volgende vertegenwoordigt:
- Een binnenkomende aanvraag.
- Een uitgaande afhankelijkheid (bijvoorbeeld een externe aanroep naar een andere service).
- Een in-process afhankelijkheid (bijvoorbeeld werk dat wordt uitgevoerd door subonderdelen van de service).
Een logboek is een type telemetrie dat het volgende voorstelt:
- logboekgegevens vastgelegd vanuit Log4j, Logback en java.util.logging
Voor telemetrieprocessors zijn deze span-/logboekonderdelen belangrijk:
- Naam
- Hoofdtekst
- Kenmerken
De spannaam is de primaire weergave voor aanvragen en afhankelijkheden in Azure Portal. Spankenmerken vertegenwoordigen zowel standaard- als aangepaste eigenschappen van een bepaalde aanvraag of afhankelijkheid.
Het traceringsbericht of de hoofdtekst is de primaire weergave voor logboeken in Azure Portal. Logboekkenmerken vertegenwoordigen zowel standaard- als aangepaste eigenschappen van een bepaald logboek.
Telemetrieprocessortypen
Momenteel zijn de vier typen telemetrieprocessors
- Kenmerkprocessors
- Spanprocessors
- Logboekprocessors
- Metrische filters
Een kenmerkprocessor kan kenmerken van een telemetrie-item (span
of log
) invoegen, bijwerken, verwijderen of hashen.
Het kan ook een reguliere expressie gebruiken om een of meer nieuwe kenmerken uit een bestaand kenmerk te extraheren.
Een spanprocessor kan de telemetrienaam van aanvragen en afhankelijkheden bijwerken. Het kan ook een reguliere expressie gebruiken om een of meer nieuwe kenmerken uit de spannaam te extraheren.
Een logboekprocessor kan de telemetrienaam van logboeken bijwerken. Het kan ook een reguliere expressie gebruiken om een of meer nieuwe kenmerken uit de logboeknaam te extraheren.
Een filter voor metrische gegevens kan metrische gegevens filteren om de opnamekosten te beheren.
Notitie
Op dit moment verwerken telemetrieprocessors alleen kenmerken van het type tekenreeks. Ze verwerken geen kenmerken van het type Booleaanse waarde of getal.
Aan de slag
Maak eerst een configuratiebestand met de naam applicationinsights.json. Sla deze op in dezelfde map als applicationinsights-agent-*.jar. Gebruik de volgende sjabloon.
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
...
},
{
"type": "attribute",
...
},
{
"type": "span",
...
},
{
"type": "log",
...
},
{
"type": "metric-filter",
...
}
]
}
}
Kenmerkprocessor
De kenmerkprocessor wijzigt kenmerken van een span
of een log
. Het kan ondersteuning bieden voor de mogelijkheid om op te nemen of uit te sluiten span
of .log
Er wordt een lijst uitgevoerd met acties die worden uitgevoerd in de volgorde waarin het configuratiebestand is opgegeven. De processor ondersteunt deze acties:
insert
update
delete
hash
extract
mask
insert
Met insert
de actie wordt een nieuw kenmerk ingevoegd in het telemetrie-item waar het key
nog niet bestaat.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"value": "value1",
"action": "insert"
}
]
}
]
Voor de insert
actie zijn de volgende instellingen vereist:
key
value
offromAttribute
action
:insert
update
Met de update
actie wordt een kenmerk bijgewerkt in telemetrie-item waar het key
al bestaat.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"value": "newValue",
"action": "update"
}
]
}
]
Voor de update
actie zijn de volgende instellingen vereist:
key
value
offromAttribute
action
:update
delete
Met de delete
actie wordt een kenmerk uit een telemetrie-item verwijderd.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"action": "delete"
}
]
}
]
Voor de delete
actie zijn de volgende instellingen vereist:
key
action
:delete
hash
De hash
actie-hashes (SHA1) een bestaande kenmerkwaarde.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"action": "hash"
}
]
}
]
Voor de hash
actie zijn de volgende instellingen vereist:
key
action
:hash
extract
Notitie
De extract
functie is alleen beschikbaar in versie 3.0.2 en hoger.
Met extract
de actie worden waarden geëxtraheerd met behulp van een reguliere expressieregel van de invoersleutel naar doelsleutels die door de regel worden opgegeven. Als er al een doelsleutel bestaat, overschrijft de extract
actie de doelsleutel. Deze actie gedraagt zich als de instelling voor de spanprocessortoAttributes
, waarbij het bestaande kenmerk de bron is.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"pattern": "<regular pattern with named matchers>",
"action": "extract"
}
]
}
]
Voor de extract
actie zijn de volgende instellingen vereist:
key
pattern
action
:extract
mask
Notitie
De mask
functie is alleen beschikbaar in versie 3.2.5 en hoger.
De mask
actie maskert kenmerkwaarden met behulp van een reguliere expressieregel die is opgegeven in de pattern
en replace
.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attributeName",
"pattern": "<regular expression pattern>",
"replace": "<replacement value>",
"action": "mask"
}
]
}
]
Voor de mask
actie zijn de volgende instellingen vereist:
key
pattern
replace
action
:mask
pattern
kan een benoemde groep bevatten tussen ?<
en >:
. Voorbeeld: (?<userGroupName>[a-zA-Z.:\/]+)\d+
? De groep is (?<userGroupName>[a-zA-Z.:\/]+)
en userGroupName
is de naam van de groep. pattern
kan vervolgens dezelfde benoemde groep bevatten tussen ${
en }
gevolgd door het masker. Voorbeeld waarbij het masker ** is: ${userGroupName}**
.
Zie voorbeelden van telemetrieprocessor voor maskeringsvoorbeelden.
Criteria opnemen en criteria uitsluiten
Kenmerkprocessors ondersteunen optioneel include
en exclude
criteria.
Een kenmerkprocessor wordt alleen toegepast op telemetrie die voldoet aan de include
criteria (als deze beschikbaar is) en niet voldoet aan de exclude
criteria (als deze beschikbaar is).
Als u deze optie wilt configureren, geeft u onder include
of exclude
(of beide) ten minste één matchType
en een spanNames
of attributes
.
De include
of exclude
configuratie staat meer dan één opgegeven voorwaarde toe.
Alle opgegeven voorwaarden moeten waar zijn om te resulteren in een overeenkomst.
Vereiste velden:
matchType
bepaalt hoe items inspanNames
matrices enattributes
matrices worden geïnterpreteerd. Mogelijke waarden zijnregexp
enstrict
. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken dieabc
ergens in de expressie staat, moet u deze gebruiken.*abc.*
.
Optionele velden:
spanNames
moet overeenkomen met ten minste één van de items.attributes
hiermee geeft u de lijst met kenmerken die overeenkomen. Al deze kenmerken moeten exact overeenkomen om te resulteren in een overeenkomst.
Notitie
Als beide include
en exclude
zijn opgegeven, worden de include
eigenschappen gecontroleerd voordat de exclude
eigenschappen worden gecontroleerd.
Notitie
Als de include
of exclude
configuratie niet is spanNames
opgegeven, worden de overeenkomende criteria toegepast op beide spans
en logs
.
Voorbeeldgebruik
"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"
}
]
}
]
Zie voorbeelden van telemetrieprocessor voor meer informatie.
Spanprocessor
De spanprocessor wijzigt de spannaam of -kenmerken van een span op basis van de spannaam. Het kan ondersteuning bieden voor de mogelijkheid om spanten op te nemen of uit te sluiten.
Een spannaam opgeven
Voor name
de sectie is de fromAttributes
instelling vereist. De waarden van deze kenmerken worden gebruikt om een nieuwe naam te maken, samengevoegd in de volgorde waarin de configuratie is opgegeven. De processor wijzigt alleen de spannaam als al deze kenmerken aanwezig zijn op de span.
De separator
instelling is optioneel. Deze instelling is een tekenreeks en u kunt gesplitste waarden gebruiken.
Notitie
Als de naamwijziging afhankelijk is van de kenmerkenprocessor om kenmerken te wijzigen, moet u ervoor zorgen dat de spanprocessor is opgegeven na de kenmerkenprocessor in de pijplijnspecificatie.
"processors": [
{
"type": "span",
"name": {
"fromAttributes": [
"attributeKey1",
"attributeKey2",
],
"separator": "::"
}
}
]
Kenmerken extraheren uit de spannaam
De toAttributes
sectie bevat de reguliere expressies die overeenkomen met de naam van het bereik. Het extraheert kenmerken op basis van subexpressies.
De rules
instelling is vereist. Deze instelling bevat de regels die worden gebruikt om kenmerkwaarden uit de spannaam te extraheren.
Uitgepakte kenmerknamen vervangen de waarden in de spannaam. Elke regel in de lijst is een reguliere expressiepatroontekenreeks (regex).
Hier ziet u hoe geëxtraheerde kenmerknamen waarden vervangen:
- De spannaam wordt gecontroleerd aan de hand van de regex.
- Alle benoemde subexpressies van de regex worden geëxtraheerd als kenmerken als de regex overeenkomt.
- De geëxtraheerde kenmerken worden toegevoegd aan het bereik.
- Elke subexpressienaam wordt een kenmerknaam.
- Het overeenkomende gedeelte van de subexpressie wordt de kenmerkwaarde.
- De geëxtraheerde kenmerknaam vervangt het overeenkomende gedeelte in de spannaam. Als de kenmerken al in de periode bestaan, worden ze overschreven.
Dit proces wordt herhaald voor alle regels in de volgorde waarin ze zijn opgegeven. Elke volgende regel werkt op de spannaam die de uitvoer van de vorige regel is.
"processors": [
{
"type": "span",
"name": {
"toAttributes": {
"rules": [
"rule1",
"rule2",
"rule3"
]
}
}
}
]
Algemene spankenmerken
In deze sectie vindt u enkele algemene spankenmerken die telemetrieprocessors kunnen gebruiken.
HTTP-spans
Kenmerk | Type | Description |
---|---|---|
http.request.method (vroeger )http.method |
tekenreeks | HTTP-aanvraagmethode. |
url.full (clientspanne) of url.path (serverspanne) (voorheen http.url ) |
tekenreeks | Volledige HTTP-aanvraag-URL in het formulier scheme://host[:port]/path?query[#fragment] . Het fragment wordt doorgaans niet verzonden via HTTP. Maar als het fragment bekend is, moet het worden opgenomen. |
http.response.status_code (vroeger )http.status_code |
Nummer | HTTP-antwoordstatuscode. |
network.protocol.version (vroeger )http.flavor |
tekenreeks | Type HTTP-protocol. |
user_agent.original (vroeger )http.user_agent |
tekenreeks | Waarde van de HTTP User-Agent-header die door de client wordt verzonden. |
Connectiviteit van Java Database omvat
In de volgende tabel worden kenmerken beschreven die u kunt gebruiken in JDBC-periodes (Java Database Connectivity):
Kenmerk | Type | Omschrijving |
---|---|---|
db.system |
tekenreeks | Id voor het DBMS-product (Database Management System) dat wordt gebruikt. Zie Semantische conventies voor databasebewerkingen. |
db.connection_string |
tekenreeks | Verbindingsreeks die wordt gebruikt om verbinding te maken met de database. U wordt aangeraden ingesloten referenties te verwijderen. |
db.user |
tekenreeks | Gebruikersnaam voor toegang tot de database. |
db.name |
tekenreeks | Tekenreeks die wordt gebruikt voor het rapporteren van de naam van de database die wordt geopend. Voor opdrachten die de database veranderen, moet deze tekenreeks worden ingesteld op de doeldatabase, zelfs als de opdracht mislukt. |
db.statement |
tekenreeks | Database-instructie die wordt uitgevoerd. |
Criteria opnemen en criteria uitsluiten
Spanprocessors ondersteunen optioneel include
en exclude
criteria.
Een spanprocessor wordt alleen toegepast op telemetrie die voldoet aan de include
criteria (als deze beschikbaar is) en niet voldoet aan de exclude
criteria (als deze beschikbaar is).
Als u deze optie wilt configureren, geeft include
u onder of exclude
(of beide) ten minste één matchType
en spanNames
een of meerdere opties attributes
op.
De include
of exclude
configuratie staat meer dan één opgegeven voorwaarde toe.
Alle opgegeven voorwaarden moeten waar zijn om te resulteren in een overeenkomst.
Vereiste velden:
matchType
bepaalt hoe items inspanNames
matrices enattributes
matrices worden geïnterpreteerd. Mogelijke waarden zijnregexp
enstrict
. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken dieabc
ergens in de expressie staat, moet u deze gebruiken.*abc.*
.
Optionele velden:
spanNames
moet overeenkomen met ten minste één van de items.attributes
hiermee geeft u de lijst met kenmerken die overeenkomen. Al deze kenmerken moeten exact overeenkomen om te resulteren in een overeenkomst.
Notitie
Als beide include
en exclude
zijn opgegeven, worden de include
eigenschappen gecontroleerd voordat de exclude
eigenschappen worden gecontroleerd.
Voorbeeldgebruik
"processors": [
{
"type": "span",
"include": {
"matchType": "strict",
"spanNames": [
"spanA",
"spanB"
]
},
"exclude": {
"matchType": "strict",
"attributes": [
{
"key": "attribute1",
"value": "attributeValue1"
}
]
},
"name": {
"toAttributes": {
"rules": [
"rule1",
"rule2",
"rule3"
]
}
}
}
]
Zie voorbeelden van telemetrieprocessor voor meer informatie.
Logboekprocessor
Notitie
Logboekprocessors zijn beschikbaar vanaf versie 3.1.1.
De logboekprocessor wijzigt de hoofdtekst van het logboekbericht of de kenmerken van een logboek op basis van de hoofdtekst van het logboekbericht. Het kan ondersteuning bieden voor de mogelijkheid om logboeken op te nemen of uit te sluiten.
Hoofdtekst van logboekbericht bijwerken
Voor body
de sectie is de fromAttributes
instelling vereist. De waarden van deze kenmerken worden gebruikt om een nieuwe hoofdtekst te maken, samengevoegd in de volgorde waarin de configuratie is opgegeven. De processor wijzigt alleen de hoofdtekst van het logboek als al deze kenmerken aanwezig zijn in het logboek.
De separator
instelling is optioneel. Deze instelling is een tekenreeks. U kunt deze opgeven om waarden te splitsen.
Notitie
Als de naamwijziging afhankelijk is van de kenmerkenprocessor om kenmerken te wijzigen, moet u ervoor zorgen dat de logboekprocessor is opgegeven na de kenmerkenprocessor in de pijplijnspecificatie.
"processors": [
{
"type": "log",
"body": {
"fromAttributes": [
"attributeKey1",
"attributeKey2",
],
"separator": "::"
}
}
]
Kenmerken extraheren uit de hoofdtekst van het logboekbericht
De toAttributes
sectie bevat de reguliere expressies die overeenkomen met de hoofdtekst van het logboekbericht. Het extraheert kenmerken op basis van subexpressies.
De rules
instelling is vereist. Deze instelling bevat de regels die worden gebruikt om kenmerkwaarden uit de hoofdtekst te extraheren.
Uitgepakte kenmerknamen vervangen de waarden in de hoofdtekst van het logboekbericht. Elke regel in de lijst is een reguliere expressiepatroontekenreeks (regex).
Hier ziet u hoe geëxtraheerde kenmerknamen waarden vervangen:
- De hoofdtekst van het logboekbericht wordt gecontroleerd aan de hand van de regex.
- Alle benoemde subexpressies van de regex worden geëxtraheerd als kenmerken als de regex overeenkomt.
- De geëxtraheerde kenmerken worden toegevoegd aan het logboek.
- Elke subexpressienaam wordt een kenmerknaam.
- Het overeenkomende gedeelte van de subexpressie wordt de kenmerkwaarde.
- De geëxtraheerde kenmerknaam vervangt het overeenkomende gedeelte in de logboeknaam. Als de kenmerken al aanwezig zijn in het logboek, worden ze overschreven.
Dit proces wordt herhaald voor alle regels in de volgorde waarin ze zijn opgegeven. Elke volgende regel werkt op de logboeknaam die de uitvoer van de vorige regel is.
"processors": [
{
"type": "log",
"body": {
"toAttributes": {
"rules": [
"rule1",
"rule2",
"rule3"
]
}
}
}
]
Criteria opnemen en criteria uitsluiten
Logboekprocessors ondersteunen optioneel include
en exclude
criteria.
Een logboekprocessor wordt alleen toegepast op telemetrie die voldoet aan de include
criteria (als deze beschikbaar is) en niet voldoet aan de exclude
criteria (als deze beschikbaar is).
Als u deze optie wilt configureren, geeft u onder include
of exclude
(of beide) het matchType
en attributes
.
De include
of exclude
configuratie staat meer dan één opgegeven voorwaarde toe.
Alle opgegeven voorwaarden moeten waar zijn om te resulteren in een overeenkomst.
- Vereist veld:
matchType
bepaalt hoe items inattributes
matrices worden geïnterpreteerd. Mogelijke waarden zijnregexp
enstrict
. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken dieabc
ergens in de expressie staat, moet u deze gebruiken.*abc.*
.attributes
hiermee geeft u de lijst met kenmerken die overeenkomen. Al deze kenmerken moeten exact overeenkomen om te resulteren in een overeenkomst.
Notitie
Als beide include
en exclude
zijn opgegeven, worden de include
eigenschappen gecontroleerd voordat de exclude
eigenschappen worden gecontroleerd.
Notitie
Logboekprocessors bieden geen ondersteuning spanNames
voor .
Voorbeeldgebruik
"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"
]
}
}
}
]
Zie voorbeelden van telemetrieprocessor voor meer informatie.
Filter voor metrische gegevens
Notitie
Metrische filters zijn beschikbaar vanaf versie 3.1.1.
Metrische filters worden gebruikt om bepaalde metrische gegevens uit te sluiten om de opnamekosten te beheren.
Metrische filters ondersteunen exclude
alleen criteria. Metrische gegevens die voldoen aan de exclude
criteria worden niet geëxporteerd.
Als u deze optie wilt configureren, geeft u onder exclude
de optie een matchType
of meer metricNames
op.
- Vereist veld:
matchType
bepaalt hoe items overeenkomenmetricNames
. Mogelijke waarden zijnregexp
enstrict
. Reguliere expressieovereenkomsten worden uitgevoerd op basis van de gehele kenmerkwaarde, dus als u een waarde wilt vergelijken dieabc
ergens in de expressie staat, moet u deze gebruiken.*abc.*
.metricNames
moet overeenkomen met ten minste één van de items.
Voorbeeldgebruik
In het volgende voorbeeld ziet u hoe u metrische gegevens kunt uitsluiten met de namen 'metricA' en 'metricB':
"processors": [
{
"type": "metric-filter",
"exclude": {
"matchType": "strict",
"metricNames": [
"metricA",
"metricB"
]
}
}
]
In het volgende voorbeeld ziet u hoe u alle metrische gegevens uitschakelt, inclusief de standaard metrische gegevens voor automatisch opgehaalde prestaties, zoals cpu en geheugen.
"processors": [
{
"type": "metric-filter",
"exclude": {
"matchType": "regexp",
"metricNames": [
".*"
]
}
}
]
Standaard metrische gegevens die zijn vastgelegd door Java-agent
Naam van meetwaarde | Type metrische gegevens | Beschrijving | Filterbaar |
---|---|---|---|
Current Thread Count |
aangepaste metrische gegevens | Zie ThreadMXBean.getThreadCount(). | ja |
Loaded Class Count |
aangepaste metrische gegevens | Zie ClassLoadingMXBean.getLoadedClassCount(). | ja |
GC Total Count |
aangepaste metrische gegevens | Som van aantallen voor alle GarbageCollectorMXBean-exemplaren (diff sinds laatst gerapporteerd). Zie GarbageCollectorMXBean.getCollectionCount(). | ja |
GC Total Time |
aangepaste metrische gegevens | Som van de tijd voor alle GarbageCollectorMXBean-exemplaren (diff sinds laatst gerapporteerd). Zie GarbageCollectorMXBean.getCollectionTime(). | ja |
Heap Memory Used (MB) |
aangepaste metrische gegevens | Zie MemoryMXBean.getHeapMemoryUsage().getUsed(). | ja |
% Of Max Heap Memory Used |
aangepaste metrische gegevens | java.lang:type=Geheugen/maximale hoeveelheid geheugen in bytes. Zie MemoryUsage | ja |
\Processor(_Total)\% Processor Time |
standaard metrische gegevens | Verschil in systeembrede CPU-belastingtellers (alleen gebruiker en systeem) gedeeld door het aantal logische processors in een bepaald tijdsinterval | nee |
\Process(??APP_WIN32_PROC??)\% Processor Time |
standaard metrische gegevens | Zie OperatingSystemMXBean.getProcessCpuTime() (diff sinds laatst gerapporteerd, genormaliseerd op tijd en aantal CPU's). | nee |
\Process(??APP_WIN32_PROC??)\Private Bytes |
standaard metrische gegevens | Som van MemoryMXBean.getHeapMemoryUsage() en MemoryMXBean.getNonHeapMemoryUsage(). | nee |
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec |
standaard metrische gegevens | /proc/[pid]/io Som van bytes die door het proces zijn gelezen en geschreven (diff sinds het laatst gerapporteerd). Zie proc(5). |
nee |
\Memory\Available Bytes |
standaard metrische gegevens | Zie OperatingSystemMXBean.getFreePhysicalMemorySize(). | nee |
Veelgestelde vragen
Waarom verwerkt de logboekprocessor logboekbestanden niet met behulp van TelemetryClient.trackTrace()?
TelemetryClient.trackTrace() maakt deel uit van de klassieke Application Insights SDK-brug en de logboekprocessors werken alleen met de nieuwe op OpenTelemetry gebaseerde instrumentatie.