Processori di telemetria (anteprima) - Application Insights per Monitoraggio di Azure per Java
Nota
La funzionalità dei processori di telemetria è designata come anteprima perché non è possibile garantire la compatibilità con le versioni precedenti dal rilascio al rilascio a causa dello stato sperimentale delle convenzioni semantiche degli attributi. Tuttavia, la funzionalità è stata testata ed è supportata nell'ambiente di produzione.
Application Insights Java 3.x può elaborare i dati di telemetria prima dell'esportazione dei dati.
Alcuni casi d'uso:
- Mascherare i dati sensibili.
- Aggiungere in modo condizionale dimensioni personalizzate.
- Aggiornare il nome dell'intervallo, usato per aggregare dati di telemetria simili nella portale di Azure.
- Eliminare attributi di intervallo specifici per controllare i costi di inserimento.
- Filtrare alcune metriche per controllare i costi di inserimento.
Nota
Per eliminare intervalli specifici (interi) per controllare i costi di inserimento, vedere Override del campionamento.
Terminologia
Prima di conoscere i processori di telemetria, è necessario comprendere i termini span e log.
Un intervallo è un tipo di telemetria che rappresenta una delle seguenti:
- Richiesta in ingresso.
- Dipendenza in uscita, ad esempio una chiamata remota a un altro servizio.
- Dipendenza in-process (ad esempio, il lavoro svolto dai sottocomponenti del servizio).
Un log è un tipo di telemetria che rappresenta:
- dati di log acquisiti da Log4j, Logback e java.util.logging
Per i processori di telemetria, questi componenti span/log sono importanti:
- Nome
- Corpo
- Attributi
Il nome dell'intervallo è la visualizzazione primaria per le richieste e le dipendenze nel portale di Azure. Gli attributi span rappresentano proprietà standard e personalizzate di una determinata richiesta o dipendenza.
Il messaggio di traccia o il corpo è la visualizzazione principale per i log nel portale di Azure. Gli attributi del log rappresentano proprietà standard e personalizzate di un determinato log.
Tipi di processore di telemetria
Attualmente, i quattro tipi di processori di telemetria sono
- Processori di attributi
- Processori span
- Processori di log
- Filtri delle metriche
Un processore di attributi può inserire, aggiornare, eliminare o hash attributi di un elemento di telemetria (span
o log
).
Può anche usare un'espressione regolare per estrarre uno o più nuovi attributi da un attributo esistente.
Un processore span può aggiornare il nome di telemetria delle richieste e delle dipendenze. Può anche usare un'espressione regolare per estrarre uno o più nuovi attributi dal nome dell'intervallo.
Un processore di log può aggiornare il nome dei dati di telemetria dei log. Può anche usare un'espressione regolare per estrarre uno o più nuovi attributi dal nome del log.
Un filtro delle metriche può filtrare le metriche per controllare i costi di inserimento.
Nota
Attualmente, i processori di telemetria elaborano solo gli attributi di tipo string. Non elaborano attributi di tipo Boolean o number.
Introduzione
Per iniziare, creare un file di configurazione denominato applicationinsights.json. Salvarlo nella stessa directory di applicationinsights-agent-*.jar. Usare il modello seguente.
{
"connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
"preview": {
"processors": [
{
"type": "attribute",
...
},
{
"type": "attribute",
...
},
{
"type": "span",
...
},
{
"type": "log",
...
},
{
"type": "metric-filter",
...
}
]
}
}
Processore di attributi
Il processore di attributi modifica gli attributi di un span
oggetto o .log
Può supportare la possibilità di includere o escludere span
o log
. Accetta un elenco di azioni eseguite nell'ordine specificato dal file di configurazione. Il processore supporta queste azioni:
insert
update
delete
hash
extract
mask
insert
L'azione insert
inserisce un nuovo attributo nell'elemento di telemetria in cui key
non esiste già .
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"value": "value1",
"action": "insert"
}
]
}
]
L'azione insert
richiede le impostazioni seguenti:
key
- Il valore può essere
value
ofromAttribute
action
:insert
update
L'azione update
aggiorna un attributo nell'elemento di telemetria in cui esiste key
già.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"value": "newValue",
"action": "update"
}
]
}
]
L'azione update
richiede le impostazioni seguenti:
key
- Il valore può essere
value
ofromAttribute
action
:update
delete
L'azione delete
elimina un attributo da un elemento di telemetria.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"action": "delete"
}
]
}
]
L'azione delete
richiede le impostazioni seguenti:
key
action
:delete
hash
L'hash hash
dell'azione (SHA1) è un valore di attributo esistente.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"action": "hash"
}
]
}
]
L'azione hash
richiede le impostazioni seguenti:
key
action
:hash
extract
Nota
La extract
funzionalità è disponibile solo nella versione 3.0.2 e successive.
L'azione extract
estrae i valori usando una regola di espressione regolare dalla chiave di input alle chiavi di destinazione specificate dalla regola. Se esiste già una chiave di destinazione, l'azione esegue l'override extract
della chiave di destinazione. Questa azione si comporta come l'impostazione del processoretoAttributes
span, in cui l'attributo esistente è l'origine.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attribute1",
"pattern": "<regular pattern with named matchers>",
"action": "extract"
}
]
}
]
L'azione extract
richiede le impostazioni seguenti:
key
pattern
action
:extract
mask
Nota
La mask
funzionalità è disponibile solo nella versione 3.2.5 e successive.
L'azione mask
maschera i valori dell'attributo pattern
usando una regola di espressione regolare specificata in e replace
.
"processors": [
{
"type": "attribute",
"actions": [
{
"key": "attributeName",
"pattern": "<regular expression pattern>",
"replace": "<replacement value>",
"action": "mask"
}
]
}
]
L'azione mask
richiede le impostazioni seguenti:
key
pattern
replace
action
:mask
pattern
può contenere un gruppo denominato posizionato tra ?<
e >:
. Esempio: (?<userGroupName>[a-zA-Z.:\/]+)\d+
? Il gruppo è (?<userGroupName>[a-zA-Z.:\/]+)
e userGroupName
è il nome del gruppo. pattern
può quindi contenere lo stesso gruppo denominato posizionato tra ${
e }
seguito dalla maschera. Esempio in cui la maschera è **: ${userGroupName}**
.
Vedere Esempi di processore di telemetria per esempi di mascheramento.
Includere criteri ed escludere criteri
I processori di attributi supportano criteri e exclude
facoltativiinclude
.
Un processore di attributi viene applicato solo ai dati di telemetria che soddisfano i relativi include
criteri (se disponibili) e non soddisfano i criteri exclude
(se disponibili).
Per configurare questa opzione, in include
o exclude
(o in entrambi), specificare almeno uno matchType
e spanNames
o attributes
.
La include
configurazione o exclude
consente più di una condizione specificata.
Tutte le condizioni specificate devono restituire true per ottenere una corrispondenza.
Campi obbligatori:
matchType
controlla il modo in cui vengono interpretati gli elementi inspanNames
matrici eattributes
matrici. I valori possibili sonoregexp
estrict
. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contieneabc
un punto qualsiasi, è necessario usare.*abc.*
.
Campi facoltativi:
spanNames
deve corrispondere ad almeno uno degli elementi.attributes
specifica l'elenco di attributi da associare. Tutti questi attributi devono corrispondere esattamente al risultato di una corrispondenza.
Nota
Se vengono specificati e include
exclude
, le include
proprietà vengono controllate prima che vengano controllate le exclude
proprietà.
Nota
Se la include
configurazione o exclude
non è spanNames
specificata, i criteri di corrispondenza vengono applicati sia spans
a che logs
a .
Esempio di utilizzo
"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"
}
]
}
]
Per altre informazioni, vedere Esempi di processore di telemetria.
Processore span
Il processore span modifica il nome dell'intervallo o gli attributi di un intervallo in base al nome dell'intervallo. Può supportare la possibilità di includere o escludere intervalli.
Assegnare un nome a span
La name
sezione richiede l'impostazione fromAttributes
. I valori di questi attributi vengono usati per creare un nuovo nome, concatenato nell'ordine specificato dalla configurazione. Il processore modifica il nome dell'intervallo solo se tutti questi attributi sono presenti nell'intervallo.
L'impostazione separator
è facoltativa. Questa impostazione è una stringa ed è possibile usare valori di divisione.
Nota
Se la ridenominazione si basa sul processore degli attributi per modificare gli attributi, assicurarsi che il processore span venga specificato dopo che il processore degli attributi nella specifica della pipeline.
"processors": [
{
"type": "span",
"name": {
"fromAttributes": [
"attributeKey1",
"attributeKey2",
],
"separator": "::"
}
}
]
Estrarre gli attributi dal nome dell'intervallo
Nella toAttributes
sezione sono elencate le espressioni regolari in modo che corrispondano al nome dell'intervallo. Estrae gli attributi in base alle sottoespressioni.
L'impostazione rules
è obbligatoria. Questa impostazione elenca le regole usate per estrarre i valori degli attributi dal nome dell'intervallo.
I nomi degli attributi estratti sostituiscono i valori nel nome dell'intervallo. Ogni regola nell'elenco è una stringa di criteri di espressione regolare (regex).
Ecco come i nomi degli attributi estratti sostituiscono i valori:
- Il nome dell'intervallo viene controllato rispetto all'espressione regolare.
- Tutte le sottoespressioni denominate dell'espressione regolare vengono estratte come attributi se l'espressione regolare corrisponde.
- Gli attributi estratti vengono aggiunti all'intervallo.
- Ogni nome di sottoespressione diventa un nome di attributo.
- La parte corrispondente alla sottoespressione diventa il valore dell'attributo.
- Il nome dell'attributo estratto sostituisce la parte corrispondente nel nome dell'intervallo. Se gli attributi esistono già nell'intervallo, vengono sovrascritti.
Questo processo viene ripetuto per tutte le regole nell'ordine in cui vengono specificate. Ogni regola successiva funziona sul nome dell'intervallo che rappresenta l'output della regola precedente.
"processors": [
{
"type": "span",
"name": {
"toAttributes": {
"rules": [
"rule1",
"rule2",
"rule3"
]
}
}
}
]
Attributi di intervallo comuni
Questa sezione elenca alcuni attributi di intervallo comuni che i processori di telemetria possono usare.
Intervalli HTTP
Attributo | Tipo | Descrizione |
---|---|---|
http.request.method (usato per essere http.method ) |
string | Metodo della richiesta HTTP. |
url.full (intervallo client) o url.path (intervallo server) (usato per essere http.url ) |
string | URL completo della richiesta HTTP nel formato scheme://host[:port]/path?query[#fragment] . Il frammento in genere non viene trasmesso tramite HTTP. Ma se il frammento è noto, deve essere incluso. |
http.response.status_code (usato per essere http.status_code ) |
number | Codice di stato della risposta HTTP. |
network.protocol.version (usato per essere http.flavor ) |
string | Tipo di protocollo HTTP. |
user_agent.original (usato per essere http.user_agent ) |
string | Valore dell'intestazione HTTP User-Agent inviata dal client. |
Intervalli di Connessione vità del database Java
La tabella seguente descrive gli attributi che è possibile usare negli intervalli JDBC (Java Database Connessione ivity):
Attributo | Tipo | Descrzione |
---|---|---|
db.system |
stringa | Identificatore del prodotto DBMS (Database Management System) in uso. Vedere Convenzioni semantiche per le operazioni di database. |
db.connection_string |
string | Connessione stringa utilizzata per connettersi al database. È consigliabile rimuovere le credenziali incorporate. |
db.user |
string | Nome utente per l'accesso al database. |
db.name |
string | Stringa utilizzata per segnalare il nome del database a cui si accede. Per i comandi che cambiano il database, questa stringa deve essere impostata sul database di destinazione, anche se il comando non riesce. |
db.statement |
string | Istruzione di database in esecuzione. |
Includere criteri ed escludere criteri
I processori span supportano i criteri e exclude
facoltativiinclude
.
Un processore span viene applicato solo ai dati di telemetria che soddisfano i criteri include
(se disponibili) e non soddisfano i criteri exclude
(se disponibili).
Per configurare questa opzione, in include
o exclude
(o entrambe), specificare almeno uno matchType
e spanNames
o span attributes
.
La include
configurazione o exclude
consente più di una condizione specificata.
Tutte le condizioni specificate devono restituire true per ottenere una corrispondenza.
Campi obbligatori:
matchType
controlla il modo in cui vengono interpretati gli elementi inspanNames
matrici eattributes
matrici. I valori possibili sonoregexp
estrict
. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contieneabc
un punto qualsiasi, è necessario usare.*abc.*
.
Campi facoltativi:
spanNames
deve corrispondere ad almeno uno degli elementi.attributes
specifica l'elenco di attributi da associare. Tutti questi attributi devono corrispondere esattamente al risultato di una corrispondenza.
Nota
Se vengono specificati e include
exclude
, le include
proprietà vengono controllate prima che vengano controllate le exclude
proprietà.
Esempio di utilizzo
"processors": [
{
"type": "span",
"include": {
"matchType": "strict",
"spanNames": [
"spanA",
"spanB"
]
},
"exclude": {
"matchType": "strict",
"attributes": [
{
"key": "attribute1",
"value": "attributeValue1"
}
]
},
"name": {
"toAttributes": {
"rules": [
"rule1",
"rule2",
"rule3"
]
}
}
}
]
Per altre informazioni, vedere Esempi di processore di telemetria.
Processore di log
Nota
I processori di log sono disponibili a partire dalla versione 3.1.1.
Il processore di log modifica il corpo del messaggio di log o gli attributi di un log in base al corpo del messaggio di log. Può supportare la possibilità di includere o escludere i log.
Aggiornare il corpo del messaggio del log
La body
sezione richiede l'impostazione fromAttributes
. I valori di questi attributi vengono usati per creare un nuovo corpo, concatenato nell'ordine specificato dalla configurazione. Il processore modifica il corpo del log solo se tutti questi attributi sono presenti nel log.
L'impostazione separator
è facoltativa. Questa impostazione è una stringa. È possibile specificarlo per suddividere i valori.
Nota
Se la ridenominazione si basa sul processore degli attributi per modificare gli attributi, assicurarsi che il processore di log venga specificato dopo il processore degli attributi nella specifica della pipeline.
"processors": [
{
"type": "log",
"body": {
"fromAttributes": [
"attributeKey1",
"attributeKey2",
],
"separator": "::"
}
}
]
Estrarre attributi dal corpo del messaggio di log
La toAttributes
sezione elenca le espressioni regolari in modo che corrispondano al corpo del messaggio di log. Estrae gli attributi in base alle sottoespressioni.
L'impostazione rules
è obbligatoria. Questa impostazione elenca le regole usate per estrarre i valori degli attributi dal corpo.
I nomi degli attributi estratti sostituiscono i valori nel corpo del messaggio di log. Ogni regola nell'elenco è una stringa di criteri di espressione regolare (regex).
Ecco come i nomi degli attributi estratti sostituiscono i valori:
- Il corpo del messaggio di log viene controllato rispetto all'espressione regolare.
- Tutte le sottoespressioni denominate dell'espressione regolare vengono estratte come attributi se l'espressione regolare corrisponde.
- Gli attributi estratti vengono aggiunti al log.
- Ogni nome di sottoespressione diventa un nome di attributo.
- La parte corrispondente alla sottoespressione diventa il valore dell'attributo.
- Il nome dell'attributo estratto sostituisce la parte corrispondente nel nome del log. Se gli attributi esistono già nel log, vengono sovrascritti.
Questo processo viene ripetuto per tutte le regole nell'ordine in cui vengono specificate. Ogni regola successiva funziona sul nome del log che rappresenta l'output della regola precedente.
"processors": [
{
"type": "log",
"body": {
"toAttributes": {
"rules": [
"rule1",
"rule2",
"rule3"
]
}
}
}
]
Includere criteri ed escludere criteri
I processori di log supportano criteri e exclude
facoltativiinclude
.
Un processore di log viene applicato solo ai dati di telemetria che soddisfano i criteri include
(se disponibili) e non soddisfano i criteri exclude
(se disponibili).
Per configurare questa opzione, in include
o (o in entrambi), specificare e matchType
attributes
.exclude
La include
configurazione o exclude
consente più di una condizione specificata.
Tutte le condizioni specificate devono restituire true per ottenere una corrispondenza.
- Campo obbligatorio:
matchType
controlla la modalità di interpretazione degli elementi nelleattributes
matrici. I valori possibili sonoregexp
estrict
. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contieneabc
un punto qualsiasi, è necessario usare.*abc.*
.attributes
specifica l'elenco di attributi da associare. Tutti questi attributi devono corrispondere esattamente al risultato di una corrispondenza.
Nota
Se vengono specificati e include
exclude
, le include
proprietà vengono controllate prima che vengano controllate le exclude
proprietà.
Nota
I processori di log non supportano spanNames
.
Esempio di utilizzo
"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"
]
}
}
}
]
Per altre informazioni, vedere Esempi di processore di telemetria.
Filtro delle metriche
Nota
I filtri delle metriche sono disponibili a partire dalla versione 3.1.1.
I filtri delle metriche vengono usati per escludere alcune metriche per controllare i costi di inserimento.
I filtri delle metriche supportano exclude
solo i criteri. Le metriche che soddisfano i criteri exclude
non vengono esportate.
Per configurare questa opzione, in exclude
specificare matchType
uno o più metricNames
.
- Campo obbligatorio:
matchType
controlla la corrispondenza degli elementi inmetricNames
. I valori possibili sonoregexp
estrict
. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contieneabc
un punto qualsiasi, è necessario usare.*abc.*
.metricNames
deve corrispondere ad almeno uno degli elementi.
Esempio di utilizzo
L'esempio seguente illustra come escludere le metriche con nomi "metricA" e "metricB":
"processors": [
{
"type": "metric-filter",
"exclude": {
"matchType": "strict",
"metricNames": [
"metricA",
"metricB"
]
}
}
]
L'esempio seguente illustra come disattivare tutte le metriche, incluse le metriche delle prestazioni predefinite, ad esempio cpu e memoria.
"processors": [
{
"type": "metric-filter",
"exclude": {
"matchType": "regexp",
"metricNames": [
".*"
]
}
}
]
Metriche predefinite acquisite dall'agente Java
Nome metrica | Tipo di metrica | Descrizione | Filtrabile |
---|---|---|---|
Current Thread Count |
metriche personalizzate | Vedere ThreadMXBean.getThreadCount(). | yes |
Loaded Class Count |
metriche personalizzate | Vedere ClassLoadingMXBean.getLoadedClassCount(). | yes |
GC Total Count |
metriche personalizzate | Somma dei conteggi in tutte le istanze GarbageCollectorMXBean (diff dall'ultimo segnalato). Vedere GarbageCollectorMXBean.getCollectionCount(). | yes |
GC Total Time |
metriche personalizzate | Somma del tempo in tutte le istanze GarbageCollectorMXBean (diff dall'ultimo segnalato). Vedere GarbageCollectorMXBean.getCollectionTime(). | yes |
Heap Memory Used (MB) |
metriche personalizzate | Vedere MemoryMXBean.getHeapMemoryUsage().getUsed(). | yes |
% Of Max Heap Memory Used |
metriche personalizzate | java.lang:type=Memoria/quantità massima di memoria in byte. Vedere MemoryUsage | yes |
\Processor(_Total)\% Processor Time |
metriche predefinite | Differenza nei contatori di graduazione del carico cpu a livello di sistema (solo utente e sistema) divisi per il numero di processori logici in un determinato intervallo di tempo | no |
\Process(??APP_WIN32_PROC??)\% Processor Time |
metriche predefinite | Vedere OperatingSystemMXBean.getProcessCpuTime() (diff dall'ultimo segnalato, normalizzato in base all'ora e al numero di CPU). | no |
\Process(??APP_WIN32_PROC??)\Private Bytes |
metriche predefinite | Somma di MemoryMXBean.getHeapMemoryUsage() e MemoryMXBean.getNonHeapMemoryUsage(). | no |
\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec |
metriche predefinite | /proc/[pid]/io Somma di byte letti e scritti dal processo (diff dall'ultimo segnalato). Vedere proc(5). |
no |
\Memory\Available Bytes |
metriche predefinite | Vedere OperatingSystemMXBean.getFreePhysicalMemorySize(). | no |
Domande frequenti
Perché i file di log del processore di log non usano TelemetryClient.trackTrace()?
TelemetryClient.trackTrace() fa parte del bridge di Application Insights Classic SDK e i processori di log funzionano solo con la nuova strumentazione basata su OpenTelemetry.
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per