LogTide Ruby SDK

Official Ruby SDK for LogTide — self-hosted log management with distributed tracing, error capture, breadcrumbs, and Rack/Rails middleware.

---

Features

• Leveled logging — debug, info, warn, error, critical, plus capture_exception
• Structured exception capture with cause chains and stack frames
• Hub / Scope model — per-request isolation with tags, user, breadcrumbs, and trace context
• Automatic batching with configurable size and interval
• Retry with backoff — exponential backoff with jitter; honours Retry-After
• Circuit breaker to prevent cascading failures
• Bounded buffer with a drop policy to cap memory; flush/close and a best-effort exit hook
• W3C traceparent inbound and outbound propagation
• Spans + OTLP export with log/trace correlation and sampling
• before_send hook and log/trace sampling
• Rack middleware + Rails Railtie
• stdlib Logger bridge
• Self-metrics (logs_sent, logs_dropped, errors, retries, circuit_breaker_trips)
• Standard library only — no runtime dependencies
• Thread-safe

Implements the LogTide SDK spec v1.0.

Requirements

• Ruby 3.1 or later
• A LogTide instance and DSN

Installation

# Gemfile
gem "logtide"

bundle install

Quick start

require "logtide"

Logtide.init(
  dsn: "https://lp_your_key@logs.example.com",
  service: "checkout",
  environment: "production"
)

Logtide.info("order placed", { order_id: 42 })

begin
  charge_card!
rescue => e
  Logtide.capture_exception(e)
end

Logtide.flush

Configuration also accepts explicit endpoint options:

Logtide.init(api_url: "https://logs.example.com", api_key: "lp_your_key", service: "checkout")

Scope, tags and breadcrumbs

Logtide.configure_scope do |scope|
  scope.set_user(id: "u_123", email: "alice@example.com")
  scope.set_tag("region", "eu")
end

Logtide.add_breadcrumb(Logtide::Breadcrumb.new(type: "query", message: "SELECT * FROM carts"))

Logtide.with_scope do |scope|
  scope.set_tag("step", "payment")
  Logtide.error("payment failed")
end

Rails

The Railtie installs the Rack middleware automatically. Initialise the SDK in an initializer:

# config/initializers/logtide.rb
Logtide.init(dsn: ENV["LOGTIDE_DSN"], service: "my-app", release: ENV["GIT_SHA"])

Plain Rack

use Logtide::Rack::Middleware

stdlib Logger bridge

logger = Logtide::LoggerBridge.new
logger.warn("disk almost full")   # delivered as a LogTide entry with scope context

Tracing

Logtide.start_span("checkout", kind: :server) do |span|
  span.set_attribute("cart.size", 3)
  Logtide.info("processing") # carries the span's trace_id/span_id
end

# Propagate the trace to a downstream service:
headers = Logtide.trace_propagation_headers # { "traceparent" => "00-..." }

Configuration options

Defaults follow the spec exactly (durations in seconds):

Option	Default
environment	"production"
batch_size	100
flush_interval	5
max_buffer_size	10_000
max_retries	3
retry_delay	1
circuit_breaker_threshold	5
circuit_breaker_reset	30
flush_timeout	10
max_breadcrumbs	100
sample_rate	1.0
traces_sample_rate	1.0
attach_stacktrace	true
send_default_pii	false
debug	false

Development

bundle install
bundle exec rspec
bundle exec rubocop

License

MIT