📚 课程目录第4章日志处理与转换

4. 日志处理与转换：使用 Processor 对日志进行清洗、富化和采样

在 OpenTelemetry Collector 的数据流水线中，Processor 是连接 Receiver 与 Exporter 的核心中间件。它负责对采集到的日志记录执行清洗、格式转换、字段富化、数据采样等操作，是保障日志质量、控制存储成本、提升可观测性的关键环节。

4.1 Processor 在流水线中的位置与作用

Processor 位于 Receiver 之后、Exporter 之前，可以串联多个形成处理链。每个 Processor 接收日志数据，经过内部逻辑处理后，将结果传递给下一个 Processor 或最终的 Exporter。

4.2 核心 Processor 类型与功能

OpenTelemetry Collector 提供了丰富的内置 Processor，以下是在日志场景中最常用的三种：

Processor 名称	核心功能	典型应用场景
attributes	对日志记录的属性（attributes）进行增、删、改、正则替换	添加环境标签、脱敏敏感字段、统一字段命名规范
batch	将多条日志合并为一批，按时间或数量触发发送	降低网络开销、提升 Exporter 吞吐量、减少后端写入压力
filter	根据条件表达式过滤日志记录，决定保留或丢弃	丢弃调试日志、只保留 ERROR 级别日志、按服务名筛选

4.3 attributes Processor：日志清洗与富化

attributes Processor 是日志处理中最灵活的组件，支持以下操作：

插入（insert）：向日志记录中添加新的属性键值对。
更新（update）：修改已有属性的值。
删除（delete）：移除不需要的属性。
哈希（hash）：对指定属性值进行 SHA-1 哈希，用于脱敏。
提取（extract）：从已有属性中通过正则表达式提取子串，生成新属性。
转换（convert）：改变属性值的数据类型。

实战案例：日志清洗与富化配置

processors:
  attributes/log_clean:
    actions:
      # 1. 删除敏感字段
      - key: password
        action: delete
      - key: credit_card
        action: delete
      # 2. 对用户 ID 进行哈希脱敏
      - key: user_id
        action: hash
      # 3. 插入环境标签
      - key: environment
        value: "production"
        action: insert
      # 4. 从日志消息中提取错误码
      - key: error_code
        pattern: "ERR-([0-9]{4})"
        action: extract
      # 5. 将时间戳转换为标准格式
      - key: timestamp
        action: convert
        converted_type: int

4.4 batch Processor：日志批处理与性能优化

batch Processor 通过聚合日志记录来优化传输效率，是生产环境中必不可少的组件。其核心参数包括：

参数	默认值	说明
`timeout`	200ms	等待批处理完成的最长时间，超时后即使未满也发送
`send_batch_size`	8192	触发发送的日志条目数阈值
`send_batch_max_size`	0（无限制）	单个批次的最大条目数上限，防止内存溢出

性能调优建议：对于高吞吐日志场景，建议将 timeout 设置为 500ms-1s，send_batch_size 设置为 16384-32768，以平衡延迟与吞吐量。注意监控 Collector 的内存使用情况，避免 send_batch_max_size 设置过大导致 OOM。

4.5 filter Processor：日志采样与过滤

filter Processor 支持基于日志级别、服务名称、属性值等条件进行过滤，是控制日志存储成本的核心手段。

实战案例：基于日志级别的采样配置

processors:
  filter/log_level_sampling:
    logs:
      # 保留所有 ERROR 及以上级别日志
      - severity_text: "ERROR"
        severity_text: "FATAL"
      # 对 INFO 级别日志进行概率采样
      - severity_text: "INFO"
        probabilistic_sampler:
          sampling_percentage: 10.0
      # 丢弃 DEBUG 级别日志
      - severity_text: "DEBUG"
        action: drop

4.6 Processor 链编排与最佳实践

在实际部署中，多个 Processor 通常按以下顺序编排：

filter Processor（最先执行）：尽早丢弃不需要的日志，减少后续处理压力。
attributes Processor（中间执行）：对保留的日志进行清洗、脱敏、富化。
batch Processor（最后执行）：将处理后的日志聚合为批次，发送给 Exporter。

注意事项：

filter Processor 应放在最前面，避免对无用日志执行昂贵的清洗操作。
batch Processor 应放在最后，确保所有属性修改完成后再进行聚合。
避免在 Processor 链中重复执行相同操作，例如多次哈希同一个字段。
生产环境中建议为每个 Processor 配置独立的 id，便于监控和调试。

4.7 完整流水线配置示例

以下是一个完整的日志处理流水线配置，展示了 Processor 链的串联方式：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  filter/drop_debug:
    logs:
      - severity_text: "DEBUG"
        action: drop

  attributes/enrich:
    actions:
      - key: environment
        value: "production"
        action: insert
      - key: source
        value: "kubernetes"
        action: insert

  batch/optimize:
    timeout: 500ms
    send_batch_size: 16384
    send_batch_max_size: 32768

exporters:
  otlphttp/prometheus:
    endpoint: http://prometheus-server:9090/api/v1/otlp
  elasticsearch:
    endpoints: ["http://elasticsearch:9200"]

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [filter/drop_debug, attributes/enrich, batch/optimize]
      exporters: [otlphttp/prometheus, elasticsearch]

通过合理配置 Processor 链，可以实现对日志数据的精细化控制，在保证可观测性的同时，有效降低存储成本和网络开销。