使用 Fluentd 将日志与遥测数据接入 OneUptime:HTTP 输出插件完整配置指南
使用 Fluentd 将日志与遥测数据接入 OneUptime:HTTP 输出插件完整配置指南
Fluentd 是生态最丰富的开源日志采集器之一,而 OneUptime 提供开箱即用的遥测摄取(Telemetry Ingestion)能力。本文将基于 OneUptime 官方文档与仓库源码,讲解如何通过 Fluentd 内置的 http 输出插件,把来自 Docker、Nginx、MySQL 等数百种数据源的日志批量投递到 OneUptime HTTP Source,并深入解析摄取端的字段映射、严重级别换算与队列落库链路。读完本文,你将能独立完成 Token 创建、fluent.conf 配置、自托管端点替换与端到端验证。
概述:Fluentd 输出插件与 OneUptime HTTP Source
OneUptime 是一个完整的开源监控与可观测性平台,其遥测体系统一接收 Logs(日志)、Metrics(指标)与 Traces(链路追踪)三类数据。Fluentd 侧不需要安装任何 OneUptime 专用插件——官方推荐的方式是使用 Fluentd 内置的 http 输出插件(out_http),将采集到的日志记录以 JSON 形式 POST 到 OneUptime 的 HTTP Source,实现零额外依赖的接入。
整个数据流可以概括为:
任意数据源(Docker/Syslog/Nginx/MySQL/...)
│ Fluentd 采集
▼
Fluentd <match **> → @type http
│ JSON 批量 POST
▼
OneUptime HTTP Source(/fluentd/...)
│ 鉴权 + 规范化
▼
队列 → ClickHouse 持久化 → OneUptime 仪表盘查询
Fluentd 本身支持数百种数据源插件,官方文档列出的常见来源包括 Docker、Syslog、Apache、Nginx、MySQL、PostgreSQL、MongoDB,以及 NodeJS、Ruby、Python、Java、PHP、Go、Rust 等语言生态,通过 in_tail、in_forward、in_syslog 等输入插件即可接入。所有这些来源采集到的记录,都可以用同一套 http 输出配置汇入 OneUptime。
摄取端链路:OneUptime 如何接收 Fluentd 数据
为了让配置有的放矢,先看 OneUptime 侧的真实实现。仓库中的 Fluentd 摄取路由定义在 App/FeatureSet/Telemetry/API/Fluent.ts,它注册了一个 POST 接口,并依次挂载了以下中间件:
router.post(
"/fluentd/v1/logs",
TelemetryIngestionDisabled.middleware,
setFluentProductType,
TelemetryIngest.forSurface(TelemetryIngestSurface.Fluent),
async (req, res, next) => FluentLogsIngestService.ingestFluentLogs(req, res, next),
);
setFluentProductType把请求标记为ProductType.Logs,用于计量与计费;TelemetryIngest.forSurface(...)完成 Token 鉴权(对应请求头x-oneuptime-token)与项目归属解析;- 真正的处理逻辑在 FluentLogsIngestService 中:先立即返回空成功响应,再把载荷交给队列(
FluentLogsQueueService)异步处理,避免大流量日志阻塞 HTTP 层。异步任务最终通过 fan-in 写入器批量落盘到 ClickHouse,并采用 ack-after-flush 语义保证可靠性——只有批次真正持久化后任务才视为成功,失败则由队列重试。
需要特别留意端点路径:官方文档示例使用 https://oneuptime.com/fluentd/logs,而当前仓库代码中注册的路由是 /fluentd/v1/logs;仓库自带的 Fluentd/fluent.conf 中也注释了本地开发端点 http://fluent-ingest:3401/fluent-ingest/fluentd/v1/logs。自托管 OneUptime 时请以你所部署版本的 API 路由为准,通常为 http(s)://YOUR_ONEUPTIME_HOST/fluentd/v1/logs,必要时可查看部署实例的 API 路由表确认。
准备工作:账户、项目与摄取 Token
配置 Fluentd 之前,需要完成四步准备:
- 安装 Fluentd:按 Fluentd 官方安装文档在目标机器上安装 Fluentd(或 td-agent);
- 注册 OneUptime 账户:注册免费账户。按官方文档说明,账户本身免费,但日志摄取属于付费功能,具体以 OneUptime 定价页为准;
- 创建 OneUptime 项目:登录后在 OneUptime 仪表盘中创建项目;
- 创建 Telemetry Ingestion Token:这是 Fluentd 向 OneUptime 发送数据时使用的鉴权凭证,用于采集应用产生的日志、指标与 traces。
创建 Token 的界面操作路径为:登录后点击导航栏中的「Products」→「项目设置」,进入 Telemetry Ingestion Key 页面,点击「创建摄取密钥」(Create Ingestion Key)生成 Token:
创建完成后,点击「查看」(View)即可看到完整的 Token 字符串,后面需要把它填进 Fluentd 配置:
该页面的前端实现在 App/FeatureSet/Dashboard/src/Pages/Settings/TelemetryIngestionKeys.tsx,它通过 ModelTable<TelemetryIngestionKey> 渲染密钥列表与创建向导。从源码可以看到创建时需填写:
- Name(必填,至少 2 个字符)与 Description(可选);
- Key Type:
Server或Browser二选一,创建后不可更改。Server 类型用于服务器、容器与 OpenTelemetry Collector,无来源限制;Browser 类型用于 Web 前端与 React Native 会话回放,需要额外配置 Allowed Origins(来源白名单)与可选的 Pinned Service Name(固定服务名),且创建后会被限流。
Fluentd 转发属于典型的服务端场景,选择 Server 类型即可。仓库的端到端测试 E2E/Tests/Dashboard/TelemetryIngestionKeys.spec.ts 完整覆盖了密钥创建向导的校验流程(必填校验、Browser 来源白名单 JSON 校验、摘要确认后才真正落库等),可作为理解该功能行为的参考。
配置 Fluentd:最小可运行的 HTTP 输出
将下述配置追加到 Fluentd 配置文件。配置文件通常位于 /etc/fluentd/fluent.conf 或 /etc/td-agent/td-agent.conf。
配置中需要替换两处占位符:
| 占位符 | 含义 | 说明 |
|---|---|---|
YOUR_SERVICE_TOKEN |
上一步创建的 Telemetry Ingestion Token | 由 x-oneuptime-token 请求头携带,用于鉴权 |
YOUR_SERVICE_NAME |
服务名称 | 由 x-oneuptime-service-name 请求头携带;可任意命名,若该服务在 OneUptime 中尚不存在,摄取端会自动创建 |
最小配置示例:
# 匹配所有 tag,将全部日志转发到 OneUptime
<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>
各参数说明:
@type http:使用 Fluentd 内置 HTTP 输出插件;endpoint:OneUptime HTTP Source 地址,云版本为https://oneuptime.com/fluentd/logs;open_timeout 2:建立 HTTP 连接的超时时间为 2 秒;headers:以 JSON 对象形式指定自定义请求头,其中x-oneuptime-token携带摄取 Token,x-oneuptime-service-name携带服务名;content_type application/json与json_array true:以 JSON 数组格式发送批量记录;<format>@type json:每条记录序列化为 JSON;<buffer>flush_interval 10s:每 10 秒批量 flush 一次缓冲区,兼顾吞吐与实时性。
完整配置示例:forward 输入 + OneUptime 输出
实际生产环境中通常需要先接入一个输入源。下面是官方文档给出的完整配置:内置 forward 输入插件监听 TCP 24224 端口(Fluentd 生态最常见的接入协议),匹配所有 tag 后统一转发到 OneUptime。
####
## 输入源定义
##
## 内置 TCP 输入(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>
<source> 中的 @type forward 表示接收来自其他 Fluentd 节点或 fluent-logger-* 客户端(NodeJS、Python、Ruby 等语言的官方 logger)通过 TCP 24224 端口推送的数据。你可以按需增加任意输入源——例如 in_tail 读取本地文件、in_syslog 接收系统日志、in_http 接收 HTTP POST——只要所有记录最终由 <match **> 匹配到同一套 HTTP 输出即可。
仓库自带的 Fluentd/fluent.conf 在此基础上还额外增加了一个 HTTP 输入源,方便直接用 curl 做本地联调:
<source>
@type http
port 8888
bind 0.0.0.0
body_size_limit 32m
keepalive_timeout 10s
</source>
自托管 OneUptime 的端点替换
如果你自托管 OneUptime,需要把 endpoint 替换为你的实例地址,格式为:
http(s)://YOUR_ONEUPTIME_HOST/fluentd/logs
例如仓库配置文件中即使用了开发环境的端点 https://oneuptimedev.genosyn.com/fluentd/logs。如前文所述,请同时结合所部署版本的 API 路由确认最终路径(仓库代码注册的是 /fluentd/v1/logs)。
字段映射:Fluentd 记录如何变成 OneUptime 日志
这是 Fluentd 接入链路中最容易被忽略、也最影响查询体验的部分。OneUptime 摄取端(FluentLogsIngestService)会对每条记录做字段规范化,理解这套映射规则能帮助你从一开始就产出可被检索、可被过滤的日志。
日志正文(body)提取优先级
摄取端按以下字段顺序提取日志正文,取到第一个非空字段即停止:
message → log → msg → body → text
若这些字段都不存在,则回退为对整个记录执行 JSON.stringify。也就是说,无论你的日志记录携带的是 message、log 还是 msg 字段,都能被正确识别为日志内容。
严重级别(severity)映射
OneUptime 把字符串形式的级别文本映射为 OpenTelemetry 标准的 severityNumber 与 severityText:
| Fluentd 记录中的字段值 | severityNumber | OneUptime severityText |
|---|---|---|
trace |
1 | Trace |
debug |
5 | Debug |
info / information / informational / notice |
9 | Information |
warn / warning |
13 | Warning |
error / err |
17 | Error |
critical |
21 | Fatal |
fatal / emergency / emerg |
23 | Fatal |
识别字段的优先级为 level → severity → loglevel → log_level → priority → severityText → severity_text。未匹配到任何已知级别时,标记为 Unspecified(number 0)。建议在应用日志中统一使用这些标准级别字段,以便在 OneUptime 仪表盘按严重级别过滤告警。
Trace / Span 关联与属性展平
若记录携带链路上下文,摄取端会提取以下字段用于日志与 traces 的关联:
- Trace ID:
trace_id/traceId/traceid; - Span ID:
span_id/spanId/spanid。
除上述专用字段与正文/级别字段外,记录中的其余字段会被转为日志属性(attributes),统一加上 fluentd. 前缀,例如记录中的 container_name 会变成属性 fluentd.container_name;嵌套对象会被递归展平为点分键。这一设计保证了 Fluentd 来源的字段与 OpenTelemetry OTLP 路径不会冲突,同时保留完整上下文供过滤与检索。
服务名默认值与自动建服务
请求头未携带 x-oneuptime-service-name 时,默认服务名为 Fluentd。一旦指定服务名,摄取端通过 telemetryServiceFromName 解析或自动创建对应服务实体,因此配置中填写的服务名在 OneUptime 中不存在时会被自动创建,无需预先在控制台登记。
端到端验证:用仓库自带的 Fluentd 容器测试
OneUptime 仓库在 Fluentd/ 目录下内置了一个完整的 Fluentd 测试环境,方便你在接入自己的基础设施前先验证链路是否打通:
- 编辑 Fluentd/fluent.conf,把
headers中的 token 与服务名替换为你自己的值; - 构建镜像:
npm run force-build fluentd; - 启动容器:
npm run dev fluentd(容器基于官方fluentd镜像,见 Fluentd/Dockerfile.tpl,暴露 24224 与 8888 端口); - 向 HTTP 输入源发送一条测试日志:
curl -X POST -d 'json={"action":"login","user":2}' http://localhost:8888/test.tag.here;
curl 的 json= 参数会被 Fluentd 解析为记录字段。发送成功后,刷新 OneUptime 仪表盘即可看到该日志(注意 flush_interval 10s 的缓冲延迟)。这条测试路径验证的是「Fluentd 采集 → HTTP 转发 → OneUptime 摄取 → 可查询」的完整闭环,之后你就可以放心地接入 Docker 容器日志、系统日志或应用日志了。
常见问题与排查建议
- 日志迟迟不出现:先检查
flush_interval缓冲延迟(默认 10 秒),再确认 Fluentd 服务已重启、配置文件无语法错误(可用fluentd --dry-run -c /etc/fluentd/fluent.conf预检); - 鉴权失败(401):确认
x-oneuptime-token与仪表盘中「查看」到的 Token 完全一致,且该密钥属于当前项目; - 服务名不生效:确认
headers中的 JSON 格式正确(键值均需双引号),且x-oneuptime-service-name拼写无误;未携带时默认值为Fluentd; - 自托管实例连不上:核对 endpoint 协议与路径,当前仓库代码注册的摄取路由为
POST /fluentd/v1/logs,请以所部署版本为准; - 字段查询不到:回忆本文的字段映射规则——正文提取自
message/log/msg/body/text,其余字段以fluentd.前缀作为属性保存,级别字段请使用标准取值。
完成上述配置与验证后,你的 Fluentd 采集链路即与 OneUptime 原生 OTLP 路径一样,会经历日志管线(Log Pipelines)、丢弃过滤器(Drop Filters)与敏感数据脱敏(Scrub Rules)等统一处理阶段,最终进入 ClickHouse 供仪表盘实时检索与分析。

