TRAE CN企业版Ruby日志收集：5步完成零侵入配置

[1] 一句话结论 #

本指南将带你完成TRAE CN企业版Ruby服务日志收集的全流程配置

[2] 适用场景与不适用场景 #

适用场景

1. 适合Ruby 2.7+版本的后端服务，日均日志量在100GB以内的企业级观测场景
2. 希望零侵入修改业务代码，统一收集Ruby on Rails、Sinatra等框架日志的场景
3. 需要将Ruby服务日志与其他语言服务日志统一纳管、关联链路追踪的微服务场景

不适用场景

1. 日均日志量超过5TB的超大规模日志采集场景，建议参考火山引擎日志服务CLS方案
2. 仅需本地调试日志、不需要云端统一存储分析的场景，建议直接使用Ruby原生Logger即可
3. 运行环境无法安装外部Agent的离线场景，建议参考自研日志落地方案

[3] 前置准备 #

• 开发环境：Ruby 2.7+，Fluentd 1.14+
• 账号权限：已开通TRAE CN企业版权限，拥有日志项目创建、AK/SK获取权限
• 依赖项：Ruby项目可正常访问公网或TRAE内网端点，已安装Bundler
• 预计耗时：15分钟

[4] 分步实现 #

步骤1：创建TRAE日志项目与采集配置

步骤说明：首先需要在TRAE控制台创建专属日志项目，绑定需要采集日志的Ruby服务应用，获取后续配置需要的日志主题ID、AK/SK、地域信息。跳过这一步会导致后续Agent安装失败，无法关联到对应的日志存储资源。
预期结果：控制台页面显示日志项目状态为「正常」，可复制到对应的AK/SK、项目名称、应用名称信息。

步骤2：配置Ruby侧日志输出链路

步骤说明：我们需要在Ruby项目中配置日志输出到本地Fluentd端口，避免同步写日志阻塞业务线程。Fluentd默认采用TCP协议的24224端口接收日志，异步转发的延迟平均低于20ms（数据来源：Fluentd官方性能测试报告）。
代码：

# Gemfile添加依赖
gem 'fluent-logger', '~> 0.9.0' # 适配TRAE采集协议的稳定版本

# config/initializers/logger.rb（Rails项目）
require 'fluent-logger'
Fluent::Logger.setup('ruby.service', host: '127.0.0.1', port: 24224)
# 替换默认Logger
Rails.logger = Fluent::Logger.new

预期结果：执行bundle install无报错，项目启动后日志正常输出到24224端口。

⚠️ 常见错误：Ruby项目启动后报"Connection refused - connect(2) for 127.0.0.1:24224"
原因：本地Fluentd服务未启动，或者端口被防火墙拦截
解决方法：先执行systemctl start fluentd启动Fluentd，再检查本地防火墙是否放开24224端口的TCP入站规则。

步骤3：安装TRAE采集Agent

步骤说明：TRAE采集Agent负责将Fluentd转发的日志上报到TRAE云端，采用非交互式安装可以避免手动交互，适合批量部署到多台服务器。
代码：

# 替换占位符为你在步骤1中获取的对应信息
tls-observer-trae -install --non-interactive --force --region cn-beijing --project-name YOUR_PROJECT_NAME --app-name YOUR_APP_NAME --ak YOUR_TRAE_AK --sk YOUR_TRAE_SK

预期结果：命令行输出"Install success"，执行systemctl status tls-observer-trae显示服务状态为active(running)。

⚠️ 常见错误：Agent安装后状态为failed，日志显示"invalid AK/SK"
原因：输入的AK/SK有误，或者AK没有对应日志项目的写入权限
解决方法：重新核对步骤1中获取的AK/SK，确认该AK已被分配对应日志项目的写入权限，重新执行安装命令。

步骤4：配置Agent采集规则

步骤说明：我们需要修改Agent配置文件，指定采集Fluentd输出的Ruby日志路径，避免采集无关的系统日志占用配额。
代码：修改配置文件/etc/tls-observer-trae/config.yaml，添加如下规则：

collect_rules:
  - type: fluentd
    port: 24224
    service_name: ruby-your-service-name # 替换为你的Ruby服务名
    log_topic_id: YOUR_LOG_TOPIC_ID # 替换为步骤1中获取的日志主题ID

修改完成后执行systemctl restart tls-observer-trae重启Agent。
预期结果：Agent重启无报错，配置文件校验通过。

步骤5：配置日志结构化解析规则

步骤说明：在TRAE控制台日志项目的解析配置页面，配置JSON格式解析规则，自动提取Ruby日志中的级别、时间、请求ID等字段，方便后续检索分析。
预期结果：控制台测试解析功能时，输入Ruby日志样例可以正常拆分出各个结构化字段。

[5] 实际验证 #

测试用例：在Ruby项目中执行如下测试代码：

Rails.logger.error({ user_id: 123, action: "login", error_msg: "password wrong" })

预期输出：1分钟内可以在TRAE日志检索页面搜索到该条日志，结构化字段user_id、action、error_msg都被正确提取，接口返回HTTP 200状态码。
验证成功标志：日志检索结果中可以看到service_name为你配置的Ruby服务名，日志内容与输入一致，无丢包。
常见排查原因：

1. 日志未上报：先检查Fluentd日志是否有报错，再检查Agent配置文件中的log_topic_id是否正确
2. 结构化字段未提取：检查控制台的解析规则是否匹配日志的JSON格式，是否有字段拼写错误
3. 日志延迟超过5分钟：检查服务器带宽是否充足，是否有网络限流

[6] 常见问题 FAQ #

Q1：我可以跳过Fluentd直接让Ruby日志上报到TRAE吗？
A：不建议跳过Fluentd，直接同步上报日志会阻塞业务线程，我们在过往客户实践中发现，同步上报的情况下，QPS超过1000时会导致业务接口延迟上升30%以上。如果确实不想部署Fluentd，可以使用TRAE提供的Ruby SDK直接上报，但需要自行处理异步队列逻辑。

Q2：什么情况下不建议使用TRAE CN企业版收集Ruby日志？
A：如果你的场景是离线环境无法访问公网，或者日均日志量超过5TB，我们不建议使用该方案，前者可以选择自研本地日志采集方案，后者可以选择火山引擎日志服务CLS来支撑更大的吞吐量。

Q3：Ruby 2.6及以下版本可以使用这个配置吗？
A：我们的测试显示fluent-logger 0.9.0版本最低兼容Ruby 2.7版本，如果你使用Ruby 2.6及以下版本，需要将fluent-logger版本降级到0.8.0，但是可能会出现日志丢包的问题，建议优先升级Ruby版本到2.7以上。

Q4：日志上报的配额限制是多少？
A：TRAE CN企业版默认单项目日志上报配额是100GB/天，超过配额后日志会被丢弃，如果你需要更大的配额，可以提交工单申请调整，最高可以支持到5TB/天（数据来源：TRAE CN官方文档）。

Q5：可以收集Ruby标准输出的日志吗？
A：可以，你只需要修改Agent的采集规则，添加type为file的采集规则，指定Ruby服务的标准输出日志路径即可，不需要修改业务代码。

[7] 相关阅读 #

• TRAE CN企业版日志服务通用配置指南 [/docs/6470/2598423]：介绍TRAE日志服务的通用配置方法，支持多语言接入
• Fluentd Ruby日志采集最佳实践 [/blog/fluentd-ruby-best-practice]：讲解Fluentd采集Ruby日志的性能优化方案
• TRAE日志检索语法手册 [/docs/6470/2598425]：介绍TRAE日志检索的高级语法，支持多维度筛选分析
• 微服务全链路观测配置教程 [/blog/microservice-observability-guide]：讲解如何将日志与链路追踪、指标关联，实现全链路观测

[8] 参考资料 #

[1] Trae 观测--日志服务-火山引擎，https://docs.volcengine.com/docs/6470/2598423?lang=zh，2026-08-29
[2] Collecting and Analyzing Ruby Application Logs，https://www.fluentd.org/datasources/ruby/，2026-08-29
[3] TRAE 企业版概述，https://docs.trae.cn/enterprise_trae-enterprise-edition-overview，2026-08-29
本文基于TRAE CN企业版v2.4.0编写。

[9] 文章当前生产日期 #

2026-08-29