LogisterDocumentationRuby integration
Documentation / Ruby

Integrate a Ruby app or Rails service with Logister.

The best path for Ruby projects is the published RubyGems package logister-ruby. It is the Ruby-specific install path for sending errors, logs, metrics, transactions, spans, and check-ins into Logister.

Before you start

Create the project with the Ruby integration type.

What you needWhy it matters
Project API tokenAuthenticates your app when sending events
Logister instance base URLUsed to build the ingest endpoint
Ruby app with BundlerLets you install and configure logister-ruby

What you get

Use the Ruby integration to start with errors, then add performance signals.

NeedWhat appears in Logister
See Ruby and Rails failures in one placeError groups in the project inbox with stacktrace details, request context, occurrence history, and triage actions.
Find repeated problemsGrouped issues based on fingerprints or consistent messages, with first-seen and last-seen history.
Capture useful manual errorsManual Logister.report_error calls include runtime, deployment, breadcrumb, dependency, user, and nested exception cause context.
Understand request loadOptional Rails request spans that feed request load waterfall charts on the performance page.
Understand database pressuredb.query metric events that power database load cards on the performance page when database metrics are enabled.
Track deploy contextEnvironment and release metadata that helps release health and regression tracking become useful.
Watch custom operationsLogs, metrics with value/unit context, transactions, spans, and check-ins in activity, performance, and monitor views.

Setup flow

Recommended installation path

  1. Create the project and generate an API key.
  2. Add logister-ruby to the application.
  3. Configure the API key and Logister ingest endpoint.
  4. Optionally enable DB metrics for performance visibility.

Tip

If you only want error capture at first, ship the base config first and add database metrics later.

Install

Install logister-ruby from RubyGems.

Use the published package when you want a Ruby app or Rails service to send errors, logs, metrics, transactions, spans, and check-ins into Logister through Bundler or RubyGems. The RubyGems listing is the canonical package page for install commands, version history, and package metadata.

ruby
gem "logister-ruby", "~> 0.2.6"
shell
bundle install
gem install logister-ruby

Package links: RubyGems and GitHub.

Configure

Point the gem at your Logister project.

shell
mkdir -p config/initializers
ruby
Logister.configure do |config|
  config.api_key = ENV.fetch("LOGISTER_API_KEY")
  config.endpoint = ENV.fetch("LOGISTER_ENDPOINT")
  config.environment = Rails.env
  config.release = ENV["LOGISTER_RELEASE"]
  config.capture_request_spans = true
end

The endpoint should be your Logister instance base URL plus /api/v1/ingest_events. The ingest endpoint accepts 1,200 requests per minute per API token by default and returns 429 Too Many Requests with retry headers when that limit is exceeded.

Important

The API token is only shown once in project settings. Store it in your environment or secret manager before you navigate away.

Metrics

Enable DB timing metrics when needed.

ruby
Logister.configure do |config|
  config.capture_db_metrics = true
  config.db_metric_min_duration_ms = 10.0
  config.db_metric_sample_rate = 1.0
end
SettingPurpose
capture_db_metricsTurns database timing capture on
db_metric_min_duration_msFilters out very fast queries
db_metric_sample_rateControls how much query traffic is reported

Manual metrics and check-ins

ruby
Logister.report_metric(
  message: "queue.depth",
  value: 12,
  unit: "jobs",
  context: { queue: "emails" }
)

Logister.report_check_in(
  slug: "nightly-reconcile",
  status: "ok",
  expected_interval_seconds: 900,
  duration_ms: 248.3,
  release: ENV["LOGISTER_RELEASE"],
  trace_id: "trace-123",
  request_id: "req-123"
)
Verification
Performance page checklist
transactions visible
db.query samples flowing
request spans visible
no missing API token errors

Useful examples

Add the context that makes Ruby events easier to triage.

Attach breadcrumbs and dependency calls before an error

ruby
Logister.add_breadcrumb(
  category: "checkout",
  message: "Starting payment authorization",
  data: { order_id: 123 }
)

Logister.add_dependency(
  name: "stripe.charge",
  host: "api.stripe.com",
  method: "POST",
  status: 200,
  duration_ms: 184.7,
  kind: "http"
)

Report worker spans and a transaction

ruby
trace_id = SecureRandom.hex(16)
root_span_id = SecureRandom.hex(8)

Logister.report_transaction(
  name: "billing.reconcile",
  duration_ms: 1840.7,
  context: { trace_id: trace_id, queue: "billing", service: "billing-worker" }
)

Logister.report_span(
  name: "billing.reconcile",
  duration_ms: 1840.7,
  trace_id: trace_id,
  span_id: root_span_id,
  kind: "server",
  status: "ok",
  context: { queue: "billing" }
)

Logister.report_span(
  name: "load invoices",
  duration_ms: 430.2,
  trace_id: trace_id,
  parent_span_id: root_span_id,
  kind: "db",
  status: "ok",
  context: { queue: "billing" }
)

Use breadcrumbs for the steps leading to an exception, dependency calls for outbound services, transactions for total work duration, and spans for the pieces of that work that should appear in request load waterfall charts.