Configuring filtering for Java applications

Edit online

You can reduce trace data volume for Java applications by filtering out specific spans based on their attributes. This feature helps optimize data ingestion costs and focus on the most relevant traces for your application monitoring needs.

Attribute-based filtering is available for HTTP and JDBC spans in Java applications. For more information about reducing data that is ingested from tracing, see Optimize data ingest in Instana.

Filtering options

Edit online

You can filter Java application traces by using the following approaches:

  • Method-based filtering: For filtering spans from DynamoDB, Redis, and Kafka, see Ignoring endpoints. With this feature, you can exclude traces based on method names (such as GET, consume, or query) and endpoints (such as Kafka topic names).
  • Span attributes-based filtering: For filtering HTTP and JDBC spans, use the span attribute-based filtering approach. This feature provides advanced filtering capabilities based on multiple span attributes, such as URLs, SQL statements, or HTTP methods. This approach supports flexible pattern matching (strict, startswith, endswith, and contains) and allows combining multiple attributes in a single rule.

For detailed configuration instructions for span attributes-based filtering, see the following sections.

Reference trace example

Edit online

The following example shows a complete trace without any filtering applied, which is used as a reference throughout this document:

Span attributes-based filtering

Edit online

Span attributes-based filtering for Java applications can be configured only through the agent configuration.yaml file. Environment variables and system properties are not supported for filtering configuration.

Note: Configuration changes are applied dynamically without requiring an application restart after the initial setup.

Filtering configuration

Edit online

You can configure filtering rules to exclude HTTP and JDBC spans based on attributes, such as URLs, SQL statements, or HTTP methods.

Filtering rules are defined in the com.instana.tracing.filter section of the agent configuration.yaml file (instanaAgentDir/etc/instana/configuration.yaml). The configuration uses a YAML structure to define filter rules based on span attributes.

To define filter rules, use the following configuration:

com.instana.tracing:
  filter:
    deactivate: <boolean>
    exclude:
      - name: <string>
        attributes:
          - key: <string>
            values: [<string>, ...]
            match_type: <string>
Important: You can define multiple filter rules within the exclude policy. Each rule can have multiple attributes that must all match for the rule to apply.
Field Required Description
filter Mandatory Root node for all filtering rules.
deactivate Optional Feature toggle to turn off filtering without deleting the configured filter rules. When set to true, filtering is disabled. The default value is false (filtering remains active).
exclude Mandatory Policy that holds the exclude rules to exclude spans from a trace. Currently, only the exclude policy is supported.
name Mandatory Human-readable name that describes the filter rule.
attributes Mandatory List of span attributes that must all match for a rule to apply.
key Mandatory Span attribute key.
values Mandatory List of values to match for the span attribute key. An attribute matches if any of its values match. Use '*' as a wildcard to match any value for the specified attribute key (useful for filtering based on attribute presence regardless of value).
match_type Optional Defines how the values of span attributes are matched. Valid values: strict (default), startswith, endswith, and contains.

Suppression behavior

When spans are excluded by filtering rules, the suppression behavior differs between HTTP and JDBC:
  • HTTP filtering: Suppression is applied by default. When an HTTP span is excluded, all child spans and downstream tracing are automatically suppressed. No spans are generated for any database calls, external service calls, or other operations that are triggered by the excluded HTTP request.
  • JDBC filtering: Suppression is not applied. When a JDBC span is excluded, child spans and subsequent operations in the trace continue to be captured.
Important: The suppression configuration parameter cannot be configured. The suppression behavior is determined automatically based on the span type.

Wildcard usage

You can use the wildcard "*" in the values field to match any value for a specific span attribute. This is useful when you want to filter spans based on the presence of an attribute regardless of its value. The wildcard can be used for both HTTP and JDBC filtering.

Example: To exclude all spans that have an error attribute (regardless of the error message), use the following configuration:

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

Rule execution order

Filter rules are evaluated in the order that they appear in the configuration. When a span matches a filter rule, that rule is applied and no subsequent rules are evaluated for that span. Within the exclude policy, the first matching rule determines the filtering behavior.

Important: Arrange your rules from the most specific to the most general to ensure that the correct filtering behavior is applied.

Example:

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 this example, if a span matches /api/internal/health, the first rule applies. If a span matches /health but not /api/internal/health, the second rule applies. The order matters because the first matching rule is used.

HTTP endpoint filtering

Edit online

With HTTP endpoint filtering, you can exclude HTTP spans based on attributes such as URL, method, and headers. This feature is supported for the following HTTP frameworks:

  • Servlet: Applications that use the Java Servlet API
  • Spring Web: Applications that use Spring MVC and Spring Boot
Important: When an HTTP span is excluded, suppression is applied by default. All child spans and downstream tracing are automatically suppressed, including any database calls, external service calls, or other operations triggered by the excluded HTTP request.

Span attributes for HTTP endpoint filtering

You can use the following span attributes to filter HTTP endpoints. The "UI Display Name" column shows how each attribute appears in the Instana UI when you view span details.

Important: The UI display names that are shown in the following table are in the English language. If you are using the Instana UI in a different language, these labels are translated according to your language settings. However, the span attribute keys (used in filtering configuration) remain the same across all languages. Sometimes the UI display names might differ from the mapping that are presented in this table.
Span attribute UI display name Description Example value Filtering support
http.url URL URL or path /api/users Yes
http.method Method HTTP method GET Yes
http.status Status code HTTP response status code 200 Limited*
http.host Host Hostname with port localhost:8080 Yes
http.path Request path Request path /api/users Yes
http.path_tpl Path template Route template or pattern /api/users/{id} Yes
http.params Parameters HTTP query string action=edit&id=5 Yes
http.error Error Error message Error description Limited*
http.header.<header-name> Header HTTP request header header-value Yes
http.header.<response-header-name> Header HTTP response header header-value Limited*
* Limited filtering support: Span attributes that are available only after the HTTP request completes (such as http.status and response headers http.header.<response-header-name>) have limited filtering capabilities. Filter rules based on these attributes can exclude spans but cannot enforce suppression of child spans and downstream tracing because the attribute values are not known at the time when the decision to suppress is made.

UI display variations

While the span attribute keys remain constant for filtering configuration, the actual display values in the Instana UI might vary based on context:

  • http.status: Displays the status code with a human-readable description appended (for example, 200 – OK, 404 – Not Found, or 500 – Internal Server Error). When filtering, use only the numeric status code value.
  • http.error: Displays in the UI only if the error value is a nonempty string. Additionally, this attribute might be redacted if it contains sensitive data as defined by the Java Tracer's sensitive data configuration. Empty or redacted errors do not appear in the UI.
  • http.params: When the query string is empty or blank, the UI displays <no query parameters> instead of an empty value. When filtering, match against the actual query string value or use an empty string.
  • http.url: Displayed in the UI only if it differs from http.path. If both values are identical, only the path is shown to avoid redundancy.
Important: These display variations do not affect filtering behavior. Filtering rules always match against the raw span attribute values that are stored in the backend, not the formatted display values shown in the UI.

Example HTTP endpoint filtering configuration

The following example shows an HTTP endpoint filtering configuration:

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

In the preceding example, the filtering configuration enforces the following rules:

  • Excludes HTTP spans whose URL ends with /health, /ping, or /ready. Child spans and downstream tracing are automatically suppressed.
  • Excludes HTTP spans with HTTP method OPTIONS. Child spans and downstream tracing are automatically suppressed.

The following example shows the effect of HTTP filtering with suppression. When comparing this trace to the complete trace without filtering (Figure 1), you can see that HTTP calls with the parameter author=test2 are filtered out, along with all their child spans:

JDBC span filtering

Edit online

With JDBC span filtering, you can exclude database spans based on attributes, such as SQL statements, connection strings, and error messages.

Important: Unlike HTTP filtering, JDBC filtering does NOT suppress downstream tracing. When a JDBC span is excluded, child spans and subsequent operations in the trace continue to be captured.

Span attributes for JDBC span filtering

You can use the following span attributes to filter JDBC spans. The "UI Display Name" column shows how each attribute appears in the Instana UI when viewing span details.

Note: The UI display names that are shown in the following table are in the English language. If you are using the Instana UI in a different language, these labels are translated according to your language settings, but the span attribute keys (used in filtering configuration) remain the same across all languages.
Span attribute UI display name Description Example value
jdbc.connection Connection JDBC connection string jdbc:mysql://localhost:3306/mydb
jdbc.statement Statement SQL statement SELECT * FROM users
jdbc.error Error Error message SQL error description

UI display variations

Similar to HTTP spans, JDBC span attributes might display variations in the Instana UI:

  • jdbc.error: Displays in the UI only if the error value is a nonempty string. This attribute might be redacted if it contains sensitive data as defined by the Java Tracer's sensitive data configuration. Empty or redacted errors do not appear in the UI.
  • jdbc.statement: SQL statements might be truncated in the UI for display purposes if they exceed a certain length, but the full statement is used for filtering evaluation.
Important: These display variations do not affect filtering behavior. Filtering rules always match against the raw span attribute values that are stored in the backend.

Example JDBC span filtering configuration

The following example shows a JDBC span filtering configuration:

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

In the preceding example, the filtering configuration enforces the following rules:

  • Excludes JDBC spans whose SQL statement contains audit_log or session_data.
  • Excludes JDBC spans with SQL statements that start with SELECT and connection strings that contain mysql.
  • Exclude all JDBC spans that contain any error message (that use the '*' wildcard to match any error value).

The following example shows the effect of JDBC filtering. When comparing this trace to the complete trace without filtering (Figure 1), you can see that the JDBC statement select book0_.id as id1_0_, book0_.author as author2_0_, book0_.title as title3_0_ from book book0_ where book0_.author=? is filtered, removing 2 spans from the trace:

Combined HTTP and JDBC filtering example

Edit online

The following example shows how to configure both HTTP and JDBC filtering rules together:

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 this example:

  • HTTP spans matching the health check endpoints are excluded with automatic suppression (child spans and downstream traces are suppressed).
  • JDBC spans for temporary tables are excluded without suppression (child spans and downstream traces continue to be captured).

Limitations of filtering

Edit online
  • Policy support: Currently, only the exclude policy is supported. The include policy is not yet available.
  • Suppression behavior:
    • HTTP filtering applies suppression by default (child spans and downstream traces are suppressed).
    • The suppression configuration parameter cannot be configured.
  • Limited suppression support for certain HTTP attributes: Filter rules based on span attributes that are only known after the HTTP request completes (such as http.statusand response headers like http.header.<response-header-name> and http.error) cannot enforce suppression of child spans and downstream tracing. These attributes can still be used to exclude the parent HTTP span from the trace. However, any child spans or downstream operations continue to be captured, which can lead to spans appearing with missing parent spans in the UI.
  • Filter rules based on the http.params span attribute might not work if values contains secrets that might be redacted from the HTTP URL by the Java Tracer.
  • Filtering configuration changes are applied dynamically without requiring an application restart after the initial setup.