使用 Fluentd 将 Telemetry 日志接入 OneUptimeHTTP 输出插件配置与源码级原理解析【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本文基于 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 sourcesFluentd 生态支持数百种数据源你可以把其中任意一种产生的日志通过 Fluentd 转发进 OneUptime。官方文档列出的常见来源包括容器与系统Docker、SyslogWeb 服务器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 统一转发到 OneUptimeconst 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 中创建一个项目若需要帮助可联系 supportoneuptime.com。步骤 4创建 Telemetry 摄取 TokenTelemetry 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 迁移脚本 可见其核心字段包括secretKeyUUID、projectId、name、keyType等——你创建出的令牌值即secretKeyFluentd 配置中的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 输出插件无需安装额外插件endpointOneUptime HTTP 摄取端点云服务为https://oneuptime.com/fluentd/logs自托管见下文open_timeoutHTTP 连接建立的超时时间秒示例为 2 秒网络不稳时可适当调大headers自定义请求头用于身份认证与服务归属必须携带x-oneuptime-token与x-oneuptime-service-namecontent_type请求体 Content-Type必须为application/jsonjson_array是否将多条记录以 JSON 数组形式批量发送必须为true对应 OneUptime 服务端的批量解析format type json记录序列化格式固定为 JSONbuffer flush_interval 10s缓冲刷新间隔示例为 10 秒可按吞吐量调整为什么必须设置json_array true与content_type application/jsonOneUptime 服务端的摄取实现会按「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_INGESTIONtrue端点会接收请求但丢弃数据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 缺失或无效时返回401NotAuthenticatedException密钥被禁用时返回403NotAuthorizedException。值得注意的是错误信息不会回显 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、surfaceFluent的绑定关系作为安全基线断言。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未知值归为Unspecified0Trace/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.tsLog 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。若请求头缺失服务名服务端会回退到默认服务名FluentdDEFAULT_SERVICE_NAME。常见问题排查请求返回 401x-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 推送的每条日志都能可靠地出现在你的可观测性仪表盘中。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考