目录
-
- 一、概述
- 二、配置与执行机制
-
- [1. 配置模型](#1. 配置模型)
- [2. 上下文层级执行](#2. 上下文层级执行)
- [3. 两种配置风格](#3. 两种配置风格)
- [4. 错误处理模式（`error_mode`）](#4. 错误处理模式（
error_mode）) - [5. Context Inference（上下文自动推断）](#5. Context Inference（上下文自动推断）)
- [6. 指标专用函数](#6. 指标专用函数)
- [7. 迁移与风险](#7. 迁移与风险)
- [三、适合使用 Filter Processor 的场景（重点）](#三、适合使用 Filter Processor 的场景（重点）)
- [1. 降本控量（最常见）](#1. 降本控量（最常见）)
- [2. 按环境/租户隔离](#2. 按环境/租户隔离)
- [3. 快速拦截敏感日志](#3. 快速拦截敏感日志)
- [4. 过滤低价值调用链噪声](#4. 过滤低价值调用链噪声)
- [5. 仅保留错误与慢请求](#5. 仅保留错误与慢请求)
- [6. 指标质量治理](#6. 指标质量治理)
- [7. 灰度与迁移期临时止噪](#7. 灰度与迁移期临时止噪)
- [8. 多团队共享 Collector 的边界控制](#8. 多团队共享 Collector 的边界控制)
- 四、关键限制（容易误解）
- 五、落地建议（避免误删）
一、概述
Filter Processor 的作用 ：在 OpenTelemetry Collector 中，基于 OTTL 条件丢弃 不需要的遥测数据。
支持信号类型：traces / metrics / logs / profiles。
规则语义：同一列表中的条件是 OR 关系，任一条件命中即丢弃。
注：特别注意Filter Processor 不能直接按"整条 trace"删除（用 filter processor 时）。
它的作用粒度是 span / spanevent（以及其他信号），不是 trace 级对象。
如果你要"要么整条保留、要么整条丢弃"，更合适的是用 tail_sampling processor 按策略对 trace_id 做最终决策；
filter 只能通过条件删 span，容易出现不完整 trace。
二、配置与执行机制
1. 配置模型
按信号分别配置：
trace_conditionsmetric_conditionslog_conditionsprofile_conditions
配置示例：
yaml
processors:
filter:
error_mode: propagate
trace_conditions:
- span.attributes["container.name"] == "app_container_1"
- resource.attributes["host.name"] == "localhost"
- span.name == "app_3"
metric_conditions:
- metric.name == "my.metric" and resource.attributes["my_label"] == "abc123"
- metric.type == METRIC_DATA_TYPE_HISTOGRAM
- resource.attributes["service.name"] == "my_service_name"
log_conditions:
- IsMatch(log.body, ".*password.*")
- log.severity_number < SEVERITY_NUMBER_WARN
profile_conditions:
- profile.duration_unix_nano > 30002. 上下文层级执行
按层级从高到低评估（不同信号层级不同）：
- Logs：
resource -> scope -> log - Metrics：
resource -> scope -> metric -> datapoint - Traces：
resource -> scope -> span -> spanevent
高层命中后，低层不会再评估。
3. 两种配置风格
- Basic Config：直接写条件列表（最常用、最简单）
- Advanced Config ：可显式指定
context，并可对条件组单独指定error_mode
4. 错误处理模式（error_mode）
ignore（推荐）：忽略错误并记录日志，继续处理silent：忽略错误且不记录日志propagate：错误向上抛出，可能导致该 payload 被丢弃
5. Context Inference（上下文自动推断）
通常无需手动写 context，处理器会根据路径前缀自动推断。
若函数与路径上下文不兼容（例如 IsRootSpan() 与 spanevent 混用），需要拆分条件并显式指定 context。
6. 指标专用函数
HasAttrKeyOnDatapoint(key)HasAttrOnDatapoint(key, value)
7. 迁移与风险
- 旧配置（如
traces.span、logs.log_record等）已弃用，建议迁移到*_conditions。 - 误删风险需重点关注，尤其是 traces 中删除父 span 可能产生 orphaned telemetry。
三、适合使用 Filter Processor 的场景（重点）
1. 降本控量（最常见）
目标 ：减少存储、传输、索引成本。
示例：
- 丢弃低级别日志：
log.severity_number < SEVERITY_NUMBER_WARN - 丢弃噪声 span（探活、静态资源、内部噪声调用）
- 丢弃无效指标类型：
metric.type == METRIC_DATA_TYPE_NONE
2. 按环境/租户隔离
目标 ：只保留关键环境或关键租户数据。
示例：
resource.attributes["deployment.environment"] != "prod"resource.attributes["tenant.id"] == "test-tenant"
3. 快速拦截敏感日志
目标 ：避免敏感信息外发到后端。
示例：
IsMatch(log.body, ".*password|token|secret.*")
适合紧急止血；长期建议结合脱敏处理器，而不仅是删除。
4. 过滤低价值调用链噪声
目标 ：减少健康检查、探针、非业务请求对追踪系统的干扰。
示例：
- 非 HTTP span：
span.attributes["http.request.method"] == nil - 按
span.name或 RPC 相关属性匹配噪声模式
5. 仅保留错误与慢请求
目标 ：面向故障排查，降低正常请求开销。
示例：
(span.end_time - span.start_time) < Duration("1s") and span.status.code != STATUS_CODE_ERROR
6. 指标质量治理
目标 ：剔除脏数据/异常数据点，提升指标可信度。
示例：
metric.name == "k8s.pod.phase" and datapoint.value_int == 4HasAttrOnDatapoint("bad.metric", "true")
7. 灰度与迁移期临时止噪
目标 ：快速压制新版本引入的遥测突增。
建议：临时规则需标注失效时间，避免长期残留。
8. 多团队共享 Collector 的边界控制
目标 ：在统一采集前提下，按服务/团队边界预过滤。
示例：
- 按
service.name、scope.name或业务标签进行过滤。
四、关键限制（容易误解）
- Filter Processor 不能直接按"整条 trace"删除（不是 trace 粒度决策）。
- 它是 span/spanevent 粒度过滤，可能造成 trace 不完整。
- 若需求是"整条 trace 保留或整条丢弃"，应优先考虑 tail_sampling processor。
五、落地建议（避免误删）
- 默认采用
error_mode: ignore，先保证可用性与韧性。 - 条件尽量"窄且准"（服务 + 环境 + 事件名组合），避免宽泛正则。
- 先开 debug 观察命中，再正式启用规则。
- traces 场景谨慎删除父 span，防止 orphaned telemetry。
- 能在
resource/scope高层过滤的，尽量前移以提升性能与稳定性。
GPT-5.3-Codex • 2.1 credits
参考：
https://opentelemetry.io/docs/collector/configuration/#processors