getfluxly (Ruby)

Server-side Ruby SDK for GetFluxly. Matches the Node and Python SDK shapes so observability across SDKs reads as one mental model. Zero runtime dependencies (uses Net::HTTP from stdlib).

gem install getfluxly

Or in your Gemfile:

gem "getfluxly"

Supports Ruby 3.1+.

Quick start

require "getfluxly"

client = GetFluxly::Client.new(token: "gflux_secret_yourtoken")

client.track("subscription_started",
             external_id: "user_42",
             properties: { plan: "pro" })

client.identify(external_id: "user_42",
                traits: { email: "x@y.com", plan: "pro" })

client.alias(user_id: "user_42", anonymous_id: "anon_a8f3c2")

client.flush
client.shutdown  # also runs from at_exit

Rails integration

Auto-loaded but opt-in via explicit require:

# config/initializers/getfluxly.rb
require "getfluxly/rails"

GetFluxly::Rails.configure do |c|
  c.token = ENV["GFLUX_SERVER_TOKEN"]
end

Then later:

GetFluxly::Rails.client.track("invoice_paid", external_id: "user_42")

A small Rack middleware (GetFluxly::Rails::Middleware) reads the gflux_anon cookie and attaches request.env["gflux.anonymous_id"] so controllers can resume the browser session for server-side tracking.

Defaults

Defaults match Node and Python.

Option	Default	Notes
flush_at	20	Events queued before forced flush
flush_interval	5.0	Periodic flush, seconds
max_retries	2	Per failed batch
timeout	5.0	Per HTTP request, seconds
max_queue_size	1000	Hard cap, raises queue_overflow

Retries: 408, 425, 429, and 5xx with exponential backoff and +/- 25% jitter. Retry-After is honored. Each batch carries a unique X-Idempotency-Key.

Errors

begin
  client.track("invoice_paid", external_id: "user_42")
rescue GetFluxly::Error => e
  case e.code
  when "queue_overflow"
    # back-pressure
  when "rate_limited"
    # SDK already retried max_retries times
  end
end

Full code table at docs.getfluxly.com/snippets/error-table.

License

MIT, see LICENSE.