error-tracking-ruby-on-rails

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog error tracking for Ruby on Rails

适用于Ruby on Rails的PostHog错误追踪

This skill helps you add PostHog error tracking to Ruby on Rails applications.

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

Reference files

参考文件

```
references/ruby-on-rails.md
```
- Ruby on rails error tracking installation - docs
```
references/fingerprints.md
```
- Fingerprints - docs
```
references/alerts.md
```
- Send error tracking alerts - docs
```
references/monitoring.md
```
- Monitor and search issues - docs
```
references/assigning-issues.md
```
- Assign issues to teammates - docs
```
references/upload-source-maps.md
```
- Upload source maps - docs

Consult the documentation for API details and framework-specific patterns.

```
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详情和框架特定模式，请查阅相关文档。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys and host URLs. Never hardcode them.
Minimal changes: Add error tracking alongside existing error handling. Don't replace or restructure existing error handling code.
Autocapture first: Enable exception autocapture in the SDK initialization before adding manual captures.
Source maps: Upload source maps so stack traces resolve to original source code, not minified bundles.
Manual capture for boundaries: Use
```
captureException()
```
at error boundaries and catch blocks for errors that don't propagate to the global handler.

环境变量：始终使用环境变量存储PostHog密钥和主机URL，切勿硬编码。
最小改动：在现有错误处理基础上添加错误追踪，不要替换或重构现有错误处理代码。
自动捕获优先：在SDK初始化时启用异常自动捕获，再添加手动捕获。
源映射：上传源映射，以便堆栈跟踪解析为原始源代码而非压缩后的包。
边界处手动捕获：在错误边界和catch块中使用
```
captureException()
```
捕获未传播到全局处理器的错误。

Framework guidelines

框架指南

Use posthog-rails gem alongside posthog-ruby for automatic exception capture and ActiveJob instrumentation
Run
```
rails generate posthog:install
```
to create the initializer, or manually create config/initializers/posthog.rb
Configure auto_capture_exceptions: true to automatically track unhandled exceptions in controllers
Configure report_rescued_exceptions: true to also capture exceptions that Rails rescues (e.g. with rescue_from)
Configure auto_instrument_active_job: true to track background job failures with job class, queue, and arguments
Use PostHog.capture() and PostHog.identify() class-level methods (NOT instance methods) — the posthog-rails gem manages the client lifecycle via PostHog.init
Do NOT manually create PostHog::Client instances in Rails — use PostHog.init in the initializer and PostHog.capture/identify everywhere else
capture_exception takes POSITIONAL args: PostHog.capture_exception(exception, distinct_id, additional_properties) — do NOT use keyword args
Define posthog_distinct_id on the User model for automatic user association in error reports — posthog-rails auto-detects by trying: posthog_distinct_id, distinct_id, id, pk, uuid (in order)
For ActiveJob user association, use the class-level DSL
```
posthog_distinct_id ->(user) { user.email }
```
or pass user_id: in a hash argument
Store API key in Rails credentials or environment variables, never hardcode
For frontend tracking alongside posthog-rails, add the posthog-js snippet to the layout template — posthog-js handles pageviews, session replay, and client-side errors while posthog-ruby handles backend events, server errors, feature flags, and background jobs
posthog-ruby is the Ruby SDK gem name (add
```
gem 'posthog-ruby'
```
to Gemfile) but require it with
```
require 'posthog'
```
(NOT
```
require 'posthog-ruby'
```
)
Use PostHog::Client.new(api_key: key, host: host) for instance-based initialization in scripts and CLIs
In CLIs and scripts: MUST call client.shutdown before exit or all events are lost
Use begin/rescue/ensure with shutdown in the ensure block for proper cleanup
capture and identify take a single hash argument: client.capture(distinct_id: 'user_123', event: 'my_event', properties: { key: 'value' })
capture_exception takes POSITIONAL args (not keyword): client.capture_exception(exception, distinct_id, additional_properties) — do NOT use
```
distinct_id:
```
keyword syntax

搭配使用posthog-rails gem与posthog-ruby，实现自动异常捕获和ActiveJob instrumentation
运行
```
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名称（在Gemfile中添加
```
gem 'posthog-ruby'
```
），但需使用
```
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:
```
关键字语法