Share via

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

  • Articolo

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 o fromAttribute
  • 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 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'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 in spanNames matrici e attributes matrici. 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 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 includeexclude , 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 logsa .

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:

  1. Il nome dell'intervallo viene controllato rispetto all'espressione regolare.
  2. Tutte le sottoespressioni denominate dell'espressione regolare vengono estratte come attributi se l'espressione regolare corrisponde.
  3. Gli attributi estratti vengono aggiunti all'intervallo.
  4. Ogni nome di sottoespressione diventa un nome di attributo.
  5. La parte corrispondente alla sottoespressione diventa il valore dell'attributo.
  6. 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 in spanNames matrici e attributes matrici. 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 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 includeexclude , 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:

  1. Il corpo del messaggio di log viene controllato rispetto all'espressione regolare.
  2. Tutte le sottoespressioni denominate dell'espressione regolare vengono estratte come attributi se l'espressione regolare corrisponde.
  3. Gli attributi estratti vengono aggiunti al log.
  4. Ogni nome di sottoespressione diventa un nome di attributo.
  5. La parte corrispondente alla sottoespressione diventa il valore dell'attributo.
  6. 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 matchTypeattributes.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 nelle attributes matrici. 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 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 includeexclude , 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 excludespecificare matchType uno 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 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.