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

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.

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
• Body
• 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.

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

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 span toAttributes, 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

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.

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.

"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:

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

Span Java Database Connectivity

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

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.

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

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.

"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:

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 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.

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

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

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.