As Web Java applications scale, controlling the volume of tracing data becomes essential for both performance and ingestion management. Starting from version 2.0.3 of the Java tracer, IBM Instana introduces span attribute filtering, which allows you to selectively ignore specific traces or calls, using many different span attributes, specifically for JDBC and HC (Http Client).

This new capability provides greater precision in trace data collection, helping you focus observability on high-value operations while reducing noise removing low priority traces.

What is new: Endpoint filtering with JDBC and HC

Previously, trace filtering in Instana was limited to Redis, DynamoDB and Kafka. See the previous blog post for details.

With the latest update:

• JDBC and HC supports filtering based on span attributes.

• You can precisely control which span attributes should be traced or ignored.
  

• It filter only the traces that matches the configuration and not filter/ignore downstream traces.
  

Why filter some endpoints?

Not all traces are equal —filtering out low-priority endpoints reduces noise, optimizes data ingestion, and could cut unnecessary costs.

Filtering some traces are particularly useful when:

• You need the ability to control the data ingestion.

• You need to improve application performance by reducing tracing overhead.

• You aim to improve the focus on the high importance traces.

Filtering rules

Filtering traces for JDBC and HC are based on span attributes. A span represents a single unit of work or operation within a distributed system, serving as the fundamental building block of a trace. Spans have multiple attributes into their metadata and you can create a filters that use them. Below you see the span attributes and their names as they appear in the UI (User Interface). This blog are not showing all span attributes, but the main ones.

JDBC

JDBC UI Mapping

JDBC UI Mapping Error

HC

HC UI mapping

HC UI Error Mapping

Impact and Considerations

• Filtered Spans: Instana does not record or show filtered traces.
• Trace continuity: If the filter is applied to JDBC traces no impact will be noticed, because these calls are leafs in the trace tree, nothing comes after a JDBC call. For HC traces if they are leafs traces like JDBC no impact will be noticed, but if downstream traces happen after the HC call, only the HC call will be filtered, the existing downstream call would be orphan.
• Not filtering downstream calls: When we are using the current filter implementation we are just applying the filtering for the calls that match the configuration definition. The downstream traces won't be filtered. 

Configuration

Currently only one way of configuring filtering is available. It is through agent configuration.yaml file.

Agent Configuration

This method is used for centralised management, especially in environments with many micro-services. This allows you to apply consistent filter configuration across all services monitored by the agent, without touching individual application deployment or environment settings.

Example Configuration

com.instana.tracing:
  filter:
    deactivate: false
    exclude:
      - name: JDBC Oracle Filter
        attributes:
          - key: jdbc.statement
            values:
              - SELECT
              - CONNECT
            match_type: startswith
          - key: jdbc.connection
            values:
              - oracle
            match_type: contains
      - name: HC Filter
        attributes:
          - key: http.host
            values:
              - localhost:8022
          - key: http.params
            values:
              - test
            match_type: endswith

With this filter configuration, we have:

• The name section: JDBC name section and HC name section.
• The JDBC name section matches statements that startswith SELECT and CONNECT and matches connection that contains oracle.
• The HC name section matches host: localhost:8022 and matches params: that endswith test.
• The following fields are used:
  • filter: Mandatory. Key value for a list of filtering rules.
    • deactivate: Optional - Boolean. The default value is false. Feature toggle that will allow deactivating the filter configuration in case of specific need.
    • policy: Mandatory - String. Defined wether a rule should be included or excluded. Acceptable value: exclude.
    • name: Mandatory - String. Human readable key to describe the rule. If there a multiple rules, the tracer MUST apply logical OR when applying the rules.
    • attributes: Mandatory. Key value for a list of conditions. The conditions will apply a logical AND.
    • key: Mandatory - String. It defines the property that the condition will be applied to. The applicable values for filtering are:
      • span attribute.
      • Custom annotations: (anything with an sdk. prefix) MAY be ignored.
    • values: Mandatory - List of Strings. Values that the key should match using conditional OR.
    • match_type: Optional - String, default: strict. Defines how the values of the key MUST be matched. Acceptable values:
      • strict
      • startswith
      • endswith
      • contains

To apply:

• Save configuration.yaml.
• Each change will be loaded in the host application without need to restart.
• To remove the filter configuration do the following:
  
  • Remove the filter configuration from configuration.yaml and save the file.
  • Restart the host application.
• To deactivate the filter configuration use the deactivate optional field as true.

Trace view: Before and After JDBC Filter

The following examples show the application of filter configuration.

Configuration

com.instana.tracing:
  filter:
    deactivate: false
    exclude:
      - name: JDBC Oracle Filter
        attributes:
          - key: jdbc.statement
            values:
              - SELECT
              - INSERT
            match_type: startswith
          - key: jdbc.connection
            values:
              - oracle
            match_type: contains
          - key: jdbc.statement
            values:
              - Foo2
            match_type: contains

Before Filter Configuration

Before filter configuration application to filter INSERT and SELECT statements for Foo2 table.

After Filter Configuration

After applying filter configuration to filter INSERT and SELECT statements for Foo2 table these calls will be excluded.

Intermediate HC filtering

com.instana.tracing:
  filter:
    exclude:
      - name: HC Intermediate Filter
        attributes:
          - key: http.host
            values:
              - localhost:8093
             match_type: strict
          - key: http.params
            values:
              - name=domenico
            match_type: strict

Leaf HC Filtering

The filter would be applied in the leaf HC call GET /v1/hello-world-java-22.

Leaf HC configuration

com.instana.tracing:
  filter:
    exclude:
      - name: HC Leaf Filter
        attributes:
          - key: http.host
            values:
              - localhost:8022
             match_type: strict
          - key: http.params
            values:
              - domenico
            match_type: endswith

Limitations

• Recommended technologies: JDBC for database calls and HC (Http Client Calls) for http calls.
• No suppression.
• Trace availability: this feature is just available for Java tracer, but will be included in all traces in the future.

Conclusion

IBM Instana’s trace filtering gives you detailed control over observability data to trace. This feature enables you to:

• Reducing data ingestion.

• Focus monitoring on what truly matters.

When use this feature allow you to focus in the important parts of your observability strategy.

#Tracing

#Java