Integrate a Ruby app or Rails service with Logister.

Before you start

Create the project with the Ruby integration type.

What you get

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

Setup flow

Recommended installation path

1. Create the project. Logister opens its setup path at the API key step; create the key there.
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.

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.

gem "logister-ruby", "~> 0.6.0"

bundle install
gem install logister-ruby

Package links: RubyGems and GitHub.

Upgrading

Upgrading to 0.6.0: review the changed defaults.

Version 0.6.0 changes what the gem captures and how it delivers events. Review each row before you update the gem in an application, then use the linked section for the exact option.

The full list of changes is in the changelog.

Configure

Point the gem at your Logister project.

mkdir -p config/initializers

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. Use HTTPS: the client logs a warning when an endpoint uses http:// on a host other than localhost or a loopback address. Calling Logister.configure again replaces the reporter; the previous client drains what it already queued and stops.

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.

Inspect delivery outcomes.

The Ruby SDK provides Logister.delivery_stats and config.delivery_observer. Counters distinguish queued, acknowledged, unconfirmed, queue-full and retry outcomes. Observer callbacks contain counts and safe reason codes, never event payloads. Send them to an independent log sink to avoid feedback loops. A successful flush only means pending work drained; it does not prove delivery. Async shutdown waits at most one second and returns false if the worker is still active.

See the SDK README for the complete contract.

Event limits

Bound event size and synchronous retries.

Each event is sanitized and serialized on its own before it is batched, so an event that is too large or cannot be serialized is dropped alone and the rest of its batch is still sent.

Invalid UTF-8 is replaced and NaN/Infinity become strings. When anything is cut, logister_truncated: true is added to the context. An event still larger than max_event_bytes after a second, tighter pass is dropped and counted as unconfirmed with reason event_too_large. An event that cannot be serialized is dropped with reason serialization_error.

Logister.configure do |config|
  config.max_event_bytes = 262_144
  config.max_retries = 3
  config.sync_max_retries = 1
end

Synchronous delivery retries

With config.async = false, delivery runs on the caller's thread, so it uses sync_max_retries (default 1, never more than max_retries) and caps each wait at one second. Deployment records are always sent this way. Asynchronous delivery keeps the max_retries budget.

Only transport failures are retried: timeouts, IOError, SocketError, OpenSSL::SSL::SSLError, Errno::*, and HTTP 408, 425, 429, or 5xx responses. Any other error fails the attempt once.

Privacy defaults

Know what the gem redacts before an event is sent.

Every event is redacted in the client before it is serialized, using the default redaction rules shared by all Logister SDKs. Matching values are replaced with [REDACTED].

Redaction covers the message and the whole context: request URL, referer, headers, params, user context, tags, breadcrumbs, dependency calls, job arguments (after Rails filter_parameters), span attributes, log fields, and exception data. Envelope fields such as uuid, event_type, trace_id, span_id, parent_span_id, request_id, and session_id are never redacted. The full list of sensitive key names is in the SDK README.

Add project-specific keys

Add keys with config.redact_keys. Entries are normalized the same way and must match a key exactly.

Logister.configure do |config|
  config.redact_keys = ["tenant_ref", "X-Internal-Signature"]
end

Request headers

Request headers are captured from an allowlist: Accept, Accept-Encoding, Accept-Language, Cache-Control, Content-Length, Content-Type, Dnt, Host, Origin, Referer, User-Agent, Via, W3C, B3, Datadog, and AWS trace headers, X-Request-Id, X-Forwarded-For/Host/Proto/Port, X-Real-Ip, and Sec-Fetch-*/Sec-Ch-Ua* hints. Other headers are not sent.

Add headers with config.capture_headers. The sensitive-key rule still applies, so an added header such as X-Auth-Token is captured as [REDACTED].

Logister.configure do |config|
  config.capture_headers = ["X-Tenant"]
  config.anonymize_ip = true
end

With config.anonymize_ip = true, the client IP and every address in X-Forwarded-For and X-Real-Ip are truncated (/24 for IPv4, /64 for IPv6).

Logister.report_error(
  RuntimeError.new("Redaction test error"),
  context: { password: "example", tenant_ref: "example" },
  fingerprint: "redaction-test-error"
)
Logister.flush

User context

Attach the signed-in user to the current request or job.

Errors reported during the current request or job include the user you set with Logister.set_user. User context is redacted with the same rules as the rest of the event.

Logister.set_user(id: current_user.id, email: current_user.email, name: current_user.name)
Logister.clear_user

The user is stored in the request scope. The Rack middleware and the Active Job integration reset that scope when each request or job ends, so identity does not carry over to the next request on a reused Puma or Sidekiq thread. In other long-lived threads, call Logister.clear_user when the unit of work ends.

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.

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

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.

Metrics

Enable DB timing metrics when needed.

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

Each sample is a metric event with message: "db.query" and context fields such as duration_ms, name, sql, and binds_count. String and numeric literals are replaced with ? in the captured sql; bind placeholders like $1 and quoted identifiers are kept.

Manual metrics and check-ins

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

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

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

SQL breadcrumbs

Rails request breadcrumbs are captured automatically. SQL breadcrumbs are off by default (capture_sql_breadcrumbs = false) because adapters without prepared statements inline literal values. Turn them on to record queries slower than sql_breadcrumb_min_duration_ms; string and numeric literals are replaced with ?.

Logister.configure do |config|
  config.capture_sql_breadcrumbs = true
  config.sql_breadcrumb_min_duration_ms = 25.0
end

Report worker spans and a transaction

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.

Follow requests between projects

Logister 3.7 adds explicit project connections and request-identifier evidence. See request correlation setup for the required SDK versions, origin allowlists, permissions, and verification.