配置 Java 应用程序的过滤规则

在线编辑

您可以通过根据特定跨度属性进行过滤，来减少 Java 应用程序的跟踪数据量。 此功能有助于优化数据采集成本，并聚焦于最符合您应用程序监控需求的追踪记录。

在 Java 应用程序中， HTTP 和 JDBC 的跨域请求支持基于属性的过滤。 有关减少从跟踪中摄入的数据的更多信息，请参阅 《 Instana 》中的“优化数据摄入 ”。

过滤选项

在线编辑

您可以通过以下方法过滤 Java 应用程序的跟踪信息：

  • 基于方法的过滤 ：若要过滤来自 DynamoDB,、 Redis 和 Kafka 的跨域请求，请参阅 “忽略端点”。 借助此功能，您可以根据方法名称（例如 GET、 consume或 query）和端点（例如 Kafka 主题名称）来排除跟踪记录。
  • 基于 span 属性的过滤 ：若要过滤 HTTP 和 JDBC 中的 span 标签，请使用基于 span 属性的过滤方法。 此功能提供了基于多个跨度属性的高级过滤功能，例如 URL、SQL 语句或 HTTP 方法。 该方法支持灵活的模式匹配（strict, startswith, endswith, 和 contains），并允许在单条规则中组合多个属性。

有关基于 span 属性的过滤的详细配置说明，请参阅以下各节。

参考轨迹示例

在线编辑

以下示例展示了一个未应用任何过滤的完整跟踪记录，本文档中将以此作为参考基准：

基于Span属性的过滤

在线编辑

Java 应用程序的跨属性过滤功能只能通过代理 configuration.yaml 文件进行配置。 环境变量和系统属性不支持用于过滤配置。

注意： 配置更改在初始设置后会动态应用，无需重新启动应用程序。

过滤配置

在线编辑

您可以配置过滤规则，根据属性（例如 URL、SQL 语句或 HTTP 方法）将 HTTP 和 JDBC 范围排除在外。

过滤规则在代理 configuration.yaml 文件（instanaAgentDir/etc/instana/configuration.yaml）的 部分 com.instana.tracing.filter 中定义。该配置使用 YAML 结构，根据 span 属性来定义过滤规则。

要定义过滤规则，请使用以下配置：

com.instana.tracing:
  filter:
    deactivate: <boolean>
    exclude:
      - name: <string>
        attributes:
          - key: <string>
            values: [<string>, ...]
            match_type: <string>
重要提示： 您可以在策略 exclude 中定义多个过滤规则。 每条规则可包含多个属性，所有属性必须完全匹配才能触发该规则。
字段 必需 描述
filter 必需 所有过滤规则的根节点。
deactivate 可选 功能开关，用于关闭过滤功能而不删除已配置的过滤规则。 当设置为 true时，过滤功能将被禁用。 默认值为 false （过滤功能保持激活状态）。
exclude 必需 用于排除跟踪中跨度段的排除规则策略。 目前仅支持该 exclude 策略。
name 必需 描述过滤规则的人类可读名称。
attributes 必需 必须全部匹配的span属性列表，规则方可生效。
key 必需 Span 属性键。
values 必需 span 属性的匹配 key值列表。 若其任意属性 values 匹配，则该属性匹配。 使用 '*' 作为通配符，匹配指定属性键的任意值（适用于基于属性存在性进行过滤，而不考虑具体值）。
match_type 可选 定义跨度 values 属性的匹配方式。 有效值： strict (默认值)、 startswith、 endswith 和 contains。

抑制行为

当跨度被过滤规则排除时， HTTP 与 JDBC 的抑制行为存在差异：
  • HTTP 过滤 ：默认启用抑制功能。 当排除 HTTP 跨度时，所有子跨度和下游追踪都会自动被抑制。 对于任何数据库调用、外部服务调用或其他由被排除的 HTTP 请求触发的操作，均不会生成跨度。
  • JDBC 过滤 ： 未应用抑制。 当排除 JDBC 跨度时，子跨度和跟踪中的后续操作仍将继续被捕获。
重要提示： 该 suppression 配置参数无法进行配置。 抑制行为将根据跨度类型自动确定。

通配符用法

您可以在 values 字段中使用 "*" 通配符 来匹配特定跨度属性的任意值。 当您希望根据属性的存在（无论其值为何）来过滤跨度时，此方法非常有用。 通配符可用于 HTTP 和 JDBC 过滤。

示例：要排除所有具有 error 属性的 span（无论错误消息内容如何），请使用以下配置：

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

规则执行顺序

过滤规则按其在配置中的出现顺序进行评估。 当某个跨度匹配某个过滤规则时，该规则将被应用，且后续规则将不再对此跨度进行评估。 在 exclude 策略中，第一个匹配规则决定了过滤行为。

重要提示： 请将规则从最具体的排列到最一般的，以确保应用正确的过滤行为。

示例：

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

在此示例中，若某个span元素匹配 /api/internal/health，则应用第一条规则。 如果某个跨度匹配 /health 但不匹配 /api/internal/health，则适用第二条规则。 顺序很重要，因为会使用第一个匹配规则。

HTTP 端点过滤

在线编辑

通过 HTTP 端点过滤功能，您可以根据 URL、方法和头部等属性排除 HTTP 的span。 此功能支持以下 HTTP 框架：

  • Servlet ：使用 Java Servlet的應用程式 API
  • Spring Web ：使用 Spring MVC 和 Spring Boot 的应用程序
重要提示： 当排除 HTTP 跨度时，默认会应用抑制机制。 所有子跨度和下游追踪都会自动抑制，包括任何数据库调用、外部服务调用或其他由被排除的 HTTP 请求触发的操作。

HTTP 端点过滤的跨度属性

您可以使用以下span属性来过滤 HTTP 端点。 "UI显示名称"列显示了在 Instana 用户界面中查看跨度详细信息时，每个属性的显示方式。

重要提示： 下表中显示的用户界面名称均为英文。 如果您使用的是其他语言版本的 Instana 用户界面，这些标签将根据您的语言设置进行翻译。 不过，span 属性的键（用于过滤配置）在所有语言中都保持一致。 有时用户界面显示名称可能与本表中呈现的映射存在差异。
Span属性 用户界面显示名称 描述 示例值 过滤支持
http.url URL URL 或路径 /api/users 是
http.method 方法 HTTP 方法 GET 是
http.status 状态码 Http 响应状态代码 200 有限*
http.host 主机 主机名及端口 localhost:8080 是
http.path 请求路径 请求路径 /api/users 是
http.path_tpl 路径模板 路由模板或模式 /api/users/{id} 是
http.params 参数 HTTP 查询字符串 action=edit&id=5 是
http.error 错误 错误消息 错误描述 有限*
http.header.<header-name> 页眉 HTTP 请求头 header-value 是
http.header.<response-header-name> 页眉 HTTP 响应头 header-value 有限*
* 过滤功能受限 ：仅在 HTTP 请求完成后才可用的Span属性（如 http.status 响应头 http.header.<response-header-name>）具有有限的过滤能力。 基于这些属性的过滤规则可以排除特定跨度，但无法强制抑制子跨度和下游追踪，因为在做出抑制决策时，这些属性的值尚未确定。

用户界面显示差异

虽然过滤配置中的跨度属性键保持不变，但 Instana 用户界面中的实际显示值可能因上下文而异：

  • http.status显示状态代码并附带可读描述（例如， 200 – OK、或 500 – Internal Server Error） 404 – Not Found。 过滤时，仅使用数字状态码值。
  • http.error仅当错误值为非空字符串时，才在用户界面中显示。 此外，若该属性包含由 Java 追踪器敏感数据配置所定义的敏感数据，则可能被屏蔽。 空值或被编辑的错误不会在用户界面中显示。
  • http.params当查询字符串为空或空白时，用户界面将显示 <no query parameters> 而非空值。 在过滤时，需与实际查询字符串值进行匹配，或使用空字符串。
  • http.url仅当与不同时在 http.path用户界面中显示。 若两个值完全相同，则仅显示路径以避免冗余。
重要提示： 这些显示方式不会影响筛选功能。 过滤规则始终与后端存储的原始span属性值进行匹配，而非用户界面中显示的格式化值。

HTTP 端点过滤配置示例

以下示例展示了 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

在上例中，过滤配置强制执行以下规则：

  • 不包括其 URL 以 /health, /ping, 或 结尾的 HTTP/ready跨度。 子进程跨度和下游跟踪将被自动抑制。
  • 不包括使用 ` HTTP ` 方法的 ` HTTPOPTIONS` 跨度。 子进程跨度和下游跟踪将被自动抑制。

以下示例展示了 HTTP 滤波器在抑制模式下的效果。 将此跟踪记录与未过滤的完整跟踪记录（图1）对比时，可见 HTTP 调用及其所有子跨度均被过滤掉，这些调用携带的参数 author=test2 ：

JDBC span过滤

在线编辑

借助 JDBC 的跨度过滤功能，您可以根据属性（如SQL语句、连接字符串和错误消息）排除数据库跨度。

重要提示： 与 HTTP 过滤不同， JDBC 过滤不会抑制下游的跟踪。 当排除 JDBC 跨度时，子跨度和跟踪中的后续操作仍将继续被捕获。

JDBC 的span过滤器属性

您可以使用以下跨度属性来过滤 JDBC 跨度。 "UI显示名称"列显示每个属性在 Instana 用户界面中查看跨度详细信息时的显示方式。

注： 下表中显示的用户界面名称均为英文。 若您使用的是其他语言版本的 Instana 用户界面，这些标签将根据您的语言设置进行翻译，但用于过滤配置的span属性键在所有语言中保持不变。
Span属性 用户界面显示名称 描述 示例值
jdbc.connection 连接 JDBC 连接字符串 jdbc:mysql://localhost:3306/mydb
jdbc.statement 语句 SQL 语句 SELECT * FROM users
jdbc.error 错误 错误消息 SQL错误描述

用户界面显示差异

与 HTTP 中的 spanned 属性类似， JDBC 中的 spanned 属性在 Instana 界面中可能呈现不同样式：

  • jdbc.error仅当错误值为非空字符串时，才在用户界面中显示。 若该属性包含由 Java 追踪器敏感数据配置所定义的敏感数据，则可能被屏蔽。 空值或被编辑的错误不会在用户界面中显示。
  • jdbc.statement当SQL语句超过特定长度时，系统可能出于显示目的在用户界面截断部分内容，但完整语句仍用于过滤评估。
重要提示： 这些显示方式不会影响筛选功能。 过滤规则始终与存储在后端的原始span属性值进行匹配。

示例： JDBC 跨度过滤配置

以下示例展示了 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

在上例中，过滤配置强制执行以下规则：

  • 不包括 SQL 语句中包含 `` audit_log 或 `` 的 ` JDBCsession_data` 跨度。
  • 不包括以 开头的 SELECTJDBC 跨度中的SQL语句，以及包含 的连接 mysql字符串。
  • 排除所有包含错误消息的 JDBC 标记（使用 '*' 通配符匹配任何错误值）。

以下示例展示了 JDBC 过滤的效果。 将此跟踪与未过滤的完整跟踪（图1）进行比较时，可见 JDBC 语句 select book0_.id as id1_0_, book0_.author as author2_0_, book0_.title as title3_0_ from book book0_ where book0_.author=? 已被过滤，导致跟踪中移除了两个跨度：

HTTP 与 JDBC 组合过滤示例

在线编辑

以下示例展示了如何同时配置 HTTP 和 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

在此示例中：

  • HTTP 与健康检查端点匹配的跨度将通过自动抑制功能排除（子跨度和下游追踪将被抑制）。
  • JDBC 临时表的跨度被排除，且不进行抑制（子跨度和下游跟踪仍继续捕获）。

过滤的局限性

在线编辑
  • 政策支持 ：目前仅支持该 exclude 政策。 该 include 政策尚未发布。
  • 抑制行为 ：
    • HTTP 过滤默认应用抑制（子跨度和下游跟踪将被抑制）。
    • 该 suppression 配置参数无法进行配置。
  • 对某些 HTTP 属性的抑制支持有限 ：基于仅在 HTTP 请求完成后才可知的span属性（如响应头 http.header.<response-header-name>http.status 中的和 http.error）制定的过滤规则，无法强制抑制子span和下游追踪。 这些属性仍可用于将父级 HTTP 跨度排除在跟踪之外。 然而，任何子跨度或下游操作仍会被捕获，这可能导致UI中出现缺少父跨度的跨度。
  • 基于span http.params 属性的过滤规则可能失效，若该 values 属性包含机密内容，这些内容可能被 Java Tracer从 HTTPURL 中删除。
  • 过滤配置更改在初始设置后会动态应用，无需应用程序重启。