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 and deployment endpoints
Ruby app with BundlerLets you install and configure logister-ruby
Optional GitHub App installationLets Logister use repository, commit_sha, branch, and deployment records for source excerpts and deploy links

What you get

Use the Ruby integration to start with errors, then add performance and deploy 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, source, 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.
Resolve source and deploy historyrepository, commit_sha, branch, release, and deployment records that let Logister show source excerpts, GitHub links, and "started after deploy" context when the GitHub App is connected.
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, Logister ingest endpoint, environment, release, and source context.
  4. Optionally enable DB metrics for performance visibility.
  5. From CI/CD, call Logister.record_deployment after a successful deploy so releases map to exact commits.

Tip

If you only want error capture at first, ship the base config first and add source context, deployment records, and database metrics next.

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, check-ins, and deployment records 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.8"
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.repository = ENV["LOGISTER_REPOSITORY"] || ENV["GITHUB_REPOSITORY"]
  config.commit_sha = ENV["LOGISTER_COMMIT_SHA"] || ENV["GITHUB_SHA"]
  config.branch = ENV["LOGISTER_BRANCH"] || ENV["GITHUB_REF_NAME"]
  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.

Source and deployments

Record the deployed commit when CI/CD knows it.

If the project is connected to the GitHub App, Logister can use source context to resolve Ruby and Rails stack frames to repository files. Deployment records tell Logister which commit was deployed for a release and environment.

ruby
Logister.record_deployment(
  release: ENV.fetch("LOGISTER_RELEASE"),
  environment: ENV.fetch("LOGISTER_ENVIRONMENT", Rails.env),
  repository: ENV.fetch("LOGISTER_REPOSITORY", "acme/checkout"),
  commit_sha: ENV.fetch("LOGISTER_COMMIT_SHA", ENV["GITHUB_SHA"]),
  branch: ENV["LOGISTER_BRANCH"] || ENV["GITHUB_REF_NAME"],
  deployed_at: Time.now.utc.iso8601,
  release_tag: ENV["GITHUB_REF_NAME"],
  workflow_run_url: ENV["GITHUB_RUN_ID"] && "https://github.com/#{ENV["GITHUB_REPOSITORY"]}/actions/runs/#{ENV["GITHUB_RUN_ID"]}"
)
FieldSet it fromUsed for
repositoryLOGISTER_REPOSITORY or GITHUB_REPOSITORYFinds the GitHub repository connected to the project.
commit_shaLOGISTER_COMMIT_SHA or GITHUB_SHAResolves stack frames and deployment context to the exact commit.
branchLOGISTER_BRANCH or GITHUB_REF_NAMEFalls back when an event has no commit or deployment record yet.
releaseYour app version, build ID, tag, or package versionConnects event filters, release health, and deployments.

config.deployment_endpoint defaults to the configured ingest endpoint with /ingest_events replaced by /deployments. Set LOGISTER_DEPLOYMENT_ENDPOINT only when that endpoint cannot be derived from LOGISTER_ENDPOINT.

Verify it

After a deploy, send one test exception with the same release. Open the event detail and check for source lookup status, deployment context, and GitHub links. If source is missing, confirm the GitHub App is installed for the repository and that the event has repository plus either commit_sha or a matching deployment record.

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
source context visible on events when configured
deployment context visible after Logister.record_deployment runs
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.