Ruby

The TraceStax Ruby SDK supports Sidekiq (6.x and 7.x) and Solid Queue (Rails 8). One gem, multiple adapters — load only what your app uses.

Requirements

• Ruby 3.1+
• Sidekiq 6.x or 7.x, or Solid Queue ≥ 0.3

Installation

Add to your Gemfile:

gem "tracestax"

Then run:

bundle install

---

Setup

Sidekiq (Rails)

config/initializers/tracestax.rb

require "tracestax/sidekiq"

TraceStax::Sidekiq.configure do |config|
  config.api_key = ENV["TRACESTAX_API_KEY"]
end

TraceStax::Sidekiq.install!

install! registers TraceStax as a Sidekiq server middleware and starts the heartbeat poller automatically.

Sidekiq (Plain Ruby)

require "tracestax/sidekiq"

TraceStax::Sidekiq.configure do |config|
  config.api_key = ENV["TRACESTAX_API_KEY"]
end

Sidekiq.configure_server do |config|
  config.server_middleware do |chain|
    chain.prepend TraceStax::Sidekiq::ServerMiddleware
  end
end

Solid Queue (Rails 8)

config/initializers/tracestax.rb

require "tracestax/solid_queue"

TraceStax.configure do |config|
  config.api_key = ENV["TRACESTAX_API_KEY"]
end

TraceStax hooks into Solid Queue’s event system using ActiveSupport::Notifications — no changes to your job classes required.

Sidekiq Pro / Enterprise

No additional configuration is needed for Sidekiq Pro or Enterprise. The middleware integrates at the standard server middleware layer and works with all Sidekiq editions.

For Sidekiq Batches, job-level events are tracked individually within a batch. Batch completion is not tracked as a separate event — each constituent job fires its own success or failure event.

---

Configuration

Sidekiq

TraceStax::Sidekiq.configure do |config|
  config.api_key    = ENV["TRACESTAX_API_KEY"]  # Required
  config.enabled    = !Rails.env.test?
  config.dry_run    = false
  config.ingest_url = "https://ingest.tracestax.com"
end

Option	Env var	Default	Description
api_key	TRACESTAX_API_KEY	—	Required
enabled	TRACESTAX_ENABLED	true	Set to false in tests
dry_run	TRACESTAX_DRY_RUN	false	Log events instead of sending
ingest_url	TRACESTAX_INGEST_URL	https://ingest.tracestax.com	Custom endpoint

Solid Queue

TraceStax.configure do |config|
  config.api_key    = ENV["TRACESTAX_API_KEY"]  # Required
  config.enabled    = !Rails.env.test?
  config.ingest_url = "https://ingest.tracestax.com"
end

---

Cron jobs (Sidekiq-Cron / Sidekiq Scheduler)

Periodic jobs scheduled via sidekiq-cron or sidekiq-scheduler are tracked automatically — the middleware fires for every execution. The scheduled: true flag is set on events from jobs that appear in the cron schedule.

---

Testing

# spec/rails_helper.rb or test/test_helper.rb
ENV["TRACESTAX_ENABLED"] = "false"

Or disable via configuration:

TraceStax::Sidekiq.configure { |c| c.enabled = false }

---

Troubleshooting

Events not appearing

The middleware fires synchronously on the server side. Confirm that:

• TRACESTAX_API_KEY is present in the Sidekiq process environment (not just the web process)
• The Sidekiq process can reach ingest.tracestax.com:443
• TraceStax logs a [TraceStax] warning line if ingest calls fail — check sidekiq.log

Concurrency impact

Ingest calls are made from a background thread with connection pooling via Faraday. They add < 1ms to job overhead in typical deployments.