Configurazione del filtro per le applicazioni Java

Modifica online

È possibile ridurre il volume dei dati di traccia per le applicazioni Java filtrando specifici intervalli in base ai loro attributi. Questa funzione consente di ottimizzare i costi di acquisizione dei dati e concentrarsi sulle tracce più rilevanti per le esigenze di monitoraggio delle applicazioni.

Il filtro basato sugli attributi è disponibile per gli intervalli HTTP e JDBC nelle applicazioni Java. Per ulteriori informazioni sulla riduzione dei dati acquisiti tramite tracciamento, consultare la sezione "Ottimizzazione dell'acquisizione dei dati" all'indirizzo Instana.

Opzioni di filtraggio

Modifica online

È possibile filtrare le tracce delle applicazioni di Java e utilizzando i seguenti metodi:

Filtraggio basato sui metodi : per filtrare gli intervalli provenienti da DynamoDB,, Redis e Kafka, consultare la sezione "Ignorare gli endpoint". Con questa funzione è possibile escludere le tracce in base ai nomi dei metodi (come GET, consume, o query) e agli endpoint (come i nomi degli argomenti di Kafka ).
Filtraggio basato sugli attributi degli span : per filtrare gli span HTTP e JDBC, utilizzare il metodo di filtraggio basato sugli attributi degli span. Questa funzione offre funzionalità di filtraggio avanzate basate su diversi attributi di span, quali URL, istruzioni SQL o metodi dell' HTTP. Questo approccio supporta la corrispondenza flessibile dei modelli (strict, startswith, endswith, e contains) e consente di combinare più attributi in un'unica regola.

Per istruzioni dettagliate sulla configurazione del filtro basato sugli attributi di span, consultare le sezioni seguenti.

Esempio di traccia di riferimento

Modifica online

L'esempio seguente mostra una traccia completa senza alcun filtro applicato, utilizzata come riferimento in tutto il documento:

Filtraggio basato sugli attributi Span

Modifica online

Il filtro basato sugli attributi Span per le applicazioni dell' Java e può essere configurato esclusivamente tramite il file configuration.yaml dell'agente. Le variabili di ambiente e le proprietà di sistema non sono supportate per il filtraggio della configurazione.

Nota: le modifiche alla configurazione vengono applicate dinamicamente senza richiedere il riavvio dell'applicazione dopo l'impostazione iniziale.

Configurazione del filtro

Modifica online

È possibile configurare regole di filtraggio per escludere gli span HTTP e JDBC in base ad attributi quali URL, istruzioni SQL o metodi HTTP.

Le regole di filtraggio sono definite nella com.instana.tracing.filter sezione del file configuration.yaml dell'agente (instanaAgentDir/etc/instana/configuration.yaml). La configurazione utilizza una struttura di tipo ` YAML ` per definire le regole di filtraggio in base agli attributi dello span.

Per definire le regole di filtro, utilizzare la seguente configurazione:

com.instana.tracing:
  filter:
    deactivate: <boolean>
    exclude:
      - name: <string>
        attributes:
          - key: <string>
            values: [<string>, ...]
            match_type: <string>

Importante: è possibile definire più regole di filtro all'interno della exclude policy. Ogni regola può avere più attributi che devono corrispondere tutti affinché la regola sia applicabile.

Campo	Obbligatorio	Descrizione
`filter`	Obbligatorio	Nodo radice per tutte le regole di filtraggio.
`deactivate`	Facoltativo	Attiva/disattiva la funzione per disattivare il filtro senza eliminare le regole di filtro configurate. Quando è impostato su `true`, il filtro è disabilitato. Il valore predefinito è `false` (il filtro rimane attivo).
`exclude`	Obbligatorio	Criterio che contiene le regole di esclusione per escludere gli intervalli da una traccia. Attualmente è supportata solo la `exclude` politica.
`name`	Obbligatorio	Nome leggibile dall'utente che descrive la regola del filtro.
`attributes`	Obbligatorio	Elenco degli attributi span che devono corrispondere tutti affinché una regola sia applicabile.
`key`	Obbligatorio	Chiave dell'attributo span.
`values`	Obbligatorio	Elenco dei valori da abbinare all'attributo span `key`. Un attributo corrisponde se uno qualsiasi dei suoi `values` corrisponde. Utilizzare `'*'` come carattere jolly per trovare qualsiasi valore per la chiave dell'attributo specificato (utile per filtrare in base alla presenza dell'attributo indipendentemente dal valore).
`match_type`	Facoltativo	Definisce come vengono abbinati gli `values` attributi span. Valori validi: `strict` (impostazione predefinita), `startswith`, `endswith`, e `contains`.

Comportamento di soppressione

Quando gli intervalli vengono esclusi dalle regole di filtraggio, il comportamento di soppressione differisce tra HTTP e JDBC :

HTTP filtraggio : la soppressione è applicata per impostazione predefinita. Quando uno span dell' HTTP e viene escluso, tutti gli span secondari e il tracciamento a valle vengono automaticamente soppressi. Non vengono generati intervalli per le chiamate al database, le chiamate a servizi esterni o altre operazioni attivate dalla richiesta esclusa HTTP.
JDBC filtraggio : la soppressione non viene applicata. Quando uno span dell' JDBC e viene escluso, gli span secondari e le operazioni successive nella traccia continuano a essere acquisiti.

Importante: il suppression parametro di configurazione non può essere configurato. Il comportamento di soppressione viene determinato automaticamente in base al tipo di span.

Uso dei caratteri jolly

È possibile utilizzare il carattere jolly "*" nel values campo per trovare qualsiasi valore per un attributo span specifico. Questo è utile quando si desidera filtrare gli span in base alla presenza di un attributo indipendentemente dal suo valore. Il carattere jolly può essere utilizzato sia per il filtraggio HTTP che JDBC.

Esempio: per escludere tutti gli span che hanno un attributo di errore (indipendentemente dal messaggio di errore), utilizzare la seguente configurazione:

com.instana.tracing:
  filter:
    exclude:
      - name: exclude all HTTP error spans
        attributes:
          - key: http.error
            values: ["*"]
            match_type: strict
      - name: exclude all JDBC error spans
        attributes:
          - key: jdbc.error
            values: ["*"]
            match_type: strict

Ordine di esecuzione delle regole

Le regole di filtro vengono valutate nell'ordine in cui compaiono nella configurazione. Quando uno span corrisponde a una regola di filtro, tale regola viene applicata e nessuna delle regole successive viene valutata per quello span. All'interno della exclude politica, la prima regola corrispondente determina il comportamento di filtraggio.

Importante: ordina le regole dalla più specifica alla più generica per garantire che venga applicato il corretto comportamento di filtraggio.

Esempio:

com.instana.tracing:
  filter:
    exclude:
      - name: exclude specific internal health endpoint
        attributes:
          - key: http.url
            values: [/api/internal/health]
            match_type: strict
      - name: exclude all health endpoints
        attributes:
          - key: http.url
            values: [/health]
            match_type: contains

In questo esempio, se uno span corrisponde /api/internal/healtha, si applica la prima regola. Se uno span corrisponde a /health ma non /api/internal/healtha, si applica la seconda regola. L'ordine è importante perché viene utilizzata la prima regola corrispondente.

HTTP filtraggio degli endpoint

Modifica online

Con il filtraggio degli endpoint di HTTP, è possibile escludere gli span di HTTP in base ad attributi quali URL, metodo e intestazioni. Questa funzione è supportata per i seguenti framework HTTP :

Servlet : applicazioni che utilizzano l' Java Servlet API
Spring Web : applicazioni che utilizzano Spring MVC e Spring Boot

Importante: quando viene escluso un intervallo di HTTP, viene applicata l'oppressione per impostazione predefinita. Tutti gli span secondari e il tracciamento a valle vengono automaticamente soppressi, comprese eventuali chiamate al database, chiamate a servizi esterni o altre operazioni attivate dalla richiesta HTTP esclusa.

Attributi Span per il filtraggio degli endpoint dell' HTTP

È possibile utilizzare i seguenti attributi span per filtrare gli endpoint dell' HTTP. La colonna "Nome visualizzato nell'interfaccia utente" mostra come ogni attributo appare nell'interfaccia utente di Instana quando si visualizzano i dettagli dello span.

Importante: i nomi visualizzati nell'interfaccia utente riportati nella tabella seguente sono in lingua inglese. Se utilizzi l'interfaccia utente di Instana in una lingua diversa, queste etichette vengono tradotte in base alle tue impostazioni di lingua. Tuttavia, le chiavi dell'attributo span (utilizzate nella configurazione dei filtri) rimangono le stesse in tutte le lingue. A volte i nomi visualizzati nell'interfaccia utente potrebbero differire dalla mappatura presentata in questa tabella.

Attributo span	Nome visualizzato nell'interfaccia utente	Descrizione	Valore di esempio	Supporto per il filtraggio
`http.url`	URL	URL o percorso	`/api/users`	Sì
`http.method`	Metodo	Metodo HTTP	`GET`	Sì
`http.status`	Codice di stato	HTTP codice di stato della risposta	`200`	Limitato*
`http.host`	Host	Nome host con porta	`localhost:8080`	Sì
`http.path`	Percorso richiesta	Percorso richiesta	`/api/users`	Sì
`http.path_tpl`	Modello di percorso	Modello o schema di percorso	`/api/users/{id}`	Sì
`http.params`	Parametri	Stringa query HTTP	`action=edit&id=5`	Sì
`http.error`	Errore	Messaggio di errore	Descrizione dell'errore	Limitato*
`http.header.<header-name>`	Intestazione	HTTP intestazione della richiesta	`header-value`	Sì
`http.header.<response-header-name>`	Intestazione	Intestazione risposta HTTP	`header-value`	Limitato*

* Supporto di filtraggio limitato : gli attributi Span disponibili solo dopo il completamento della richiesta HTTP (come http.status e le intestazioni di risposta http.header.<response-header-name> ) hanno capacità di filtraggio limitate. Le regole di filtro basate su questi attributi possono escludere gli span, ma non possono imporre la soppressione degli span secondari e del tracciamento a valle, poiché i valori degli attributi non sono noti al momento in cui viene presa la decisione di sopprimere.

Variazioni nella visualizzazione dell'interfaccia utente

Sebbene le chiavi dell'attributo span rimangano costanti per la configurazione del filtro, i valori effettivi visualizzati nell'interfaccia utente dell' Instana e possono variare in base al contesto:

http.status: Visualizza il codice di stato con una descrizione leggibile dall'utente (ad esempio, 200 – OK, 404 – Not Found, o 500 – Internal Server Error). Durante il filtraggio, utilizzare solo il valore numerico del codice di stato.
http.error: Visualizza nell'interfaccia utente solo se il valore dell'errore è una stringa non vuota. Inoltre, questo attributo potrebbe essere oscurato se contiene dati sensibili, come definito dalla configurazione dei dati sensibili di Tracer dell' Java. Gli errori vuoti o modificati non vengono visualizzati nell'interfaccia utente.
http.paramsQuando la stringa di query è vuota o bianca, l'interfaccia utente visualizza <no query parameters> anziché un valore vuoto. Durante il filtraggio, effettuare la corrispondenza con il valore effettivo della stringa di query oppure utilizzare una stringa vuota.
http.url: Visualizzato nell'interfaccia utente solo se diverso da http.path. Se entrambi i valori sono identici, viene mostrato solo il percorso per evitare ridondanze.

Importante: queste variazioni nella visualizzazione non influiscono sul funzionamento dei filtri. Le regole di filtraggio vengono sempre confrontate con i valori grezzi dell'attributo span memorizzati nel backend, non con i valori formattati visualizzati nell'interfaccia utente.

Esempio di configurazione del filtro endpoint HTTP

L'esempio seguente mostra una configurazione di filtraggio dell'endpoint dell' HTTP :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude HTTP health check endpoints
        attributes:
          - key: http.url
            values: [/health, /ping, /ready]
            match_type: endswith
      - name: exclude HTTP OPTIONS requests
        attributes:
          - key: http.method
            values: [OPTIONS]
            match_type: strict

Nell'esempio precedente, la configurazione di filtraggio applica le seguenti regole:

Esclude gli span HTTP il cui URL termina con /health, /ping, o /ready. I child span e il tracciamento a valle vengono automaticamente soppressi.
Esclude gli span dell' HTTP con il metodo HTTPOPTIONS. I child span e il tracciamento a valle vengono automaticamente soppressi.

L'esempio seguente mostra l'effetto di un filtro HTTP o con soppressione. Confrontando questa traccia con la traccia completa senza filtraggio (Figura 1), è possibile notare che le chiamate HTTP con il parametro author=test2 vengono filtrate, insieme a tutti i loro span secondari:

JDBC filtraggio span

Modifica online

Con il filtro degli span di tipo " JDBC ", è possibile escludere gli span del database in base ad attributi quali istruzioni SQL, stringhe di connessione e messaggi di errore.

Importante: a differenza del filtro " HTTP ", il filtro " JDBC " NON inibisce il tracciamento a valle. Quando uno span dell' JDBC e viene escluso, gli span secondari e le operazioni successive nella traccia continuano a essere acquisiti.

Attributi span per il filtraggio span dell' JDBC

È possibile utilizzare i seguenti attributi span per filtrare gli span dell' JDBC. La colonna "Nome visualizzato nell'interfaccia utente" mostra come ogni attributo appare nell'interfaccia utente di Instana durante la visualizzazione dei dettagli dello span.

Nota: i nomi visualizzati nell'interfaccia utente riportati nella tabella seguente sono in lingua inglese. Se si utilizza l'interfaccia utente di Instana in una lingua diversa, queste etichette vengono tradotte in base alle impostazioni della lingua, ma le chiavi dell'attributo span (utilizzate nella configurazione del filtro) rimangono le stesse in tutte le lingue.

Attributo span	Nome visualizzato nell'interfaccia utente	Descrizione	Valore di esempio
`jdbc.connection`	Connessione	Stringa di connessione JDBC	`jdbc:mysql://localhost:3306/mydb`
`jdbc.statement`	Dichiarazione	Istruzione SQL	`SELECT * FROM users`
`jdbc.error`	Errore	Messaggio di errore	Descrizione dell'errore SQL

Variazioni nella visualizzazione dell'interfaccia utente

Analogamente agli span HTTP, gli attributi degli span JDBC potrebbero presentare variazioni nell'interfaccia utente Instana :

jdbc.error: Visualizza nell'interfaccia utente solo se il valore dell'errore è una stringa non vuota. Questo attributo potrebbe essere oscurato se contiene dati sensibili, come definito dalla configurazione dei dati sensibili di Tracer dell' Java. Gli errori vuoti o modificati non vengono visualizzati nell'interfaccia utente.
jdbc.statement: Le istruzioni SQL potrebbero essere troncate nell'interfaccia utente per motivi di visualizzazione se superano una certa lunghezza, ma per la valutazione del filtro viene utilizzata l'istruzione completa.

Importante: queste variazioni nella visualizzazione non influiscono sul funzionamento dei filtri. Le regole di filtraggio vengono sempre confrontate con i valori degli attributi span grezzi memorizzati nel backend.

Esempio di configurazione del filtro span JDBC

L'esempio seguente mostra una configurazione di filtro span JDBC :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude JDBC spans for audit tables
        attributes:
          - key: jdbc.statement
            values: [audit_log, session_data]
            match_type: contains
      - name: exclude SELECT queries on MySQL database
        attributes:
          - key: jdbc.statement
            values: [SELECT]
            match_type: startswith
          - key: jdbc.connection
            values: [mysql]
            match_type: contains
      - name: exclude all JDBC error spans
        attributes:
          - key: jdbc.error
            values: ['*']
            match_type: strict

Nell'esempio precedente, la configurazione di filtraggio applica le seguenti regole:

Esclude gli span di tipo ` JDBC ` la cui istruzione SQL contiene audit_log `` o ` session_data`.
Esclude gli span JDBC con istruzioni SQL che iniziano con SELECT e stringhe di connessione che contengono mysql.
Escludere tutti gli span JDBC che contengono messaggi di errore (che utilizzano il '*' carattere jolly per trovare qualsiasi valore di errore).

L'esempio seguente mostra l'effetto del filtraggio dell' JDBC. Confrontando questa traccia con la traccia completa senza filtro (Figura 1), è possibile notare che l'istruzione select book0_.id as id1_0_, book0_.author as author2_0_, book0_.title as title3_0_ from book book0_ where book0_.author=?JDBC viene filtrata, rimuovendo 2 span dalla traccia:

Esempio di filtraggio combinato di HTTP e JDBC

Modifica online

L'esempio seguente mostra come configurare insieme le regole di filtraggio HTTP e JDBC :

com.instana.tracing:
  filter:
    exclude:
      - name: exclude HTTP health check endpoints
        attributes:
          - key: http.url
            values: [/health, /status, /metrics]
            match_type: strict
      - name: exclude JDBC queries for temporary tables
        attributes:
          - key: jdbc.statement
            values: [temp_, tmp_]
            match_type: contains

In questo esempio:

HTTP gli span corrispondenti agli endpoint del controllo di integrità vengono esclusi con soppressione automatica (gli span secondari e le tracce a valle vengono soppressi).
JDBC gli span per le tabelle temporanee vengono esclusi senza soppressione (gli span secondari e le tracce a valle continuano a essere acquisiti).

Limiti del filtraggio

Modifica online

Supporto delle politiche : attualmente è supportata solo la exclude politica. La include politica non è ancora disponibile.
Comportamento di soppressione :
- HTTP il filtro applica la soppressione per impostazione predefinita (gli span secondari e le tracce a valle vengono soppressi).
- Il suppression parametro di configurazione non può essere configurato.
Supporto limitato alla soppressione per determinati attributi dell' HTTP : le regole di filtro basate su attributi span noti solo dopo il completamento della richiesta HTTP (come http.statuse le intestazioni di risposta come http.header.<response-header-name> e http.error) non possono imporre la soppressione degli span secondari e del tracciamento a valle. Questi attributi possono comunque essere utilizzati per escludere lo span padre HTTP dalla traccia. Tuttavia, eventuali operazioni span o downstream continuano a essere acquisite, il che può comportare la visualizzazione di span con span parent mancanti nell'interfaccia utente.
Le regole di filtro basate sull'attributo http.params span potrebbero non funzionare se values contengono segreti che potrebbero essere oscurati dall' HTTPURL dall' Java Tracer.
Le modifiche alla configurazione del filtro vengono applicate dinamicamente senza richiedere il riavvio dell'applicazione dopo la configurazione iniziale.