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() を使用してください。

フレームワークのガイドライン

• 自動例外キャプチャと ActiveJob のインストルメンテーションには、posthog-ruby とともに posthog-rails gem を使用してください。
• rails generate posthog:install を実行してイニシャライザーを作成するか、config/initializers/posthog.rb を手動で作成してください。
• コントローラーの未処理の例外を自動的にトラッキングするには、auto_capture_exceptions: true を設定してください。
• Rails がレスキューする例外（例：rescue_from を使用した場合）もキャプチャするには、report_rescued_exceptions: true を設定してください。
• ジョブクラス、キュー、引数とともにバックグラウンドジョブの失敗をトラッキングするには、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 を必ず呼び出してください。呼び出さないと、すべてのイベントが失われます。
• 適切にクリーンアップするには、ensure ブロック内で shutdown を呼び出す begin/rescue/ensure を使用してください。
• 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: のキーワード構文は使用しないでください。