OpenTelemetry Filelog Receiver：日志文件摄取指南

Source: Dev.to

Filelog 接收器的工作原理

在深入配置细节之前，先想象一下接收器在整个生命周期中如何处理日志文件。它以一个简单的四步循环不断重复：

• Discover（发现）： 按照您设置的 include 和 exclude 模式，定期扫描文件系统，以确定要监控的日志文件。
• Read（读取）： 打开每个选中的文件，并在新行写入时持续跟踪。start_at 设置决定是从 beginning（文件开头）开始，还是从 end（文件末尾）开始捕获新内容。
• Parse（解析）： 每一行（如果使用多行解析，则是一组行）会经过一系列 Stanza 操作符（如果已配置）。操作符解析原始文本，提取关键属性，分配时间戳和严重性级别，并将日志数据结构化。
• Emit（发出）： 结构化的日志记录被送入 Collector 的管道，在那里可以进行 过滤、进一步转换，或导出到您的后端。

Discover → Read → Parse → Emit 循环构成了接收器所做一切的基础。

快速入门：尾随（tail）日志文件

一个常见的使用场景是应用已经以 JSON 格式将日志写入文件，例如 /var/log/myapp/app.log：

{"time":"2025-09-28 20:15:12","level":"INFO","message":"User logged in successfully","user_id":"u-123","source_ip":"192.168.1.100"}
{"time":"2025-09-28 20:15:45","level":"WARN","message":"Password nearing expiration","user_id":"u-123"}

最小化 filelog 接收器配置

# otelcol.yaml
receivers:
  filelog:
    # 1. DISCOVER /var/log/myapp/ 下所有 .log 文件
    include: [/var/log/myapp/*.log]
    # 2. READ 从新文件的开头开始
    start_at: beginning
    # 3. PARSE 使用 json_parser 操作符
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time
          layout: "%Y-%m-%d %H:%M:%S"
        severity:
          parse_from: attributes.level

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    logs:
      receivers: [filelog]
      exporters: [debug]

配置拆解

• include：指向 /var/log/myapp/ 中所有 .log 文件。
• start_at: beginning：首次看到文件时处理整个文件。默认值（end）只会捕获 Collector 启动后新增的行。
• operators：这里使用单个 json_parser 将每行解释为 JSON，并将选定字段提升为日志记录的核心元数据。
• timestamp 与 severity：从 JSON 中提取 time 和 level 字段，并映射到 OpenTelemetry 的顶层 Timestamp 与 Severity* 字段。

使用 debug 导出器时，您会看到解析后结构化的输出：

LogRecord #0
ObservedTimestamp: 2025-09-28 20:48:36.728437503 +0000 UTC
Timestamp: 2025-09-28 20:15:12 +0000 UTC
SeverityText: INFO
SeverityNumber: Info(9)
Body: Str({"time":"2025-09-28 20:15:12","level":"INFO","message":"User logged in successfully","user_id":"u-123","source_ip":"192.168.1.100"})
Attributes:
     -> user_id: Str(u-123)
     -> source_ip: Str(192.168.1.100)
     -> log.file.name: Str(myapp.log)
     -> time: Str(2025-09-28 20:15:12)
     -> level: Str(INFO)
     -> message: Str(User logged in successfully)
Trace ID:
Span ID:
Flags: 0

原始的 JSON 日志现已被转换为 OpenTelemetry 统一的日志数据格式，为跨系统可观测性提供了一致的基础。

添加完整文件路径

接收器会自动添加 log.file.name 属性。若还想捕获完整路径，可启用 include_file_path：

# otelcol.yaml (excerpt)
receivers:
  filelog:
    include: [/var/log/myapp/*.log]
    include_file_path: true

生成的属性示例：

Attributes:
     -> log.file.path: Str(/var/log/myapp/app.log)
     -> log.file.name: Str(app.log)

更多丰富选项请参阅 官方 OpenTelemetry Filelog 接收器文档。

过滤与管理日志文件

配置 filelog 接收器的根本步骤是通过 include 与 exclude glob 模式指定要监控的文件。接收器首先使用 include 生成文件列表，然后使用 exclude 从该列表中剔除匹配的文件。

# otelcol.yaml
receivers:
  filelog:
    include: [/var/log/apps/**/*.log]
    exclude:
      - /var/log/apps/**/debug.log
      - /var/log/apps/**/*.tmp

在此示例中，/var/log/apps/ 及其子目录下的所有 .log 文件都会被收集，除去名为 debug.log 的文件以及所有以 .tmp 结尾的文件。

按修改时间排除文件

如果您读取的日志目录中已有大量历史日志文件，可以指示接收器忽略在一定时间范围内未被修改的文件，…