vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/instrument-feature-flags/references/ruby-on-rails.md

@@ -0,0 +1,604 @@
+# Ruby on Rails - Docs
+
+PostHog makes it easy to get data about traffic and usage of your Ruby on Rails app. Integrating PostHog enables analytics, custom event capture, feature flags, and automatic exception tracking.
+
+This guide walks you through integrating PostHog into your Rails app using the [posthog-rails gem](https://github.com/PostHog/posthog-ruby/tree/main/posthog-rails).
+
+## Beta: integration via LLM
+
+Install PostHog for Rails in seconds with our wizard by running this prompt with [LLM coding agents](/blog/envoy-wizard-llm-agent.md) like Cursor and Bolt, or by running it in your terminal.
+
+`npx @posthog/wizard`
+
+[Learn more](/wizard.md)
+
+Or, to integrate manually, continue with the rest of this guide.
+
+## Features
+
+-   **Automatic exception tracking** – Captures unhandled and rescued exceptions
+-   **ActiveJob instrumentation** – Tracks background job exceptions
+-   **User context** – Automatically associates exceptions with the current user
+-   **Smart filtering** – Excludes common Rails exceptions (404s, etc.) by default
+-   **Request context** – Adds request metadata and optional PostHog tracing header identity/session context to captured events
+-   **Rails 7.0+ error reporter** – Integrates with Rails' built-in error reporting
+-   **Log forwarding** – Optionally forwards `Rails.logger` output to [PostHog Logs](/docs/logs.md) over OpenTelemetry, automatically correlated with request context (Ruby 3.3+)
+
+## Installation
+
+Add both gems to your Gemfile:
+
+Gemfile
+
+PostHog AI
+
+```ruby
+gem 'posthog-ruby', require: 'posthog'
+gem 'posthog-rails'
+```
+
+Then run:
+
+Terminal
+
+PostHog AI
+
+```bash
+bundle install
+```
+
+## Identifying users
+
+> **Identifying users is required.** Backend events need a `distinct_id` that matches the ID your frontend uses when calling `posthog.identify()`. Without this, backend events are orphaned — they can't be linked to frontend event captures, [session replays](/docs/session-replay.md), [LLM traces](/docs/ai-engineering.md), or [error tracking](/docs/error-tracking.md).
+>
+> See our guide on [identifying users](/docs/getting-started/identify-users.md) for how to set this up.
+
+### Generate the initializer
+
+Run the install generator to create the PostHog initializer:
+
+Terminal
+
+PostHog AI
+
+```bash
+rails generate posthog:install
+```
+
+This creates `config/initializers/posthog.rb` with sensible defaults and documentation.
+
+## Configuration
+
+`PostHog.init` creates a single client instance used across your app. Avoid creating multiple `PostHog::Client` instances with the same API key, as this can cause dropped events and inconsistent behavior.
+
+The generated initializer includes the most common options:
+
+config/initializers/posthog.rb
+
+PostHog AI
+
+```ruby
+# Rails-specific configuration
+PostHog::Rails.configure do |config|
+  config.auto_capture_exceptions = true           # Enable automatic exception capture (default: false)
+  config.report_rescued_exceptions = true         # Report exceptions Rails rescues (default: false)
+  config.auto_instrument_active_job = true        # Instrument background jobs (default: false)
+  config.use_tracing_headers = true               # Use PostHog tracing headers for identity/session context (default: true)
+  config.capture_user_context = true              # Include authenticated user info in exceptions (default: true)
+  config.current_user_method = :current_user      # Method to get current user (default: :current_user)
+  config.user_id_method = nil                     # Method to get ID from user object (default: auto-detect)
+  # Add additional exceptions to ignore
+  config.excluded_exceptions = ['MyCustomError']
+end
+# Core PostHog client initialization
+PostHog.init do |config|
+  # Required: Your PostHog project API key
+  config.api_key = '<ph_project_token>'
+  # Optional: Your PostHog instance URL
+  config.host = 'https://us.i.posthog.com'
+  # Optional: Personal API key for feature flags
+  config.personal_api_key = 'phx_xxxxxxxxx'
+  # Maximum number of events to queue before dropping (default: 10000)
+  config.max_queue_size = 10_000
+  # Send events synchronously on the calling thread (default: false)
+  config.sync_mode = false
+  # Feature flags polling interval in seconds (default: 30)
+  config.feature_flags_polling_interval = 30
+  # Feature flag request timeout in seconds (default: 3)
+  config.feature_flag_request_timeout_seconds = 3
+  # Error callback to detect misconfiguration
+  config.on_error = proc { |status, msg|
+    Rails.logger.error("PostHog error: #{msg}")
+  }
+  # Before-send callback to modify or drop events
+  config.before_send = proc { |event|
+    event[:properties] ||= {}
+    event[:properties]['environment'] = Rails.env
+    event
+  }
+  # Disable network calls in test mode
+  config.test_mode = true if Rails.env.test?
+end
+```
+
+You can find your project token and instance address in [your project settings](https://us.posthog.com/project/settings).
+
+> **Tip:** Use [`Rails.application.credentials`](https://guides.rubyonrails.org/security.html#custom-credentials) to avoid hardcoding API keys. First, add your keys and then reference them in your initializer:
+>
+> Terminal
+>
+> PostHog AI
+>
+> ```bash
+> rails credentials:edit
+> ```
+>
+> config/credentials.yml.enc
+>
+> PostHog AI
+>
+> ```yaml
+> posthog:
+>   api_key: <ph_project_token>
+>   host: https://us.i.posthog.com
+>   personal_api_key: phx_xxxxxxxxx
+> ```
+>
+> config/initializers/posthog.rb
+>
+> PostHog AI
+>
+> ```ruby
+> config.api_key = Rails.application.credentials.posthog[:api_key]
+> config.host = Rails.application.credentials.posthog[:host]
+> config.personal_api_key = Rails.application.credentials.posthog[:personal_api_key]
+> ```
+
+## Capturing events
+
+Track custom events anywhere in your Rails app:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog.capture({
+  distinct_id: current_user.id,
+  event: 'post_created',
+  properties: { title: @post.title }
+})
+```
+
+Identify a user and set their person properties:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog.identify({
+  distinct_id: current_user.id,
+  properties: {
+    email: current_user.email,
+    plan: current_user.plan
+  }
+})
+```
+
+The Rails integration delegates methods like `capture`, `identify`, `alias`, `group_identify`, `evaluate_flags`, `capture_exception`, `flush`, and `shutdown` to the initialized `PostHog::Client`.
+
+## Request context
+
+PostHog Rails automatically applies request-scoped context to events captured during web requests. Request metadata such as `$current_url`, `$request_method`, `$request_path`, `$user_agent`, and `$ip` is added to event properties.
+
+When `use_tracing_headers` is enabled, PostHog tracing headers (`X-PostHog-Distinct-Id` and `X-PostHog-Session-Id`) are also used as default `distinct_id` and `$session_id` values. Explicit `distinct_id` and properties passed to `PostHog.capture` always take precedence.
+
+If you're using [PostHog JS](/docs/libraries/js.md) on the frontend, configure [`tracing_headers`](/docs/libraries/js/config.md#tracing-headers) for your Rails backend hostname so browser requests include the session and distinct ID headers.
+
+Tracing headers are client-controlled analytics context, not authentication or authorization. Pass an authenticated `distinct_id` explicitly for security-sensitive server-side decisions.
+
+Disable tracing header identity/session capture if you do not want client-supplied tracing headers used for server-side events. Request metadata is still captured:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog::Rails.config.use_tracing_headers = false
+```
+
+## Logs
+
+To set up [PostHog Logs](/docs/logs.md) in your Rails app, follow the [Ruby on Rails logs installation guide](/docs/logs/installation/ruby-on-rails.md). The integration forwards `Rails.logger` output to PostHog Logs over OpenTelemetry, automatically correlated with each request's distinct ID and session ID. Requires Ruby 3.3+.
+
+## Error tracking
+
+For full details on setting up error tracking with Rails, see our [Rails error tracking installation guide](/docs/error-tracking/installation/ruby-on-rails.md).
+
+### Automatic exception tracking
+
+When `auto_capture_exceptions` is enabled, exceptions are automatically captured:
+
+Ruby
+
+PostHog AI
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+    # Any exception here is automatically captured
+  end
+end
+```
+
+`report_rescued_exceptions` controls whether exceptions Rails rescues (for example, exceptions rendered by Rails error pages) are captured. Enable it along with `auto_capture_exceptions` for complete error visibility, or leave it disabled to capture only unhandled exceptions.
+
+### Manual exception capture
+
+You can also manually capture exceptions:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog.capture_exception(
+  exception,
+  current_user.id,
+  { custom_property: 'value' }
+)
+```
+
+If you evaluated feature flags for the request, pass the same snapshot to include matching flag properties on the exception event:
+
+Ruby
+
+PostHog AI
+
+```ruby
+flags = PostHog.evaluate_flags(current_user.id)
+PostHog.capture_exception(
+  exception,
+  current_user.id,
+  { custom_property: 'value' },
+  flags: flags
+)
+```
+
+### Background job exceptions
+
+When `auto_instrument_active_job` is enabled, ActiveJob exceptions are automatically captured with job context:
+
+Ruby
+
+PostHog AI
+
+```ruby
+class EmailJob < ApplicationJob
+  def perform(user_id)
+    user = User.find(user_id)
+    UserMailer.welcome(user).deliver_now
+    # Exceptions are automatically captured
+  end
+end
+```
+
+#### Associating jobs with users
+
+By default, PostHog extracts a `distinct_id` from job arguments by looking for a `user_id` key in hash arguments:
+
+Ruby
+
+PostHog AI
+
+```ruby
+# PostHog will automatically use options[:user_id] as the distinct_id
+ProcessOrderJob.perform_later(order.id, user_id: current_user.id)
+```
+
+For more control, use the `posthog_distinct_id` class method. The proc or block receives the same arguments as `perform`:
+
+Ruby
+
+PostHog AI
+
+```ruby
+class SendWelcomeEmailJob < ApplicationJob
+  posthog_distinct_id ->(user, _options) { user.id }
+  def perform(user, options = {})
+    UserMailer.welcome(user).deliver_now
+  end
+end
+```
+
+You can also use a block:
+
+Ruby
+
+PostHog AI
+
+```ruby
+class ProcessOrderJob < ApplicationJob
+  posthog_distinct_id do |_order, notify_user_id|
+    notify_user_id
+  end
+  def perform(order, notify_user_id)
+    # Process the order...
+  end
+end
+```
+
+### Rails 7.0+ error reporter
+
+PostHog integrates with Rails' built-in error reporting:
+
+Ruby
+
+PostHog AI
+
+```ruby
+# These errors are automatically sent to PostHog
+Rails.error.handle do
+  # Code that might raise an error
+end
+Rails.error.record(exception, context: { user_id: current_user.id })
+```
+
+PostHog automatically extracts the user's distinct ID from `user_id` or `distinct_id` in the context hash. Other context keys are included as properties on the exception event.
+
+### User context
+
+PostHog Rails automatically captures authenticated user information from your controllers for exceptions. Authenticated Rails user context takes precedence over client-supplied tracing headers for exception identity.
+
+If your user method has a different name, configure it:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog::Rails.config.current_user_method = :logged_in_user
+```
+
+#### User ID extraction
+
+By default, PostHog Rails auto-detects the user's distinct ID by trying these methods in order:
+
+1.  `posthog_distinct_id` – Define this on your User model for full control
+2.  `distinct_id` – Common analytics convention
+3.  `id` – Standard ActiveRecord primary key
+4.  `pk` – Primary key alias
+5.  `uuid` – For UUID-based primary keys
+
+It also checks hash-like users for `id`, `pk`, and `uuid` keys.
+
+You can configure a specific method:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog::Rails.config.user_id_method = :email
+```
+
+Or define a method on your User model:
+
+Ruby
+
+PostHog AI
+
+```ruby
+class User < ApplicationRecord
+  def posthog_distinct_id
+    "user_#{id}"  # or external_id, or any unique identifier
+  end
+end
+```
+
+### Excluded exceptions
+
+The following exceptions are not reported by default (common 4xx errors):
+
+-   `AbstractController::ActionNotFound`
+-   `ActionController::BadRequest`
+-   `ActionController::InvalidAuthenticityToken`
+-   `ActionController::InvalidCrossOriginRequest`
+-   `ActionController::MethodNotAllowed`
+-   `ActionController::NotImplemented`
+-   `ActionController::ParameterMissing`
+-   `ActionController::RoutingError`
+-   `ActionController::UnknownFormat`
+-   `ActionController::UnknownHttpMethod`
+-   `ActionDispatch::Http::Parameters::ParseError`
+-   `ActiveRecord::RecordNotFound`
+-   `ActiveRecord::RecordNotUnique`
+
+Add more with:
+
+Ruby
+
+PostHog AI
+
+```ruby
+PostHog::Rails.config.excluded_exceptions = ['MyException']
+```
+
+## Feature flags
+
+Evaluate flags once for the current user, then read values from the returned snapshot:
+
+Ruby
+
+PostHog AI
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    flags = PostHog.evaluate_flags(current_user.id)
+    if flags.enabled?('new-post-design')
+      render 'posts/show_new'
+    else
+      render 'posts/show'
+    end
+  end
+end
+```
+
+For multivariate flags and experiments, use `get_flag`:
+
+Ruby
+
+PostHog AI
+
+```ruby
+flags = PostHog.evaluate_flags(current_user.id)
+variant = flags.get_flag('checkout-experiment')
+if variant == 'test'
+  # Do something differently
+end
+```
+
+When capturing an event after branching on a flag, pass the same `flags` snapshot so the event includes the exact flag values used by your code:
+
+Ruby
+
+PostHog AI
+
+```ruby
+flags = PostHog.evaluate_flags(current_user.id)
+PostHog.capture({
+  distinct_id: current_user.id,
+  event: 'checkout_started',
+  flags: flags.only_accessed
+})
+```
+
+For local evaluation, ensure you've set `personal_api_key`:
+
+Ruby
+
+PostHog AI
+
+```ruby
+config.personal_api_key = Rails.application.credentials.posthog[:personal_api_key]
+```
+
+See our [Ruby SDK docs](/docs/libraries/ruby.md#local-evaluation) for details on local evaluation with Puma and Unicorn servers.
+
+> **Note:** `PostHog.is_feature_enabled`, `PostHog.get_feature_flag`, `PostHog.get_feature_flag_result`, `PostHog.get_feature_flag_payload`, and `PostHog.capture({ ..., send_feature_flags: true })` still work during the migration period, but they're deprecated. Prefer `PostHog.evaluate_flags` for new code.
+
+## Testing
+
+In your test environment, disable network calls with test mode:
+
+config/environments/test.rb
+
+PostHog AI
+
+```ruby
+PostHog.init do |config|
+  config.api_key = '<ph_project_token>'
+  config.test_mode = true
+end
+```
+
+Or in your specs:
+
+spec/rails\_helper.rb
+
+PostHog AI
+
+```ruby
+RSpec.configure do |config|
+  config.before(:each) do
+    allow(PostHog).to receive(:capture)
+  end
+end
+```
+
+## Configuration reference
+
+### Core PostHog options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| api_key | String | required | Your PostHog project token. |
+| host | String | https://us.i.posthog.com | Fully qualified PostHog API host. |
+| personal_api_key | String | nil | Personal API key for local feature flag evaluation and remote config payloads. |
+| max_queue_size | Integer | 10000 | Maximum number of events to keep in the async queue before dropping new events. |
+| test_mode | Boolean | false | Keep events queued and do not send them. Useful for tests. |
+| sync_mode | Boolean | false | Send events synchronously on the calling thread. |
+| on_error | Proc | no-op | Callback called as on_error.call(status, error). |
+| feature_flags_polling_interval | Integer | 30 | Seconds between local feature flag definition polls. |
+| feature_flag_request_timeout_seconds | Integer | 3 | Timeout, in seconds, for feature flag requests. |
+| before_send | Proc | nil | Callback that receives the event hash before it is queued or sent. Return a modified event hash, or nil to drop the event. |
+
+The `PostHog.init` block supports the options above. Less common core options like `batch_size`, `disable_singleton_warning`, `skip_ssl_verification`, and `flag_definition_cache_provider` can be passed as an options hash to `PostHog.init(...)`; see the [Ruby SDK docs](/docs/libraries/ruby.md#configuration) for details.
+
+### Rails-specific options
+
+Configure these via `PostHog::Rails.configure` or `PostHog::Rails.config`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| auto_capture_exceptions | Boolean | false | Automatically capture exceptions. |
+| report_rescued_exceptions | Boolean | false | Report exceptions Rails rescues. |
+| auto_instrument_active_job | Boolean | false | Capture ActiveJob exceptions with job context. |
+| excluded_exceptions | Array | [] | Additional exception class names to ignore. |
+| use_tracing_headers | Boolean | true | Use X-PostHog-Distinct-Id and X-PostHog-Session-Id as request-scoped defaults. |
+| capture_user_context | Boolean | true | Include authenticated user info in exceptions. |
+| current_user_method | Symbol | :current_user | Controller method used to fetch the current user. |
+| user_id_method | Symbol | nil | Method used to extract the distinct ID from the user object. Auto-detects when nil. |
+
+## Troubleshooting
+
+### Exceptions not being captured
+
+1.  Verify PostHog is initialized:
+
+    Ruby
+
+    PostHog AI
+
+    ```ruby
+    Rails.console
+    > PostHog.initialized?
+    => true
+    ```
+
+2.  Check your excluded exceptions list.
+
+3.  Verify middleware is installed:
+
+    Ruby
+
+    PostHog AI
+
+    ```ruby
+    Rails.application.middleware
+    ```
+
+### User context not working
+
+1.  Verify `current_user_method` matches your controller method.
+2.  Check that the user object responds to `posthog_distinct_id`, `distinct_id`, `id`, `pk`, or `uuid`.
+3.  If using a custom identifier, set `PostHog::Rails.config.user_id_method = :your_method`.
+
+### Feature flags not working
+
+Ensure you've set `personal_api_key` in your configuration.
+
+## Next steps
+
+For any technical questions for how to integrate specific PostHog features into Rails (such as analytics, feature flags, A/B testing, etc.), have a look at our [Ruby SDK docs](/docs/libraries/ruby.md).
+
+### Community questions
+
+Ask a question
+
+### Was this page useful?
+
+HelpfulCould be better