Processori di dati di telemetria (anteprima) - Monitoraggio di Azure di Application Insights per Java

Nota

La funzionalità dei processori di telemetria è designata come anteprima perché non è possibile garantire la retrocompatibilità fra le versioni, 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, che viene usato per aggregare dati di telemetria simili nel portale di Azure.
Rimuovere attributi di intervallo specifici per controllare i costi di inserimento.
Filtrare alcune metriche per controllare i costi di inserimento.

Nota

Se si vogliono rimuovere intervalli specifici (interi) per controllare i costi di inserimento, vedere Override di 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:

Una 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 eseguire l'hash degli 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 booleano o numero.

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 oggetto span 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 o fromAttribute
action: insert

`update`

L'azione update aggiorna un attributo nell'elemento di telemetria in cui key esiste già.

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

L'azione update richiede le impostazioni seguenti:

key
Il valore può essere value o fromAttribute
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'azione hash esegue l'hash (SHA1) di 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 funzionalità extract è 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 processore spantoAttributes, 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 funzionalità mask è disponibile solo nella versione 3.2.5 e successive.

L'azione mask maschera i valori dell'attributo usando una regola di espressione regolare specificata in pattern 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 i criteri facoltativi include e exclude. Un processore di attributi viene applicato solo ai dati di telemetria che soddisfano i relativi criteri include (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 un'opzione fra spanNames o attributes. La configurazione include 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 in matrici spanNames e attributes. I valori possibili sono regexp e strict. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contiene abc in un punto qualsiasi, è necessario usare .*abc.*.
Campi facoltativi:
- spanNames deve corrispondere ad almeno uno degli elementi.
- attributes specifica l'elenco di attributi. Tutti questi attributi devono corrispondere esattamente al risultato di una corrispondenza.

Nota

Se vengono specificati include e exclude, le proprietà include vengono controllate prima che vengano controllate le proprietà exclude.

Nota

Se le configurazioni include o exclude non sono specificate da spanNames, i criteri di corrispondenza vengono applicati sia su spans che su logs.

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 sezione name 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 fatto che il processore degli attributi per modifichi gli attributi, assicurarsi che il processore span venga specificato dopo la specifica del processore degli attributi nella pipeline.

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

Estrarre gli attributi dal nome dell'intervallo

Nella sezione toAttributes 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`)	corda	Metodo della richiesta HTTP.
`url.full` (intervallo client) o `url.path` (intervallo server) (usato per essere `http.url`)	corda	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`)	numero	Codice di stato della risposta HTTP.
`network.protocol.version` (usato per essere `http.flavor`)	corda	Tipo di protocollo HTTP.
`user_agent.original` (usato per essere `http.user_agent`)	corda	Valore dell'intestazione HTTP User-Agent inviata dal client.

Span Java Database Connectivity

La tabella seguente descrive gli attributi che è possibile usare negli intervalli JDBC (Java Database Connectivity):

Attributo	Tipo	Descrizione
`db.system`	corda	Identificatore del prodotto DBMS (Database Management System) in uso. Vedere Convenzioni semantiche per le operazioni di database.
`db.connection_string`	corda	Stringa di connessione utilizzata per connettersi al database. È consigliabile rimuovere le credenziali incorporate.
`db.user`	corda	Nome utente per l'accesso al database.
`db.name`	corda	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`	corda	Istruzione di database in esecuzione.

Includere criteri ed escludere criteri

I processori span supportano i criteri facoltativi include e exclude. 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 uno fra spanNames o span attributes. La configurazione include 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 in matrici spanNames e attributes. I valori possibili sono regexp e strict. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contiene abc in un punto qualsiasi, è necessario usare .*abc.*.
Campi facoltativi:
- spanNames deve corrispondere ad almeno uno degli elementi.
- attributes specifica l'elenco di attributi. Tutti questi attributi devono corrispondere esattamente al risultato di una corrispondenza.

Nota

Se vengono specificati include e exclude, le proprietà include vengono controllate prima che vengano controllate le proprietà exclude.

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 sezione body 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 sezione toAttributes 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 i criteri facoltativi include e exclude. 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 exclude (o in entrambi), specificare matchType e attributes. La configurazione include 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 nelle matrici attributes. I valori possibili sono regexp e strict. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contiene abc in un punto qualsiasi, è necessario usare .*abc.*.
- attributes specifica l'elenco di attributi. Tutti questi attributi devono corrispondere esattamente al risultato di una corrispondenza.

Nota

Se vengono specificati include e exclude, le proprietà include vengono controllate prima che vengano controllate le proprietà exclude.

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 solo i criteri exclude. Le metriche che soddisfano i criteri exclude non vengono esportate.

Per configurare questa opzione, in exclude, specificare un oggetto matchType o più metricNames.

Campo obbligatorio:
- matchType controlla la corrispondenza degli elementi in metricNames. I valori possibili sono regexp e strict. Le corrispondenze dell'espressione regolare vengono eseguite sull'intero valore dell'attributo, quindi se si vuole trovare una corrispondenza con un valore che contiene abc in 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().	Sì
`Loaded Class Count`	metriche personalizzate	Vedere ClassLoadingMXBean.getLoadedClassCount().	Sì
`GC Total Count`	metriche personalizzate	Somma dei conteggi in tutte le istanze GarbageCollectorMXBean (diff dall'ultimo segnalato). Vedere GarbageCollectorMXBean.getCollectionCount().	Sì
`GC Total Time`	metriche personalizzate	Somma del tempo in tutte le istanze GarbageCollectorMXBean (diff dall'ultimo segnalato). Vedere GarbageCollectorMXBean.getCollectionTime().	Sì
`Heap Memory Used (MB)`	metriche personalizzate	Vedere MemoryMXBean.getHeapMemoryUsage().getUsed().	Sì
`% Of Max Heap Memory Used`	metriche personalizzate	java.lang:type=Memoria/quantità massima di memoria in byte. Vedere MemoryUsage	Sì
`\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

Passaggi successivi

Per esaminare le domande frequenti, vedere Domande frequenti sul processore di telemetria

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-01-31

Condividi tramite

Processori di dati di telemetria (anteprima) - Monitoraggio di Azure di Application Insights per Java

Terminologia

Tipi di processore di telemetria

Introduzione

Processore di attributi

insert

update

delete

hash

extract

mask

Includere criteri ed escludere criteri

Esempio di utilizzo

Processore span

Assegnare un nome a span

Estrarre gli attributi dal nome dell'intervallo

Attributi di intervallo comuni

Intervalli HTTP

Span Java Database Connectivity

Includere criteri ed escludere criteri

Esempio di utilizzo

Processore di log

Aggiornare il corpo del messaggio del log

Estrarre attributi dal corpo del messaggio di log

Includere criteri ed escludere criteri

Esempio di utilizzo

Filtro delle metriche

Esempio di utilizzo

Metriche predefinite acquisite dall'agente Java

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

`insert`

`update`

`delete`

`hash`

`extract`

`mask`