Ruby

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.

Use a single client instance (singleton) — Create the PostHog client once and reuse it throughout your application. Multiple client instances with the same API key can cause dropped events and inconsistent behavior. The SDK logs a warning if it detects multiple instances.

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.

Or set it up manually by following the rest of this guide.

Installation

Add this to your Gemfile:

gem "posthog-ruby", "~> 3.0"

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://).

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 page in PostHog.

Configuration

Initialize the client with your project token before making any calls:

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 }
})

Available client options:

Filtering or modifying events before sending

Use before_send to add, modify, or drop events immediately before the SDK queues or sends them:

posthog = PostHog::Client.new({
  api_key: '<ph_project_token>',
  before_send: Proc.new do |event|
    event[:properties] ||= {}
    event[:properties]['environment'] = ENV['RACK_ENV']

    # Return nil to drop the event
    event[:properties]['internal_user'] == true ? nil : event
  end
})

Flushing and shutting down

For short-lived scripts, call flush before the process exits. Call shutdown when your application is stopping to flush pending events and stop background resources.

posthog.capture({ distinct_id: 'user_123', event: 'script_finished' })
posthog.flush
posthog.shutdown

From version 3.22.0, both methods accept timeout: in seconds and return a Boolean:

flushed = posthog.flush(timeout: 5)
stopped = posthog.shutdown(timeout: 5)

In async mode, both return true when pending events are sent, or false on timeout. flush leaves the client running. shutdown stops it and drops events still queued at the deadline. Cleanup can take up to one extra second. Without a timeout, both wait indefinitely.

With sync_mode: true, both wait for in-flight event requests without honoring timeout:.

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, LLM traces, or error tracking.

See our guide on identifying users for how to set this up.

Identify a user and set their person properties with identify:

posthog.identify({
  distinct_id: 'distinct_id_of_your_user',
  properties: {
    email: 'john@doe.com',
    pro_user: false
  }
})

Capturing events

You can send custom events using capture:

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, or invite sent.

Setting event properties

Optionally, you can include additional information with the event by including a properties object:

posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: 'user_signed_up',
    properties: {
        login_type: 'email',
        is_free_trial: true
    }
})

Sending pageviews

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:

posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: '$pageview',
    properties: {
        '$current_url': 'https://example.com'
    }
})

capture accepts these fields:

Person profiles and properties

The Ruby SDK captures identified events by default. These create person profiles. To set person properties in these profiles, include them when capturing an event:

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.

To capture anonymous events without person profiles, set the event's $process_person_profile property to false:

posthog.capture({
    distinct_id: 'distinct_id',
    event: 'event_name',
    properties: {
        '$process_person_profile': false
    }
})

Alias

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.

posthog.alias({
  distinct_id: 'distinct_id',
  alias: 'alias_id'
})

We strongly recommend reading our docs on alias to best understand how to correctly use this method.

Feature flags

PostHog's feature flags enable you to safely deploy and roll back new features as well as target specific users and groups with them.

There are two steps to implement feature flags in Ruby:

Step 1: Evaluate flags once

Call posthog.evaluate_flags() once for the user, then read values from the returned snapshot.

Boolean feature flags

flags = posthog.evaluate_flags('distinct_id_of_your_user')

if flags.enabled?('flag-key')
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = flags.get_flag_payload('flag-key')
end

Multivariate feature flags

flags = posthog.evaluate_flags('distinct_id_of_your_user')

enabled_variant = flags.get_flag('flag-key')

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 = flags.get_flag_payload('flag-key')
end

flags.get_flag() returns the variant string for multivariate flags, true for enabled boolean flags, false for disabled flags, and nil when the flag wasn't returned by the evaluation.

Note: posthog.is_feature_enabled(), posthog.get_feature_flag(), posthog.get_feature_flag_result(), posthog.get_feature_flag_payload(), and capture({ ..., send_feature_flags: true }) still work during the migration period, but they're deprecated. Prefer evaluate_flags() for new code.

Step 2: Include feature flag information when capturing events

If you want use your feature flag to breakdown or filter events in your insights, 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.

There are two methods you can use to include feature flag information in your events:

Method 1: Pass the evaluated flags snapshot to capture()

Pass the same flags object that you used for branching. This attaches the exact flag values from that evaluation and doesn't make another /flags request.

flags = posthog.evaluate_flags('distinct_id_of_your_user')

if flags.enabled?('flag-key')
    # Do something differently for this user
end

posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags,
})

By default, this attaches every flag in the snapshot using $feature/<flag-key> properties and $active_feature_flags.

To reduce event property bloat, pass a filtered snapshot:

# Attach only flags accessed with enabled?() or get_flag() before this call
posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags.only_accessed,
})

# Attach only specific flags
posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags.only(['checkout-flow', 'new-dashboard']),
})

only_accessed is order-dependent. If you call it before accessing any flags with enabled?() or get_flag(), no feature flag properties are attached.

Method 2: Include the $feature/feature_flag_name property manually

In the event properties, include $feature/feature_flag_name: variant_key:

posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    properties: {
        # Replace feature-flag-key with your flag key and 'variant-key' with the key of your variant
        '$feature/feature-flag-key': 'variant-key',
    },
})

Evaluating only specific flags

By default, evaluate_flags() evaluates every flag for the user. If you only need a few flags, pass flag_keys to request only those flags:

flags = posthog.evaluate_flags(
    'distinct_id_of_your_user',
    flag_keys: ['checkout-flow', 'new-dashboard'],
)

Evaluating locally only

If you want to skip the remote /flags request and only use locally cached definitions, pass only_evaluate_locally: true:

flags = posthog.evaluate_flags(
    'distinct_id_of_your_user',
    only_evaluate_locally: true,
)

Disabling GeoIP for flag evaluation

Pass disable_geoip: true to disable GeoIP lookup for remote flag evaluation:

flags = posthog.evaluate_flags(
    'distinct_id_of_your_user',
    disable_geoip: true,
)

Sending $feature_flag_called events

Capturing $feature_flag_called events enables PostHog to know when a flag was accessed by a user and provide analytics and insights on the flag. With evaluate_flags(), the SDK sends this event when you call flags.enabled?() or flags.get_flag() for a flag.

The SDK deduplicates these events per (distinct_id, flag, value) in a local cache. If you reinitialize the PostHog client, the cache resets and $feature_flag_called events may be sent again. PostHog handles duplicates, so duplicate $feature_flag_called events don't affect your analytics.

flags.get_flag_payload() doesn't send $feature_flag_called events and doesn't count as an access for only_accessed.

Advanced: Overriding server properties

Sometimes, you may want to evaluate feature flags using person properties, groups, 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:

flags = posthog.evaluate_flags(
    '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'
        },
    },
)

if flags.enabled?('flag-key')
    # Do something differently for this user
end

Overriding GeoIP properties

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_zone

Simply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.

Request timeout

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 if PostHog's servers are too slow to respond. By default, this is set to 3 seconds.

posthog = PostHog::Client.new({
    # rest of your configuration...
    feature_flag_request_timeout_seconds: 3 # Time in seconds. Defaults to 3.
})

Default values

From version 3.27.0, use default_value: when a flag has no value:

flags = posthog.evaluate_flags("user_123")
show_checkout = flags.enabled?("new-checkout", default_value: true)

The default applies only when the snapshot has no value for the flag. Evaluated values, including false and server-reported failures, take precedence. Without a default, missing flags return false.

Legacy single-flag methods

The following methods are still available during the migration period, but are deprecated. Prefer evaluate_flags for new code.

Local evaluation

Evaluating 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.

Set secret_key to a personal or project secret API key with feature flag read access. Keep it on your server. Remote evaluation does not require it. See the local evaluation guide for setup.

Load definitions asynchronously

From version 3.20.0, set feature_flags_async_load: true to avoid waiting for local flag definitions during client initialization:

posthog = PostHog::Client.new({
  api_key: "<ph_project_token>",
  secret_key: ENV.fetch("POSTHOG_SECRET_KEY"),
  feature_flags_async_load: true
})

posthog.feature_flags_loaded?

Until feature_flags_loaded? returns true, evaluations use a remote request. With only_evaluate_locally: true, unavailable flags have no value instead.

Diagnose unresolved flags

From version 3.29.0, inspect unresolved_flags to see why flags could not be evaluated:

flags = posthog.evaluate_flags("user_123", only_evaluate_locally: true)
flags.unresolved_flags.each do |key, reason|
  posthog.logger.warn("Flag #{key} could not resolve locally: #{reason}")
end

Reasons are experience_continuity, unsupported_definition, unresolved_dependency, or missing_context. Unresolved flags use the missing-flag default. The SDK also warns about definitions that cannot be evaluated locally.

Evaluating feature flags locally in unicorn server

If you have preload_app true in your unicorn config, you can use the after_fork hook (which is part of the unicorn's configuration) to enable the feature flag cache to receive the updates from PostHog.

after_fork do |_server, _worker|
  $posthog = PostHog::Client.new({
    api_key: '<ph_project_token>',
    secret_key: ENV.fetch("POSTHOG_SECRET_KEY"),
    host: 'https://us.i.posthog.com',
    on_error: Proc.new { |status, msg| print msg }
  })
end

Evaluating feature flags locally in a Puma server

If you use Puma with multiple workers, you can use the on_worker_boot hook (which is part of Puma's configuration) to enable the feature flag cache to receive updates from PostHog.

on_worker_boot do
  $posthog = PostHog::Client.new({
    api_key: '<ph_project_token>',
    secret_key: ENV.fetch("POSTHOG_SECRET_KEY"),
    host: 'https://us.i.posthog.com',
    on_error: Proc.new { |status, msg| print msg }
  })
end

Distributed flag definition caching

flag_definition_cache_provider shares locally evaluated feature flag definitions across multiple workers or processes. The provider object must implement:

• flag_definitions – returns cached definitions as a hash with :flags, :group_type_mapping, :cohorts, :minimal_flag_called_events, and :property_matching_version, or nil if empty.
• should_fetch_flag_definitions? – returns true if this process should fetch fresh definitions from PostHog.
• on_flag_definitions_received(data) – stores freshly fetched definitions.
• shutdown – releases locks or other resources.

posthog = PostHog::Client.new({
  api_key: '<ph_project_token>',
  secret_key: ENV.fetch("POSTHOG_SECRET_KEY"),
  flag_definition_cache_provider: my_cache_provider
})

Store the complete snapshot, including property_matching_version, to preserve flag matching behavior.

From version 3.27.1, cache-only clients can omit secret_key. Without a key, they cannot fetch definitions if the cache is unavailable.

In Rails, set config.flag_definition_cache_provider inside PostHog.init from posthog-rails 3.19.0.

Remote config payloads

Use get_remote_config_payload to fetch the decrypted remote config payload for a flag. This requires secret_key.

payload = posthog.get_remote_config_payload('flag-key')

Experiments (A/B tests)

Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code:

flags = posthog.evaluate_flags('user_distinct_id')
variant = flags.get_flag('experiment-feature-flag-key')

if variant == 'variant-name'
    # Do something
end

It's also possible to run experiments without using feature flags.

Group analytics

Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). Read the Group Analytics 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.

Capture an event and associate it with a group:

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'
    }
})

Update properties on a group:

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 $#{group_type}_#{group_key} (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.

Exception capture

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.

For non-Rails Ruby applications, you can manually capture exceptions with capture_exception:

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'
    }
  )
end

The capture_exception method accepts the following parameters:

Reports include chained causes and active OpenTelemetry trace and span IDs, when available. Repeated captures of the same mutable exception are ignored after the first successful report. Include identity and context on the first call.

To associate errors with a deployment, see link Ruby releases.

You can also override the fingerprint to customize how exceptions are grouped into issues:

posthog.capture_exception(
  e,
  'user_distinct_id',
  {
    '$exception_fingerprint': 'CustomExceptionGroup'
  }
)

Transactional emails

From version 3.30.0, use posthog.emails to send emails and check delivery status. See send transactional emails with Ruby for setup and examples.

Debug mode

The Ruby SDK logs warnings by default. You can change the log level to DEBUG to debug the client:

posthog.logger.level = Logger::DEBUG

You can also replace the SDK logger globally:

PostHog::Logging.logger = Rails.logger

Test helpers

When test_mode: true, events remain queued. You can inspect and clear the queue in tests:

posthog = PostHog::Client.new({ api_key: '<ph_project_token>', test_mode: true })
posthog.capture({ distinct_id: 'user_123', event: 'test_event' })

posthog.queued_messages
posthog.dequeue_last_message
posthog.clear

Thank you

This library is largely based on the analytics-ruby package.