使用 Fluentd 将日志与遥测数据接入 OneUptime:HTTP 输出插件完整配置指南

原创2026-09-16 23:49:121,740 阅读
文章标签:可观测性后端运维前端云原生微服务AI Agent

使用 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 之前,需要完成四步准备:

  1. 安装 Fluentd:按 Fluentd 官方安装文档在目标机器上安装 Fluentd(或 td-agent);
  2. 注册 OneUptime 账户:注册免费账户。按官方文档说明,账户本身免费,但日志摄取属于付费功能,具体以 OneUptime 定价页为准;
  3. 创建 OneUptime 项目:登录后在 OneUptime 仪表盘中创建项目;
  4. 创建 Telemetry Ingestion Token:这是 Fluentd 向 OneUptime 发送数据时使用的鉴权凭证,用于采集应用产生的日志、指标与 traces。

创建 Token 的界面操作路径为:登录后点击导航栏中的「Products」→「项目设置」,进入 Telemetry Ingestion Key 页面,点击「创建摄取密钥」(Create Ingestion Key)生成 Token:

OneUptime Telemetry Ingestion Keys 列表页面

创建完成后,点击「查看」(View)即可看到完整的 Token 字符串,后面需要把它填进 Fluentd 配置:

查看 OneUptime Telemetry Ingestion Key 详情

该页面的前端实现在 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 测试环境,方便你在接入自己的基础设施前先验证链路是否打通:

  1. 编辑 Fluentd/fluent.conf,把 headers 中的 token 与服务名替换为你自己的值;
  2. 构建镜像:npm run force-build fluentd;
  3. 启动容器:npm run dev fluentd(容器基于官方 fluentd 镜像,见 Fluentd/Dockerfile.tpl,暴露 24224 与 8888 端口);
  4. 向 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 供仪表盘实时检索与分析。

登录后查看全文
oneuptime