error-tracking-ruby-on-rails

Ruby on Rails 的 PostHog 错误跟踪

此技能可帮助你在 Ruby on Rails 应用中添加 PostHog 错误跟踪。

参考文件

• references/ruby-on-rails.md - Ruby on rails 错误跟踪安装 - 文档
• references/fingerprints.md - 指纹 - 文档
• references/alerts.md - 发送错误跟踪警报 - 文档
• references/monitoring.md - 监控和搜索问题 - 文档
• references/assigning-issues.md - 将问题分配给队友 - 文档
• references/upload-source-maps.md - 上传源映射 - 文档

请查阅文档，了解 API 详情和框架特定模式。

核心原则

• 环境变量：始终使用环境变量存储 PostHog 密钥和主机 URL。切勿将它们硬编码。
• 尽量减少改动：在现有错误处理中添加错误跟踪。不要替换或重构现有错误处理代码。
• 优先启用自动捕获：添加手动捕获之前，先在 SDK 初始化时启用异常自动捕获。
• 源映射：上传源映射，以便堆栈跟踪能够解析到原始源代码，而不是压缩后的代码包。
• 在边界处手动捕获：对于不会传播到全局处理程序的错误，在错误边界和 catch 块中使用 captureException()。

框架指南

• 将 posthog-rails gem 与 posthog-ruby 一起使用，以自动捕获异常并检测 ActiveJob
• 运行 rails generate posthog:install 以创建初始化文件，或手动创建 config/initializers/posthog.rb
• 配置 auto_capture_exceptions: true，以自动跟踪控制器中未处理的异常
• 配置 report_rescued_exceptions: true，以捕获 Rails 处理掉的异常（例如通过 rescue_from 处理的异常）
• 配置 auto_instrument_active_job: true，以跟踪后台作业失败，并记录作业类、队列和参数
• 使用 PostHog.capture() 和 PostHog.identify() 类级方法（而非实例方法）——posthog-rails gem 通过 PostHog.init 管理客户端生命周期
• 在 Rails 中不要手动创建 PostHog::Client 实例——在初始化文件中使用 PostHog.init，其他位置则使用 PostHog.capture/identify
• capture_exception 使用位置参数：PostHog.capture_exception(exception, distinct_id, additional_properties)——不要使用关键字参数
• 在 User 模型中定义 posthog_distinct_id，以便在错误报告中自动关联用户——posthog-rails 会依次尝试 posthog_distinct_id、distinct_id、id、pk、uuid 来自动检测
• 若要在 ActiveJob 中关联用户，请使用类级 DSL posthog_distinct_id ->(user) { user.email }，或在哈希参数中传递 user_id:
• 将 API 密钥存储在 Rails 凭据或环境变量中，切勿硬编码
• 若要在使用 posthog-rails 的同时跟踪前端事件，请将 posthog-js 代码片段添加到布局模板中——posthog-js 负责处理页面浏览、会话回放和客户端错误，而 posthog-ruby 负责处理后端事件、服务端错误、功能标志和后台作业
• posthog-ruby 是 Ruby SDK 的 gem 名称（将 gem 'posthog-ruby' 添加到 Gemfile），但引入时应使用 require 'posthog'（而非 require 'posthog-ruby'）
• 在脚本和 CLI 中使用 PostHog::Client.new(api_key: key, host: host) 进行基于实例的初始化
• 在 CLI 和脚本中：退出前必须调用 client.shutdown，否则所有事件都会丢失
• 使用 begin/rescue/ensure，并在 ensure 块中调用 shutdown，以便正确清理
• capture 和 identify 接受单个哈希参数：client.capture(distinct_id: 'user_123', event: 'my_event', properties: { key: 'value' })
• capture_exception 使用位置参数（不是关键字参数）：client.capture_exception(exception, distinct_id, additional_properties)——不要使用 distinct_id: 关键字语法