Konfigurieren der Filterung für „ Java “-Anwendungen

Online bearbeiten

Sie können das Volumen der Trace-Daten für „ Java “-Anwendungen reduzieren, indem Sie bestimmte Spans anhand ihrer Attribute herausfiltern. Diese Funktion hilft Ihnen, die Kosten für die Datenerfassung zu optimieren und sich auf die für Ihre Anwendungsüberwachung relevantesten Traces zu konzentrieren.

Die attributbasierte Filterung ist für Spans in „ HTTP “ und „ JDBC “ in „ Java “-Anwendungen verfügbar. Weitere Informationen zur Reduzierung der aus der Ablaufverfolgung erfassten Daten finden Sie unter „Optimieren der Datenerfassung“ unter Instana.

Filteroptionen

Online bearbeiten

Sie können die Anwendungsverlaufsdaten von „ Java “ mit den folgenden Methoden filtern:

Methodenbasierte Filterung : Informationen zum Filtern von Spannen aus den Bereichen DynamoDB,, Redis und Kafka finden Sie unter „Endpunkte ignorieren “. Mit dieser Funktion können Sie Traces anhand von Methodennamen (wie z. B. GET, consume, oder query) und Endpunkten (wie z. B. Kafka Themennamen) ausschließen.
Filterung anhand von Span-Attributen : Verwenden Sie zur Filterung von Spans unter HTTP und JDBC die Filterung anhand von Span-Attributen. Diese Funktion bietet erweiterte Filteroptionen auf der Grundlage verschiedener Span-Attribute, wie beispielsweise URLs, SQL-Anweisungen oder Methoden von HTTP. Dieser Ansatz unterstützt flexiblen Musterabgleich (strict, startswith, endswith, und contains) und ermöglicht es, mehrere Attribute in einer einzigen Regel zu kombinieren.

Ausführliche Anweisungen zur Konfiguration der Filterung anhand von Span-Attributen finden Sie in den folgenden Abschnitten.

Beispiel für eine Referenzkurve

Online bearbeiten

Das folgende Beispiel zeigt einen vollständigen Trace ohne Filterung, der in diesem Dokument als Referenz dient:

Filterung auf Basis von Span-Attributen

Online bearbeiten

Die auf Span-Attributen basierende Filterung für „ Java “-Anwendungen kann ausschließlich über die configuration.yaml Agent-Datei konfiguriert werden. Umgebungsvariablen und Systemeigenschaften werden für die Filterkonfiguration nicht unterstützt.

Hinweis: Konfigurationsänderungen werden dynamisch übernommen, ohne dass nach der Ersteinrichtung ein Neustart der Anwendung erforderlich ist.

Filterkonfiguration

Online bearbeiten

Sie können Filterregeln konfigurieren, um Spans von HTTP und JDBC anhand von Attributen wie URLs, SQL-Anweisungen oder HTTP -Methoden auszuschließen.

Filterregeln werden im com.instana.tracing.filter Abschnitt der configuration.yaml Agent-Datei (instanaAgentDir/etc/instana/configuration.yaml) definiert. Die Konfiguration nutzt eine Struktur vom Typ „ YAML “, um Filterregeln auf der Grundlage von Span-Attributen zu definieren.

Verwenden Sie zur Definition von Filterregeln die folgende Konfiguration:

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

Wichtig: Sie können innerhalb der exclude Richtlinie mehrere Filterregeln definieren. Jede Regel kann mehrere Attribute haben, die alle übereinstimmen müssen, damit die Regel angewendet wird.

Feld	Erforderlich	Beschreibung
`filter`	Obligatorisch	Wurzelknoten für alle Filterregeln.
`deactivate`	Optional	Funktion zum Deaktivieren der Filterung, ohne die konfigurierten Filterregeln zu löschen. Wenn auf gesetzt `true`, ist die Filterung deaktiviert. Der Standardwert ist `false` (die Filterung bleibt aktiv).
`exclude`	Obligatorisch	Richtlinie, die die Ausschlussregeln zum Ausschließen von Spans aus einer Ablaufverfolgung enthält. Derzeit wird nur die `exclude` Richtlinie unterstützt.
`name`	Obligatorisch	Für Menschen lesbarer Name, der die Filterregel beschreibt.
`attributes`	Obligatorisch	Liste der Span-Attribute, die alle übereinstimmen müssen, damit eine Regel angewendet wird.
`key`	Obligatorisch	Span-Attributschlüssel.
`values`	Obligatorisch	Liste der Werte, die für das Attribut „span“ `key`übereinstimmen müssen. Ein Attribut passt, wenn eines seiner `values` übereinstimmt. Verwenden Sie `'*'` als Platzhalter, um jeden Wert für den angegebenen Attributschlüssel abzugleichen (nützlich für die Filterung basierend auf dem Vorhandensein eines Attributs, unabhängig vom Wert).
`match_type`	Optional	Legt fest, wie die `values` von Span-Attributen abgeglichen werden. Gültige Werte: `strict` (Standard), `startswith`, `endswith` und `contains`.

Unterdrückungsverhalten

Wenn Spans durch Filterregeln ausgeschlossen werden, unterscheidet sich das Unterdrückungsverhalten zwischen HTTP und JDBC :

HTTP Filterung : Unterdrückung wird standardmäßig angewendet. Wenn ein „ HTTP “-Span ausgeschlossen wird, werden alle untergeordneten Spans und nachgelagerten Tracing-Vorgänge automatisch unterdrückt. Für Datenbankaufrufe, externe Dienstaufrufe oder andere Vorgänge, die durch die ausgeschlossene Anfrage „ HTTP “ ausgelöst werden, werden keine Spannen generiert.
JDBC Filterung : Unterdrückung wird nicht angewendet. Wenn ein „ JDBC “-Span ausgeschlossen wird, werden untergeordnete Spans und nachfolgende Vorgänge in der Ablaufverfolgung weiterhin erfasst.

Wichtig: Der suppression Konfigurationsparameter kann nicht konfiguriert werden. Das Unterdrückungsverhalten wird automatisch anhand des Spannweiten-Typs bestimmt.

Verwendung von Platzhaltern

Sie können den Platzhalter "*" im values Feld verwenden, um einen beliebigen Wert für ein bestimmtes Span-Attribut abzugleichen. Dies ist nützlich, wenn Sie Spans anhand des Vorhandenseins eines Attributs unabhängig von dessen Wert filtern möchten. Die Wildcard kann sowohl für die Filterung von HTTP als auch von JDBC verwendet werden.

Beispiel: Um alle Spans auszuschließen, die ein Fehlerattribut haben (unabhängig von der Fehlermeldung), verwenden Sie die folgende Konfiguration:

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

Regelausführungsreihenfolge

Filterregeln werden in der Reihenfolge ausgewertet, in der sie in der Konfiguration erscheinen. Wenn ein Bereich einer Filterregel entspricht, wird diese Regel angewendet und es werden keine nachfolgenden Regeln für diesen Bereich ausgewertet. Innerhalb der exclude Richtlinie bestimmt die erste übereinstimmende Regel das Filterverhalten.

Wichtig: Ordnen Sie Ihre Regeln von der spezifischsten zur allgemeinsten an, um sicherzustellen, dass das richtige Filterverhalten angewendet wird.

Beispiel:

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 diesem Beispiel gilt die erste Regel, wenn eine Spanne mit übereinstimmt /api/internal/health. Wenn eine Spanne aber nicht /health/api/internal/health übereinstimmt, gilt die zweite Regel. Die Reihenfolge ist wichtig, da die erste übereinstimmende Regel verwendet wird.

HTTP Endpunktfilterung

Online bearbeiten

Mit der Endpunktfilterung von „ HTTP “ können Sie „ HTTP “-Spans basierend auf Attributen wie „ URL “, „method“ und „headers“ ausschließen. Diese Funktion wird für die folgenden „ HTTP “-Frameworks unterstützt:

Servlet : Anwendungen, die das Servlet „ Java “ verwenden API
Spring Web : Anwendungen, die „ Spring MVC” und „ Spring Boot ” verwenden

Wichtig: Wenn eine „ HTTP “-Span ausgeschlossen wird, wird standardmäßig eine Unterdrückung angewendet. Alle Kindspannen und nachgelagerten Verfolgungen werden automatisch unterdrückt, einschließlich aller Datenbankaufrufe, externen Dienstaufrufe oder anderer Vorgänge, die durch die ausgeschlossene Anfrage „ HTTP “ ausgelöst werden.

Span-Attribute für die Endpunktfilterung „ HTTP “

Sie können die folgenden Span-Attribute verwenden, um Endpunkte von HTTP zu filtern. Die Spalte „UI-Anzeigename“ zeigt, wie jedes Attribut in der Benutzeroberfläche von „ Instana “ angezeigt wird, wenn Sie Spanne-Details anzeigen.

Wichtig: Die in der folgenden Tabelle aufgeführten Bezeichnungen der Benutzeroberfläche sind in englischer Sprache. Wenn Sie die Benutzeroberfläche von „ Instana “ in einer anderen Sprache verwenden, werden diese Bezeichnungen entsprechend Ihren Spracheinstellungen übersetzt. Die Schlüssel des Attributs „span“ (die bei der Filterkonfiguration verwendet werden) bleiben jedoch in allen Sprachen gleich. Manchmal können die Anzeigenamen der Benutzeroberfläche von den Zuordnungen in dieser Tabelle abweichen.

Span-Attribut	Anzeigename der Benutzeroberfläche	Beschreibung	Beispielwert	Filterunterstützung
`http.url`	URL	URL oder Pfad	`/api/users`	Ja
`http.method`	Methode	HTTP-Methode	`GET`	Ja
`http.status`	Statuscode	HTTP Antwortstatuscode	`200`	Begrenzt*
`http.host`	Host	Hostname mit Port	`localhost:8080`	Ja
`http.path`	Anforderungspfad	Anforderungspfad	`/api/users`	Ja
`http.path_tpl`	Pfadvorlage	Routenvorlage oder Muster	`/api/users/{id}`	Ja
`http.params`	Parameter	HTTP Abfragezeichenfolge	`action=edit&id=5`	Ja
`http.error`	Fehler	Fehlernachricht	Fehlerbeschreibung	Begrenzt*
`http.header.<header-name>`	Header	HTTP Anfrage-Header	`header-value`	Ja
`http.header.<response-header-name>`	Header	HTTP-Antwortheader	`header-value`	Begrenzt*

* Eingeschränkte Filterunterstützung : Span-Attribute, die erst nach Abschluss der Anfrage „ HTTP “ verfügbar sind (z. B. http.status und Antwort-Header http.header.<response-header-name>), verfügen über eingeschränkte Filterfunktionen. Filterregeln, die auf diesen Attributen basieren, können Spans ausschließen, jedoch nicht die Unterdrückung von untergeordneten Spans und nachgelagerten Tracing-Prozessen erzwingen, da die Attributwerte zum Zeitpunkt der Entscheidung über die Unterdrückung nicht bekannt sind.

Variationen der Benutzeroberfläche

Während die Schlüssel des Attributs „span“ für die Filterkonfiguration konstant bleiben, können die tatsächlich angezeigten Werte in der Benutzeroberfläche „ Instana “ je nach Kontext variieren:

http.statusZeigt den Statuscode mit einer für Menschen lesbaren Beschreibung an (z. B. 200 – OK, 404 – Not Found, oder 500 – Internal Server Error). Verwenden Sie beim Filtern nur den numerischen Statuscode-Wert.
http.error: Wird nur dann in der Benutzeroberfläche angezeigt, wenn der Fehlerwert eine nicht leere Zeichenfolge ist. Darüber hinaus kann dieses Attribut redigiert werden, wenn es sensible Daten enthält, wie sie in der Konfiguration für sensible Daten von Java Tracer definiert sind. Leere oder redigierte Fehler werden in der Benutzeroberfläche nicht angezeigt.
http.paramsWenn die Abfragezeichenfolge leer oder unbeschrieben ist, zeigt die <no query parameters> Benutzeroberfläche anstelle eines leeren Werts an. Beim Filtern den tatsächlichen Wert der Abfragezeichenfolge abgleichen oder eine leere Zeichenfolge verwenden.
http.url: Wird nur dann in der Benutzeroberfläche angezeigt, wenn es sich von unterscheidet http.path. Wenn beide Werte identisch sind, wird nur der Pfad angezeigt, um Redundanzen zu vermeiden.

Wichtig: Diese Darstellungsvarianten haben keinen Einfluss auf das Filterverhalten. Filterregeln werden immer mit den rohen Span-Attributwerten abgeglichen, die im Backend gespeichert sind, nicht mit den formatierten Anzeigewerten, die in der Benutzeroberfläche angezeigt werden.

Beispiel für die Konfiguration der Endpunktfilterung in „ HTTP “

Das folgende Beispiel zeigt eine Filterkonfiguration für den Endpunkt „ 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

Im vorstehenden Beispiel erzwingt die Filterkonfiguration die folgenden Regeln:

Schließt „ HTTP “-Spannen aus, deren „ URL “ mit /health„, /ping “ oder /ready„.“ endet. Child-Spans und Downstream-Tracing werden automatisch unterdrückt.
Schließt „ HTTP “-Spannen mit der Methode „ HTTPOPTIONS“ aus. Child-Spans und Downstream-Tracing werden automatisch unterdrückt.

Das folgende Beispiel zeigt die Wirkung der Filterung „ HTTP “ mit Unterdrückung. Wenn Sie diese Ablaufverfolgung mit der vollständigen Ablaufverfolgung ohne Filterung vergleichen (Abbildung 1), sehen Sie, dass Aufrufe von „ HTTP “ mit dem Parameter zusammen mit allen untergeordneten author=test2 Spans herausgefiltert werden:

JDBC Span-Filterung

Online bearbeiten

Mit der Spannenfilterung von „ JDBC “ können Sie Datenbankspannen basierend auf Attributen wie SQL-Anweisungen, Verbindungszeichenfolgen und Fehlermeldungen ausschließen.

Wichtig: Im Gegensatz zur Filterung nach „ HTTP “ unterdrückt die Filterung nach „ JDBC “ die nachgelagerte Ablaufverfolgung NICHT. Wenn ein „ JDBC “-Span ausgeschlossen wird, werden untergeordnete Spans und nachfolgende Vorgänge in der Ablaufverfolgung weiterhin erfasst.

Span-Attribute für die Span-Filterung von „ JDBC “

Sie können die folgenden Span-Attribute verwenden, um Spans in „ JDBC “ zu filtern. Die Spalte „UI-Anzeigename“ zeigt, wie jedes Attribut in der Benutzeroberfläche von „ Instana “ angezeigt wird, wenn Sie Spannen-Details anzeigen.

Hinweis: Die in der folgenden Tabelle aufgeführten Anzeigenamen der Benutzeroberfläche sind in englischer Sprache. Wenn Sie die Benutzeroberfläche von „ Instana “ in einer anderen Sprache verwenden, werden diese Bezeichnungen entsprechend Ihren Spracheinstellungen übersetzt, aber die Schlüssel des Attributs „span“ (das bei der Filterkonfiguration verwendet wird) bleiben in allen Sprachen gleich.

Span-Attribut	Anzeigename der Benutzeroberfläche	Beschreibung	Beispielwert
`jdbc.connection`	Verbindung	JDBC-Verbindungszeichenfolge	`jdbc:mysql://localhost:3306/mydb`
`jdbc.statement`	Anweisung	SQL-Anweisung	`SELECT * FROM users`
`jdbc.error`	Fehler	Fehlernachricht	Beschreibung des SQL-Fehlers

Variationen der Benutzeroberfläche

Ähnlich wie bei den Attributen „ HTTP “ können die Attribute „ JDBC “ in der Benutzeroberfläche „ Instana “ Abweichungen aufweisen:

jdbc.error: Wird nur dann in der Benutzeroberfläche angezeigt, wenn der Fehlerwert eine nicht leere Zeichenfolge ist. Dieses Attribut kann redigiert werden, wenn es sensible Daten enthält, wie in der Konfiguration für sensible Daten von Java Tracer definiert. Leere oder redigierte Fehler werden in der Benutzeroberfläche nicht angezeigt.
jdbc.statementSQL-Anweisungen können in der Benutzeroberfläche zu Anzeigezwecken gekürzt werden, wenn sie eine bestimmte Länge überschreiten, aber für die Filterauswertung wird die vollständige Anweisung verwendet.

Wichtig: Diese Darstellungsvarianten haben keinen Einfluss auf das Filterverhalten. Filterregeln werden immer mit den Rohwerten der Span-Attribute abgeglichen, die im Backend gespeichert sind.

Beispiel für die Konfiguration der Spannenfilterung in „ JDBC “

Das folgende Beispiel zeigt eine Konfiguration für die Filterung von „ JDBC “-Spannen:

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

Im vorstehenden Beispiel erzwingt die Filterkonfiguration die folgenden Regeln:

Schließt „ JDBC “-Spans aus, deren SQL-Anweisung oder audit_logsession_data enthält.
Schließt „ JDBC “-Spans mit SQL-Anweisungen, die mit beginnen SELECT , und Verbindungszeichenfolgen, die enthalten mysql, aus.
Alle JDBC -Spans ausschließen, die eine Fehlermeldung enthalten (die den '*' Platzhalter verwenden, um mit einem beliebigen Fehlerwert übereinzustimmen).

Das folgende Beispiel zeigt die Wirkung der Filterung „ JDBC “. Wenn Sie diese Ablaufverfolgung mit der vollständigen Ablaufverfolgung ohne Filterung vergleichen (Abbildung 1), sehen Sie, dass die Anweisung „ select book0_.id as id1_0_, book0_.author as author2_0_, book0_.title as title3_0_ from book book0_ where book0_.author=?JDBC “ gefiltert wurde, wodurch zwei Spans aus der Ablaufverfolgung entfernt wurden:

Beispiel für die kombinierte Filterung von „ HTTP “ und „ JDBC “

Online bearbeiten

Das folgende Beispiel zeigt, wie Sie die Filterregeln „ HTTP “ und „ JDBC “ gemeinsam konfigurieren können:

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

Für dieses Beispiel gilt Folgendes:

HTTP Spans, die mit den Endpunkten des Gesundheitschecks übereinstimmen, werden automatisch unterdrückt (untergeordnete Spans und nachgelagerte Traces werden unterdrückt).
JDBC Spans für temporäre Tabellen werden ohne Unterdrückung ausgeschlossen (untergeordnete Spans und nachgelagerte Traces werden weiterhin erfasst).

Einschränkungen der Filterung

Online bearbeiten

Unterstützte Richtlinien : Derzeit wird nur die exclude Richtlinie unterstützt. Die include Richtlinie ist noch nicht verfügbar.
Unterdrückungsverhalten :
- HTTP Die Filterung unterdrückt standardmäßig (untergeordnete Spans und nachgelagerte Traces werden unterdrückt).
- Der suppression Konfigurationsparameter kann nicht konfiguriert werden.
Eingeschränkte Unterdrückungsunterstützung für bestimmte Attribute von „ HTTP “: Filterregeln, die auf Span-Attributen basieren, die erst nach Abschluss der Anfrage „ HTTP “ bekannt sind (z. B. http.statusund Antwort-Header wie http.header.<response-header-name> und http.error), können die Unterdrückung von untergeordneten Spans und nachgeschalteten Tracings nicht erzwingen. Diese Attribute können weiterhin verwendet werden, um die übergeordnete Span- HTTP -Span aus der Ablaufverfolgung auszuschließen. Allerdings werden alle untergeordneten Spans oder nachgelagerten Vorgänge weiterhin erfasst, was dazu führen kann, dass Spans mit fehlenden übergeordneten Spans in der Benutzeroberfläche angezeigt werden.
Filterregeln basierend auf dem http.params Das span-Attribut funktioniert möglicherweise nicht, wenn values enthält Geheimnisse, die vom Java Tracer aus der HTTP URL entfernt werden könnten.
Änderungen an der Filterkonfiguration werden dynamisch angewendet, ohne dass nach der Ersteinrichtung ein Neustart der Anwendung erforderlich ist.