OneUptime Fluentd 日志接入实战:从 Fluentd 配置到 Telemetry Ingestion 全链路解析

原创2026-09-17 09:53:271,674 阅读
文章标签:可观测性后端运维前端云原生微服务AI Agent

OneUptime Fluentd 日志接入实战:从 Fluentd 配置到 Telemetry Ingestion 全链路解析

本文基于 OneUptime 官方文档 Fluentd 接入指南 展开,介绍如何使用 Fluentd 的 HTTP 输出插件将应用日志与遥测数据发送到 OneUptime 的 HTTP Source,并深入服务端 FluentLogsIngestService 的字段映射与 OTel 标准化实现。读完本文,你可以独立完成 Fluentd 配置、Token 申请、日志字段映射原理理解,以及本地容器化环境的端到端联调验证。

工作原理:Fluentd 通过 HTTP 输出插件对接 OneUptime HTTP Source

OneUptime 提供了专门的 Fluentd 接入端点,其核心链路如下:

Docker / Syslog / Nginx / MySQL / NodeJS / ...(任意 Fluentd 数据源)
        │
        ▼
   Fluentd(<match **> 匹配所有 tag)
        │  @type http,JSON 数组格式
        ▼
   https://oneuptime.com/fluentd/logs   (OneUptime HTTP Source)
        │  校验 x-oneuptime-token,按 x-oneuptime-service-name 归档服务
        ▼
   日志/指标/Trace → OneUptime 仪表盘

具体机制是:Fluentd 的 @type http 输出插件将所有 tag 的日志批量打包为 JSON 数组,以 POST 请求发送到 OneUptime 的 Fluentd 端点;请求头中携带 x-oneuptime-token(遥测摄入 Token)用于身份鉴权,x-oneuptime-service-name 用于指定日志归属的服务名。在服务端,该接入路由由 Fluent.ts 挂载——从源码结构看,路由在处理前会执行 Telemetry 摄入禁用检查,并将请求的产品类型标记为 ProductType.Logs,随后交由 FluentLogsIngestService.ingestFluentLogs 完成解析与入库。

支持的数据源

Fluentd 生态本身支持数百种数据源,因此 OneUptime 可以通过 Fluentd 间接接入几乎所有类型的日志。官方文档列出的常见数据源包括:

  • Docker
  • Syslog
  • Apache
  • Nginx
  • MySQL
  • PostgreSQL
  • MongoDB
  • NodeJS
  • Ruby
  • Python
  • Java
  • PHP
  • Go
  • Rust

更完整的源插件列表可查阅 Fluentd 官方数据源目录。

前置条件

  1. 安装 Fluentd:按 Fluentd 官方安装指南在目标系统上安装(支持 Docker、源码编译、包管理器等方式)。
  2. 注册 OneUptime 账号:账号本身免费,但日志摄入(Log Ingestion)属于计费功能,计费细节以官方定价页为准。
  3. 创建 OneUptime 项目:登录 OneUptime 控制台后,在 Dashboard 中创建一个项目。
  4. 创建遥测摄入 Token(Telemetry Ingestion Key):
    • 在导航栏点击 "Products",再点击 "Project Settings";
    • 进入 Telemetry Ingestion Key 页面,点击 "Create Ingestion Key" 创建 Token;
    • 创建完成后点击 "View" 查看并复制完整 Token。

核心配置:fluent.conf 详解

将以下配置追加到 Fluentd 配置文件(通常位于 /etc/fluentd/fluent.conf 或 /etc/td-agent/td-agent.conf)中,替换 YOUR_SERVICE_TOKEN 为上一步创建的 Token,YOUR_SERVICE_NAME 替换为你想用的服务名——服务名可以是任意字符串,若该服务在 OneUptime 中尚不存在,会被自动创建:

# Match all patterns
<match **>
@type http

endpoint https://oneuptime.com/fluentd/logs
open_timeout 2

headers {"x-oneuptime-token":"YOUR_SERVICE_TOKEN", "x-oneuptime-service-name":"YOUR_SERVICE_NAME"}

content_type application/json
json_array true

<format>
@type json
</format>
<buffer>
flush_interval 10s
</buffer>
</match>

逐项参数说明:

参数 作用
<match **> 匹配所有 tag 的日志事件,实现"全量转发";如需只转发特定来源可收窄为具体 tag
@type http 使用 Fluentd 内置 HTTP 输出插件发送请求
endpoint OneUptime 的 Fluentd 摄入端点,私有化部署时替换为自建实例地址(见下文)
open_timeout 2 建立连接的超时时间(秒)
headers 鉴权与路由头:x-oneuptime-token 携带摄入 Token,x-oneuptime-service-name 指定服务名
content_type application/json 请求体以 JSON 编码
json_array true 将缓冲区内多条记录打包为 JSON 数组一次性发送,降低请求开销
<format> @type json 每条日志序列化为 JSON 对象
<buffer> flush_interval 10s 缓冲区每 10 秒批量刷新一次,平衡实时性与吞吐

一个包含输入源的完整配置文件示例如下:

####
## Source descriptions:
##

## built-in TCP input
## @see https://docs.fluentd.org/input/forward
<source>
@type forward
port 24224
bind 0.0.0.0
</source>

<match **>
@type http

endpoint https://oneuptime.com/fluentd/logs
open_timeout 2

headers {"x-oneuptime-token":"YOUR_SERVICE_TOKEN", "x-oneuptime-service-name":"YOUR_SERVICE_NAME"}

content_type application/json
json_array true

<format>
@type json
</format>
<buffer>
flush_interval 10s
</buffer>
</match>

仓库中同样维护了一份可直接运行的参考配置 Fluentd/fluent.conf,其中除 forward 输入源外还额外声明了 HTTP 输入源(@type http,端口 8888,body_size_limit 32m、keepalive_timeout 10s),方便通过 curl 直接向容器投递测试日志。

自建(Self-Hosting)环境的端点替换

如果你使用的是私有化部署的 OneUptime 实例,只需将 endpoint 替换为自建实例地址:

http(s)://YOUR_ONEUPTIME_HOST/fluentd/logs

其余配置保持不变。

服务端实现解析:日志如何被解析与标准化

Token 校验通过后,日志的处理由 FluentLogsIngestService 完成。该服务继承自 OtelIngestBaseService,负责把杂乱的 Fluentd 日志字段规范化为 OTel 语义。阅读源码可以得到几个对配置者很有价值的实现事实:

  • 日志正文字段按优先级探测:BODY_FIELDS 依次尝试 message、log、msg、body、text,即你无需强制约定字段名,常见的日志正文字段都能被识别。
  • 严重级别映射:SEVERITY_FIELDS 支持 level、severity、loglevel、log_level、priority、severityText、severity_text 等字段;SEVERITY_TEXT_MAP 将 trace/debug/info/warn/error/critical/fatal/emergency 等文本映射到 OTel 标准 severity number(1/5/9/13/17/21/23),例如 warn 与 warning 都映射为 13(Warning),err 与 error 都映射为 17(Error)。
  • Trace 关联字段:TRACE_ID_FIELDS(trace_id/traceId/traceid)与 SPAN_ID_FIELDS(span_id/spanId/spanid)会被提取出来用于链路关联。
  • 默认服务名:当请求未携带有效服务名时,服务名默认回退为 Fluentd(DEFAULT_SERVICE_NAME)。
  • 存储路径:从源码结构看,日志经队列缓冲(FluentLogsQueueService)、管道处理(LogPipelineService)与丢弃/脱敏规则(LogDropFilterService、LogScrubRuleService)后,批量写入 ClickHouse 存储,批量大小由 TELEMETRY_LOG_FLUSH_BATCH_SIZE 控制;未识别为标量索引键的其余字段会保留为属性,而已被单独提取的字段(正文、级别等)会被排除,避免在属性中重复出现。

这一实现意味着你在 Fluentd 侧只要输出标准 JSON 日志即可,OneUptime 会自行完成字段识别、级别归一化和 OTel 语义对齐。

本地容器化联调验证

仓库内提供了完整的 Fluentd 联调环境,可直接用于验证自己的配置是否正确(参考 Fluentd/README.md):

  1. 确认 Fluentd/fluent.conf 中已填入你自己的 Token 与服务名;
  2. 构建并启动容器:
npm run force-build fluentd
npm run dev fluentd
  1. 向 Fluentd 容器的 HTTP 输入源(8888 端口)投递一条测试日志:
curl -X POST -d 'json={"action":"login","user":2}' http://localhost:8888/test.tag.here

容器镜像由 Fluentd/Dockerfile.tpl 构建,基于官方 fluentd 基础镜像并额外安装 bash 与 curl,EXPOSE 24224(forward 协议)与 EXPOSE 8888(HTTP 输入)两个端口。日志成功送达后,在 OneUptime 仪表盘对应服务下即可看到该条日志。

上线步骤与验证

  1. 将配置写入生产环境的 Fluentd 配置文件并替换 Token 与服务名;
  2. 重启 Fluentd 服务使配置生效;
  3. 在 OneUptime 仪表盘确认日志开始流入对应服务。

需要注意的几个要点:

  • 服务名即隔离维度:不同应用建议使用不同的 x-oneuptime-service-name,OneUptime 会按服务名自动建档,便于后续按服务检索、设置告警。
  • Token 安全:x-oneuptime-token 是摄入凭证,避免提交到代码仓库或写入共享配置;仓库内的参考配置 Fluentd/fluent.conf 中带有示例 Token,生产使用前务必替换。
  • 批量与缓冲:flush_interval 10s 决定了日志可见性的最大延迟约 10 秒;如日志量大可结合 Fluentd 自身的 buffer 策略(chunk、重试等)进一步调优,OneUptime 端点为 JSON 数组批量接口,天然适配批量发送。
  • 计费前提:账号注册免费,但日志摄入属于计费功能,正式接入前请确认套餐额度。

小结

OneUptime 的 Fluentd 接入方案刻意保持轻量:Fluentd 侧只需一个 <match **> 块加两个请求头,端点、鉴权、服务路由全部收敛在 HTTP 协议层;服务端则由 FluentLogsIngestService 完成字段探测、OTel 级别映射与 ClickHouse 落盘。这套组合让你无需改造应用日志格式,即可把 Docker、Nginx、MySQL、Go、Rust 等任意 Fluentd 可采集的日志源接入 OneUptime 的统一遥测体系。

登录后查看全文
oneuptime