references/ruby.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Ruby Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/ruby
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install with the wizard
- Install the gem
- Configure PostHog
- Send events
- Manually capture exceptions
- Verify error tracking
- Link releases
Install with the wizard
Run this command in your project directory to add PostHog to your Ruby project. The wizard detects your framework, installs the SDK, and sets up your first events.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
-
1
Install the gem
Required
Add the PostHog Ruby gem to your Gemfile:
Gemfile
gem "posthog-ruby" -
2
Configure PostHog
Required
Initialize the PostHog client with your project token and host:
Ruby
require 'posthog' posthog = PostHog::Client.new({ api_key: "<ph_project_token>", host: "https://us.i.posthog.com", on_error: Proc.new { |status, msg| print msg } }) -
3
Send events
Recommended
Once installed, you can manually send events to test your integration:
Ruby
posthog.capture({ distinct_id: 'user_123', event: 'button_clicked', properties: { button_name: 'signup' } }) -
4
Manually capture exceptions
Required
Using Ruby on Rails? The
posthog-railsgem provides automatic exception capture for controllers and background jobs. Select "Ruby on Rails" from the SDK list for setup instructions.To capture exceptions in your Ruby application, use the
capture_exceptionmethod:Ruby
begin # Code that might raise an exception raise StandardError, "Something went wrong" rescue => e posthog.capture_exception( e, 'user_distinct_id', { custom_property: 'custom_value' } ) endThe
capture_exceptionmethod accepts the following parameters:| Param | Type | Description | | --- | --- | --- | |
exception|Exception| The exception object to capture (required) | |distinct_id|String| The distinct ID of the user (optional) | |additional_properties|Hash| Additional properties to attach to the exception event (optional) | -
Verify error tracking
Recommended
Confirm events are being sent to PostHog
Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
Activity feed with events
-
5
Link releases
Optional
Great, you're capturing exceptions! To see which release each exception comes from, give your app the release ID when you deploy.
Let's continue to the next section.