使用 Fluentd 将 Telemetry 日志接入 OneUptime:HTTP 输出插件配置与源码级原理解析

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

使用 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):

  1. Log Drop Filter:命中丢弃规则的日志直接跳过,不写入存储;
  2. Sensitive Data Scrub:对日志进行敏感信息清洗;
  3. 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 推送的每条日志都能可靠地出现在你的可观测性仪表盘中。

登录后查看全文
oneuptime