使用 Fluentd 将 Telemetry 日志接入 OneUptime:HTTP 输出插件配置与源码级原理解析
使用 Fluentd 将 Telemetry 日志接入 OneUptime:HTTP 输出插件配置与源码级原理解析
导读
本文基于 OneUptime 官方文档中 Fluentd 接入指南,完整讲解如何借助 Fluentd 的 HTTP 输出插件(out_http),把 Docker、Syslog、Nginx、各类应用日志等 Telemetry 数据统一汇聚到 OneUptime 的 HTTP 摄取端点 /fluentd/logs。读完本文,你将掌握完整的 fluent.conf 配置写法、x-oneuptime-token 与 x-oneuptime-service-name 两个请求头的正确用法、自托管场景下的端点改写规则,并能从 OneUptime 仓库源码层面理解日志字段映射、严重级别换算与异步落库的实现细节。
概述:Fluentd 作为 OneUptime 的日志接入通道
OneUptime 是一款开源的可观测性平台,其 Telemetry 功能支持通过多种协议与工具摄入日志、指标和 Trace。Fluentd 是其中最灵活的日志采集器之一:你可以在任意主机、容器或 Kubernetes 节点上运行 Fluentd,将来自数百种数据源的日志统一格式化为 JSON,然后通过 HTTP 输出插件发送到 OneUptime 的 HTTP Source。
Fluentd 端的接入链路非常简单——不需要安装任何 OneUptime 专用插件,只需使用 Fluentd 内置的 http 输出插件(官方文档中位于 docs.fluentd.org/output/http)。OneUptime 在服务端提供对应的 HTTP 摄取端点,接收 Fluentd 以 json_array 形式批量 POST 的日志条目。
在 OneUptime 仓库中,这条链路对应的实现位于 App/FeatureSet/Telemetry/API/Fluent.ts,服务端实际注册的端点为 POST /fluentd/v1/logs;为了兼容文档中的老路径,Nginx 层会执行 /fluentd/logs → /fluentd/v1/logs 的重写(见下文「端点与自托管」小节)。
支持的输入源:hundreds of data sources
Fluentd 生态支持数百种数据源,你可以把其中任意一种产生的日志通过 Fluentd 转发进 OneUptime。官方文档列出的常见来源包括:
- 容器与系统:Docker、Syslog
- Web 服务器:Apache、Nginx
- 数据库:MySQL、PostgreSQL、MongoDB
- 应用语言:NodeJS、Ruby、Python、Java、PHP、Go、Rust
以及其他更多来源(Fluentd 官方数据源清单见 fluentd.org/datasources)。
仓库中的 Examples/fluentd/index.js 给出了一个 Node.js 侧的参考示例:应用通过 @fluent-org/logger 的 FluentClient 向本地 Fluentd 的 forward 输入(localhost:24224)发送日志事件,随后由 Fluentd 统一转发到 OneUptime:
const FluentClient = require("@fluent-org/logger").FluentClient;
const logger = new FluentClient("fluentd.test", {
socket: {
host: "localhost",
port: 24224,
timeout: 3000, // 3 seconds
},
});
app.get("/", (request, response) => {
logger.emit("follow", { from: "userA", to: "userB" });
response.send("Hello World!");
});
这种「应用 → Fluentd 本地端口 → OneUptime HTTP 端点」的架构,让你无需在每个应用里嵌入 SDK,即可集中管理日志出口。
前提条件
在开始配置之前,需要依次完成以下四个步骤:
- 步骤 1:安装 Fluentd —— 按 Fluentd 官方安装指引在你的系统上安装 Fluentd(安装完成后配置文件通常位于
/etc/fluentd/fluent.conf,使用 td-agent 发行版时则为/etc/td-agent/td-agent.conf)。 - 步骤 2:注册 OneUptime 账号 —— 在 oneuptime.com 注册免费账号。注意:账号免费,但日志摄取属于付费功能,具体以官方定价页面为准。
- 步骤 3:创建 OneUptime 项目 —— 登录后在 Dashboard 中创建一个项目;若需要帮助可联系 support@oneuptime.com。
- 步骤 4:创建 Telemetry 摄取 Token(Telemetry Ingestion Key) —— 进入项目后,点击导航栏中的 Products → Project Settings,在 Telemetry Ingestion Key 页面点击 Create Ingestion Key 创建令牌,创建后点击 View 查看令牌值。
仓库 Fluentd/README.md 对步骤 4 给出了同样的指引:创建入口为 Dashboard 中 More → Project Settings → Telemetry Ingestion Key。该令牌在后端对应一张 TelemetryIngestionKey 数据表,从 Postgres 迁移脚本 可见其核心字段包括 secretKey(UUID)、projectId、name、keyType 等——你创建出的令牌值即 secretKey,Fluentd 配置中的 YOUR_SERVICE_TOKEN 就填这个值。
配置:将 Telemetry 数据发送到 OneUptime HTTP Source
将以下配置追加到 Fluentd 配置文件中(通常为 /etc/fluentd/fluent.conf 或 /etc/td-agent/td-agent.conf):
# 匹配所有模式
<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>
使用前必须替换两处占位符:
YOUR_SERVICE_TOKEN:替换为上一节「步骤 4」创建的 Telemetry Ingestion Key。这是 OneUptime 识别项目归属的凭据,务必保密。YOUR_SERVICE_NAME:替换为你的服务名。服务名可以任意命名;如果该服务在 OneUptime 中尚不存在,服务端会自动创建(见下文「服务名解析」)。
各配置项详解
| 配置项 | 作用 | 建议/取值 |
|---|---|---|
<match **> |
匹配所有 tag 的日志记录,是 Fluentd 路由的核心 | 若只想转发特定来源,可将 ** 替换为具体 tag,如 docker.** |
@type http |
使用 Fluentd 内置 HTTP 输出插件 | 无需安装额外插件 |
endpoint |
OneUptime HTTP 摄取端点 | 云服务为 https://oneuptime.com/fluentd/logs;自托管见下文 |
open_timeout |
HTTP 连接建立的超时时间(秒) | 示例为 2 秒;网络不稳时可适当调大 |
headers |
自定义请求头,用于身份认证与服务归属 | 必须携带 x-oneuptime-token 与 x-oneuptime-service-name |
content_type |
请求体 Content-Type | 必须为 application/json |
json_array |
是否将多条记录以 JSON 数组形式批量发送 | 必须为 true,对应 OneUptime 服务端的批量解析 |
<format> @type json |
记录序列化格式 | 固定为 JSON |
<buffer> flush_interval 10s |
缓冲刷新间隔 | 示例为 10 秒,可按吞吐量调整 |
为什么必须设置 json_array true 与 content_type application/json
OneUptime 服务端的摄取实现会按「JSON 数组批量」的形态解析请求体。在 FluentLogsIngestService.normalizeLogEntries 中可以看到,服务端对请求体做了多层归一化:当 payload 是字符串时按单条 message 处理,多行字符串按行拆分;当 payload 是数组时逐项递归归一化;当 payload 是对象时优先解包 json 与 entries 字段。因此 Fluentd 以 json_array true 发送的 [{...},{...}] 数组会被完整保留为多条日志条目——这正是该配置项必须开启的原因。
自托管 OneUptime:替换端点地址
如果你自行托管 OneUptime,只需将 endpoint 替换为你实例的地址:
http(s)://YOUR_ONEUPTIME_HOST/fluentd/logs
例如仓库 Fluentd/fluent.conf 中使用的开发/生产示例端点 https://oneuptimedev.genosyn.com/fluentd/logs。
端点与路径重写:/fluentd/logs 背后的真实路由
值得说明的是:文档对外暴露的端点是 /fluentd/logs,而 OneUptime 应用服务实际注册的路由是 /fluentd/v1/logs(见 App/FeatureSet/Telemetry/API/Fluent.ts 中 router.post("/fluentd/v1/logs", ...))。两者通过 Nginx 层衔接:
location /fluentd/logs {
...
rewrite ^/fluentd/logs(.*)$ /fluentd/v1/logs$1 break;
proxy_pass ${BACKEND_APP_TARGET};
}
见 Nginx/default.conf.template。所以无论你是直连应用端口还是经由 Nginx 网关,只要按文档把 endpoint 指向 /fluentd/logs 即可,网关会自动改写请求。若你的部署不经过该 Nginx 模板(例如自定义反向代理),则需自行保证对 /fluentd/v1/logs 的转发。
完整配置示例:一个可运行的 fluent.conf
仓库 Fluentd/fluent.conf 给出了一个带输入源(<source>)的完整可运行配置,可作为自建 Fluentd 容器的起点:
####
## Source descriptions:
##
## built-in TCP input
## @see https://docs.fluentd.org/input/forward
<source>
@type forward
port 24224
bind 0.0.0.0
</source>
<source>
@type http
port 8888
bind 0.0.0.0
body_size_limit 32m
keepalive_timeout 10s
</source>
# 匹配所有模式
<match **>
@type http
endpoint https://oneuptimedev.genosyn.com/fluentd/logs # 生产环境示例端点
open_timeout 2
# 请务必将 token 与 service name 替换为你自己的值
headers {"x-oneuptime-token":"YOUR_SERVICE_TOKEN", "x-oneuptime-service-name": "fluentd-logs"}
content_type application/json
json_array true
<format>
@type json
</format>
<buffer>
flush_interval 10s
</buffer>
</match>
这段配置同时开启两种输入:
forward输入(TCP 24224):接收来自本机/局域网应用(如 Examples/fluentd/index.js 中FluentClient)的日志;http输入(HTTP 8888):接收 curl 等工具直接 POST 的日志(body_size_limit 32m限制单请求体积,keepalive_timeout 10s允许长连接复用)。
Fluentd 的 Docker 化部署在仓库中有完整配套:镜像定义见 Fluentd/Dockerfile.tpl(基于官方 fluentd 镜像,暴露 24224 与 8888 端口),开发环境通过 docker-compose.dev.yml 以 ./Fluentd/fluent.conf:/fluentd/etc/fluent.conf 挂载配置。注意该容器定位为开发验证用途;生产环境中按 docker-compose.dev.yml 中的注释说明,应由客户在自己的环境中运行 Fluentd 并向 OneUptime 转发日志。
使用:重启服务并在 Dashboard 查看日志
完成配置后,重启 Fluentd 服务使配置生效:
# 使用 systemd 管理时
systemctl restart fluentd
# 或使用 td-agent 发行版
systemctl restart td-agent
服务重启后,Fluentd 会按照 flush_interval 10s 的节奏把缓冲的日志批量 POST 到 OneUptime HTTP Source,你即可在 OneUptime Dashboard 的日志视图中看到这些数据。
本地快速验证
如果使用仓库中的 Fluentd 容器进行开发验证,按 Fluentd/README.md 的步骤操作:
# 1. 确保 Fluentd/fluent.conf 中 token 与 endpoint 正确
# 2. 构建并启动 Fluentd 容器
npm run force-build fluentd
npm run dev fluentd
# 3. 通过容器的 HTTP 输入(8888 端口)发送一条测试日志
curl -X POST -d 'json={"action":"login","user":2}' http://localhost:8888/test.tag.here
发送成功后即可在 OneUptime Dashboard 中看到这条 {"action":"login","user":2} 日志。
源码级原理:Fluentd 日志在 OneUptime 服务端的处理链路
理解服务端如何处理 Fluentd 推送的数据,有助于你调整字段命名、排查日志丢失问题。整条链路共四层:
1. 路由与认证(中间件层)
Fluent.ts 中注册的 POST /fluentd/v1/logs 依次经过:
TelemetryIngestionDisabled.middleware:全局摄取开关,若设置了DISABLE_TELEMETRY_INGESTION=true,端点会接收请求但丢弃数据;setFluentProductType:把请求标记为ProductType.Logs(按日志产品计费);TelemetryIngest.forSurface(TelemetryIngestSurface.Fluent):密钥认证与摄取面校验。
认证逻辑位于 Common/Server/Middleware/TelemetryIngest.ts:优先读取 x-oneuptime-token 请求头,若缺失则依次回退到 x-oneuptime-service-token 与 x-oneuptime-ingestion-key,然后用该值查询 TelemetryIngestionKeyService 的密钥策略。Token 缺失或无效时返回 401(NotAuthenticatedException);密钥被禁用时返回 403(NotAuthorizedException)。值得注意的是,错误信息不会回显 token 本身,避免密钥泄漏到日志中。
从 Common/Types/Telemetry/TelemetryIngestSurface.ts 可以看到,Fluentd 摄取被归类为 TelemetryIngestSurface.Fluent = "fluent",且不在浏览器密钥(Browser key)允许清单 BROWSER_ALLOWED_INGEST_SURFACES 中——即 Fluentd 端点只能使用服务端密钥(Server key)访问,防止从公开页面窃取的浏览器密钥被重放到该端点。这一约束由测试 App/Tests/Telemetry/TelemetryIngestSurfaceWiring.test.ts 钉死,该测试将 Fluent.ts 与路由 /fluentd/v1/logs、surface Fluent 的绑定关系作为安全基线断言。
2. 异步队列(响应先行,落库后置)
主服务在 FluentLogsIngestService.ingestFluentLogs 中先对请求体做 normalizeLogEntries 归一化,若解析出的日志条目为空则抛 BadRequestException;否则先向客户端返回 200 空响应,再把请求通过 FluentLogsQueueService 提交到 BullMQ 队列(TelemetryType.FluentLogs,见 TelemetryQueueService.ts)。实际的数据加工与写入在队列 Worker 的 processFluentLogsFromQueue → processFluentLogsAsync 中异步完成,因此单次 HTTP 请求不会阻塞在写库上。
3. 字段解析与映射(日志加工)
队列 Worker 对每条日志条目执行以下解析(见 FluentLogsIngestService.ts):
- 日志正文:按优先级依次检查
message、log、msg、body、text字段(BODY_FIELDS),取到第一个非空值;若全部缺失,则把整个条目JSON.stringify作为正文; - 严重级别:从
level、severity、loglevel、log_level、priority、severityText、severity_text中取值,并通过SEVERITY_TEXT_MAP映射为 OTel 语义的严重级别数字与文本。例如trace→1、debug→5、info/notice→9、warn→13、error/err→17、critical→21、fatal/emergency→23;未知值归为Unspecified(0); - Trace/Span 关联:
trace_id/traceId/traceid与span_id/spanId/spanid会被提取为独立的 traceId、spanId 字段,便于把日志关联到链路追踪; - 自定义属性:除上述被排除的字段外,条目中的其他键会以
fluentd.<key>前缀(如fluentd.action、fluentd.user)作为日志属性写入;嵌套对象会被展平为点分属性,数组则以 JSON 字符串保存。这解释了为什么你在 Dashboard 中看到的属性名会带fluentd.前缀——这是服务端刻意区隔来源的命名约定。
4. 加工管线与持久化(与 OTLP 路径对齐)
为保证 Fluentd 日志与 OTLP 日志路径享受同等的处理策略,Worker 会在每批日志上按固定顺序执行(FluentLogsIngestService.ts):
- Log Drop Filter:命中丢弃规则的日志直接跳过,不写入存储;
- Sensitive Data Scrub:对日志进行敏感信息清洗;
- Log Pipeline:应用用户配置的日志处理管线。
随后日志按「每批 TELEMETRY_LOG_FLUSH_BATCH_SIZE 条」提交给共享的扇入写入器(TelemetryFanInWriter),最终落库到 ClickHouse。这里还有一个重要的可靠性细节:队列任务采用 ack-after-flush 语义——Worker 必须等待所有包含本次数据的批次在 ClickHouse 中持久化成功后才标记任务完成;若写库失败,任务会被 BullMQ 重试,从而避免「客户端收到 200 但数据丢失」的情况。
5. 服务名解析与保留期
服务端通过请求头中的 x-oneuptime-service-name 调用 OTelIngestService.telemetryServiceFromName({ serviceName, projectId }) 解析服务元数据:若该服务不存在则自动创建(这也验证了文档中「服务不存在会自动创建」的说明);同时根据服务/项目的保留期配置与日志严重级别,计算该条日志的 retentionDate(见 FluentLogsIngestService.ts)。若请求头缺失服务名,服务端会回退到默认服务名 Fluentd(DEFAULT_SERVICE_NAME)。
常见问题排查
- 请求返回 401:
x-oneuptime-token缺失或令牌无效。请核对 Dashboard 中 Telemetry Ingestion Key 的值,并确认没有把密钥粘贴到日志输出中。 - 请求返回 403:令牌被禁用(
isEnabled为 false),请到 Project Settings 重新启用或重建密钥。 - Dashboard 看不到日志:先确认
content_type application/json与json_array true均已设置;再确认endpoint在你的网络环境中可访问(自托管时网关需正确转发/fluentd/v1/logs);最后检查日志条目的正文字段是否为message/log/msg/body/text之一,否则正文会退化为整个 JSON 的字符串化结果。 - 属性名带
fluentd.前缀:这是服务端对 Fluentd 来源的标准化命名,属正常行为,可在 Dashboard 中按该前缀检索与过滤。
总结
通过 Fluentd 接入 OneUptime 无需安装任何专用插件:一段 <match> 配置加上 HTTP 输出插件即可完成对接。配置要点可概括为:正确的 endpoint、携带 x-oneuptime-token 与 x-oneuptime-service-name 的请求头、application/json 内容类型与 json_array true 批量模式。而深入 OneUptime 仓库源码可以看到,端点背后有完整的认证中间件、BullMQ 异步队列、OTel 语义字段映射、日志加工管线与 ClickHouse 持久化保障,确保从 Fluentd 推送的每条日志都能可靠地出现在你的可观测性仪表盘中。