Setting the file. One moment.
Chapter 199 · Omnibus Instrument Product Analytics
Subchapter 199.57
references/ruby.mdMarkdown19 KBView on GitHub
The posthog-ruby library provides tracking functionality on the server-side for applications built in Ruby.
It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server-side application that needs performance.
Add this to your Gemfile:
Terminal
PostHog AI
gem "posthog-ruby"In your app, set your API key before making any calls. If setting a custom host, make sure to include the protocol (e.g. https://).
Ruby
PostHog AI
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 }
})You can find your project token and instance address in the project settings (opens in a new tab) page in PostHog.
Identifying users is required. Backend events need a
distinct_idthat matches the ID your frontend uses when callingposthog.identify(). Without this, backend events are orphaned — they can’t be linked to frontend event captures, session replays (opens in a new tab), LLM traces (opens in a new tab), or error tracking (opens in a new tab).See our guide on identifying users (opens in a new tab) for how to set this up.
You can send custom events using capture:
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_the_user',
event: 'user_signed_up'
})Tip: We recommend using a
[object] [verb]format for your event names, where[object]is the entity that the behavior relates to, and[verb]is the behavior itself. For example,project created,user signed up, orinvite sent.
Optionally, you can include additional information with the event by including a properties (opens in a new tab) object:
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_the_user',
event: 'user_signed_up',
properties: {
login_type: 'email',
is_free_trial: true
}
})If you’re aiming for a backend-only implementation of PostHog and won’t be capturing events from your frontend, you can send pageviews from your backend like so:
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_the_user',
event: '$pageview',
properties: {
'$current_url': 'https://example.com'
}
})The Ruby SDK captures identified events by default. These create person profiles (opens in a new tab). To set person properties (opens in a new tab) in these profiles, include them when capturing an event:
Ruby
PostHog AI
posthog.capture(
distinct_id: 'distinct_id',
event: 'event_name',
properties: {
'$set': { name: 'Max Hedgehog' },
'$set_once': { initial_url: '/blog' }
}
)For more details on the difference between $set and $set_once, see our person properties docs (opens in a new tab).
To capture anonymous events (opens in a new tab) without person profiles, set the event’s $process_person_profile property to false:
Ruby
PostHog AI
posthog.capture(
distinct_id: 'distinct_id',
event: 'event_name',
properties: {
'$process_person_profile': false
}
)Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.
In this case, you can use alias to assign another distinct ID to the same user.
Ruby
PostHog AI
posthog.alias(
distinct_id: "distinct_id",
alias: "alias_id"
)We strongly recommend reading our docs on alias (opens in a new tab) to best understand how to correctly use this method.
PostHog’s feature flags (opens in a new tab) enable you to safely deploy and roll back new features as well as target specific users and groups with them.
There are 2 steps to implement feature flags in Ruby:
Ruby
PostHog AI
is_my_flag_enabled = posthog.is_feature_enabled('flag-key', 'distinct_id_of_your_user')
if is_my_flag_enabled
# Do something differently for this user
# Optional: fetch the payload
matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')
endRuby
PostHog AI
enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')
if enabled_variant == 'variant-key' # replace 'variant-key' with the key of your variant
# Do something differently for this user
# Optional: fetch the payload
matched_flag_payload = posthog.get_feature_flag_payload('variant-key', 'distinct_id_of_your_user')
endIf you want use your feature flag to breakdown or filter events in your insights (opens in a new tab), you’ll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API (opens in a new tab).
There are two methods you can use to include feature flag information in your events:
In the event properties, include $feature/feature_flag_name: variant_key:
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
properties: {
'$feature/feature-flag-key': 'variant-key', # replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
}
})The capture() method has an optional argument send_feature_flags, which is set to false by default. This parameter controls whether feature flag information is sent with the event.
Setting send_feature_flags to true will include feature flag information with the event:
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
send_feature_flags: true,
})As of version 3.1.0, send_feature_flags can also accept a hash for more granular control:
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_your_user',
event: 'event_name',
send_feature_flags: {
only_evaluate_locally: true,
person_properties: { plan: 'premium' },
group_properties: { org: { tier: 'enterprise' } }
}
})With local evaluation: When local evaluation (opens in a new tab) is configured, setting send_feature_flags: true will not make additional server requests. Instead, it uses the locally cached feature flags, and it provides an interface for including person and/or group properties needed to evaluate the flags in the context of the event, if required.
Without local evaluation: PostHog will make an additional request to fetch feature flag information before capturing the event, which adds delay.
Prior to version 3.1.0, feature flags were automatically sent with events when using local evaluation, even when send_feature_flags was not explicitly set. This behavior has been removed in v3.1.0 to be more predictable and explicit.
If you were relying on this automatic behavior, you must now explicitly set send_feature_flags: true to continue sending feature flags with your events.
You can fetch all flag values for a single user by calling get_all_flags() or get_all_flags_and_payloads().
This is useful when you need to fetch multiple flag values and don’t want to make multiple requests.
Ruby
PostHog AI
posthog.get_all_flags('distinct_id_of_your_user')
posthog.get_all_flags_and_payloads('distinct_id_of_your_user')Capturing $feature_flag_called events enable PostHog to know when a flag was accessed by a user and thus provide analytics and insights (opens in a new tab) on the flag. By default, we send a these event when:
posthog.get_feature_flag() or posthog.is_feature_enabled(), ANDNote: Tracking whether it’s a new user or if a flag value has changed happens in a local cache. This means that if you reinitialize the PostHog client, the cache resets as well – causing
$feature_flag_calledevents to be sent again when callingget_feature_flagoris_feature_enabled. PostHog is built to handle this, and so duplicate$feature_flag_calledevents won’t affect your analytics.
You can disable automatically capturing $feature_flag_called events. For example, when you don’t need the analytics, or it’s being called at such a high volume that sending events slows things down.
To disable it, set the send_feature_flag_events argument in your function call, like so:
Ruby
PostHog AI
is_my_flag_enabled = posthog.is_feature_enabled(
'flag-key',
'distinct_id_of_your_user',
send_feature_flag_events: true)Sometimes, you may want to evaluate feature flags using person properties (opens in a new tab), groups (opens in a new tab), or group properties that haven’t been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
Ruby
PostHog AI
posthog.get_feature_flag(
'flag-key',
'distinct_id_of_the_user',
person_properties: {
'property_name': 'value'
},
groups: {
'your_group_type': 'your_group_id',
'another_group_type': 'your_group_id',
},
group_properties: {
'your_group_type': {
'group_property_name': 'value'
}
'another_group_type': {
'group_property_name': 'value'
}
},
)By default, a user’s GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you’re not using PostHog on your frontend, so the user has no GeoIP properties.
You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you’re evaluating flags on your backend and want to use the client’s location instead of your server’s location.
The following GeoIP properties can be overridden:
$geoip_country_code$geoip_country_name$geoip_city_name$geoip_city_confidence$geoip_continent_code$geoip_continent_name$geoip_latitude$geoip_longitude$geoip_postal_code$geoip_subdivision_1_code$geoip_subdivision_1_name$geoip_subdivision_2_code$geoip_subdivision_2_name$geoip_subdivision_3_code$geoip_subdivision_3_name$geoip_time_zoneSimply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.
You can configure the feature_flag_request_timeout_seconds parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog’s servers are too slow to respond. By default, this is set at 3 seconds.
Ruby
PostHog AI
posthog = PostHog::Client.new({
# rest of your configuration...
feature_flag_request_timeout_seconds: 3 # Time in seconds. Default is 3.
})When using the PostHog SDK, it’s important to handle potential errors that may occur during feature flag operations. Here’s an example of how to wrap PostHog SDK methods in an error handler:
Ruby
PostHog AI
def handle_feature_flag(client, flag_key, distinct_id)
begin
is_enabled = client.is_feature_enabled(flag_key, distinct_id)
puts "Feature flag '#{flag_key}' for user '#{distinct_id}' is #{is_enabled ? 'enabled' : 'disabled'}"
return is_enabled
rescue => e
puts "Error fetching feature flag '#{flag_key}': #{e.message}"
# Optionally, you can return a default value or throw the error
# return false # Default to disabled
raise e
end
end
# Usage example
try
flag_enabled = handle_feature_flag(client, 'new-feature', 'user-123')
if flag_enabled
# Implement new feature logic
else
# Implement old feature logic
end
rescue => e
# Handle the error at a higher level
puts 'Feature flag check failed, using default behavior'
# Implement fallback logic
endEvaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.
It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.
For details on how to implement local evaluation, see our local evaluation guide (opens in a new tab).
If you have preload_app true in your unicorn config, you can use the after_fork (opens in a new tab) hook (which is part of the unicorn’s configuration) to enable the feature flag cache to receive the updates from posthog dashboard.
Ruby
PostHog AI
after_fork do |server, worker|
$posthog = PostHog::Client.new(
api_key: '<ph_project_token>',
personal_api_key: '<ph_personal_api_key>'
host: 'https://us.i.posthog.com',
on_error: Proc.new { |status, msg| print msg }
)
endIf you use Puma with multiple workers, you can use the on_worker_boot hook (which is part of the Puma’s configuration) to enable the feature flag cache to receive the updates from PostHog.
Ruby
PostHog AI
on_worker_boot do
$posthog = PostHog::Client.new(
api_key: '<ph_project_token>',
personal_api_key: '<ph_personal_api_key>'
host: 'https://us.i.posthog.com',
on_error: Proc.new { |status, msg| print msg }
)
endSince experiments (opens in a new tab) use feature flags, the code for running an experiment is very similar to the feature flags code:
Ruby
PostHog AI
variant = posthog.get_feature_flag('experiment-feature-flag-key', 'user_distinct_id')
if variant == 'variant-name'
# Do something
endIt’s also possible to run experiments without using feature flags (opens in a new tab).
Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). Read the Group Analytics (opens in a new tab) guide for more information.
Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more on the pricing page (opens in a new tab).
Ruby
PostHog AI
posthog.capture({
distinct_id: 'distinct_id_of_the_user',
event: 'movie_played',
properties: {
movie_id: '123',
category: 'romcom'
}
groups: {
'company': 'company_id_in_your_db'
}
})Ruby
PostHog AI
posthog.group_identify(
{
group_type: "company",
group_key: "company_id_in_your_db",
properties: {
name: "Awesome Inc."
}
}
)The name is a special property which is used in the PostHog UI for the name of the group. If you don’t specify a name property, the group ID will be used instead.
If the optional distinct_id is not provided in the group identify call, it defaults to ${groupType}_${groupKey} (e.g., $company_company_id_in_your_db in the example above). This default behavior will result in each group appearing as a separate person in PostHog. To avoid this, it’s often more practical to use a consistent distinct_id, such as group_identifier.
You can capture exceptions using the posthog-ruby library. This enables you to see stack traces and debug errors in your application. Learn more in our error tracking docs (opens in a new tab).
Using Rails?
The posthog-rails (opens in a new tab) gem provides automatic exception capture, ActiveJob instrumentation, and user context out of the box. See our Rails error tracking guide (opens in a new tab) for details.
For non-Rails Ruby applications, you can manually capture exceptions:
To capture exceptions, use the capture_exception method:
Ruby
PostHog AI
begin
# Code that might raise an exception
raise StandardError, "Something went wrong"
rescue => e
posthog.capture_exception(
e,
distinct_id: 'user_distinct_id',
properties: {
custom_property: 'custom_value'
}
)
endThe capture_exception method accepts the following parameters:
| Parameter | Type | Description |
|---|---|---|
| exception | Exception | The exception object to capture (required) |
| distinct_id | String | The distinct ID of the user (optional) |
| properties | Hash | Additional properties to attach to the exception event (optional) |
You can also override the fingerprint (opens in a new tab) to customize how exceptions are grouped into issues:
Ruby
PostHog AI
posthog.capture_exception(
e,
distinct_id: 'user_distinct_id',
properties: {
'$exception_fingerprint': 'CustomExceptionGroup'
}
)The Ruby SDK debug logs by default. The log level by default is set to WARN. You can change it to DEBUG if you want to debug the client by running posthog.logger.level = Logger::DEBUG, where posthog is your initialized PostHog::Client instance.
This library is largely based on the analytics-ruby package.
Ask a question
HelpfulCould be better
Nearby