← BackRuby

Ruby

Complete integration guide for ImmutableLog in Ruby. Automatic middleware for Rails (Rack) and Sinatra — or a direct Net::HTTP client for Sidekiq workers, rake tasks, and scripts. Sending runs in a fire-and-forget Thread.

Middlewares

Automatic integration via middleware — every HTTP request is captured without modifying any controller. Click the framework to see the complete code.

RailsRack

Rack middleware inserted via config.middleware. Captures the status from @app.call(env) and sends in a Thread.

ruby

def call(env)
  started = now
  status, headers, body = @app.call(env)
  Thread.new { emit(env, status, latency(started)) }
  [status, headers, body]
end

View full documentation →

Sinatrabefore / after

before/after filters + error block. Reuses the ImmutableLog client and sends the event in a fire-and-forget Thread.

ruby

after do
  Thread.new do
    settings.imtbl.send_event(
      event_name: @imtbl_event_name, kind: kind, payload: payload)
  end
end

View full documentation →

Direct HTTP client (Net::HTTP)

Use the ImmutableLog class to send events directly without depending on a web framework. Ideal for Sidekiq workers, rake tasks, and any Ruby script that needs to record events. No dependencies beyond stdlib.

ruby

# lib/immutable_log.rb
require "net/http"
require "json"
require "securerandom"
require "time"
require "uri"

class ImmutableLog
  def initialize(api_key:, service: "ruby-service", env: "production", api_url: nil)
    @api_key = api_key
    @service = service
    @env = env
    @api_url = api_url || ENV.fetch("IMTBL_URL", "https://api.immutablelog.com")
  end

  def send_event(event_name:, kind:, payload:, immutable_trail: nil)
    request_id = SecureRandom.uuid
    trail = self.class.sanitize_trail(immutable_trail)

    # Todos os valores de meta precisam ser strings.
    meta = {
      "type" => kind,
      "event_name" => event_name,
      "service" => @service,
      "request_id" => request_id,
      "env" => @env,
    }
    meta["immutable_trail"] = trail if trail

    body = {
      "payload" => JSON.generate(payload.merge("timestamp" => Time.now.utc.iso8601)),
      "meta" => meta,
    }

    uri = URI.join(@api_url, "/v1/events")
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = uri.scheme == "https"
    http.open_timeout = 5
    http.read_timeout = 5

    req = Net::HTTP::Post.new(uri)
    req["Authorization"] = "Bearer #{@api_key}"
    req["Content-Type"] = "application/json"
    # Idempotency-Key e OBRIGATORIO (sem ele a API responde 400).
    req["Idempotency-Key"] = "#{event_name}-#{request_id}"
    req["Request-Id"] = request_id
    req["X-Client-TZ"] = "America/Sao_Paulo"
    req["X-Client-Offset-Minutes"] = "-180"
    req["X-Imtbl-Trail"] = trail if trail
    req.body = JSON.generate(body)

    http.request(req)
  end

  # Normaliza o immutable_trail (trim, nao-vazio, max 256, sem ':').
  # O servidor responde 400 invalid_immutable_trail se a regra for violada.
  def self.sanitize_trail(value)
    return nil unless value.is_a?(String)
    v = value.strip
    return nil if v.empty?
    v = v.tr(":", "-")
    v = v[0, 256] if v.length > 256
    v
  end
end

# Uso (fire-and-forget via Thread):
log = ImmutableLog.new(api_key: ENV["IMTBL_API_KEY"], service: "payments-service")
Thread.new do
  log.send_event(
    event_name: "payment.approved", kind: "success",
    payload: { "payment_id" => "pay_abc123", "amount" => 299.90 },
    immutable_trail: "order-7782",
  )
end

To avoid blocking the request, wrap send_event in a Thread (fire-and-forget) or dispatch it to a Sidekiq/ActiveJob worker.

Retry with exponential backoff

For high-availability production, add retry with exponential backoff. ImmutableLog returns 202 on success and 200 on an idempotent duplicate — never retry on 429 (monthly limit reached).

ruby

def send_with_retry(event_name:, kind:, payload:, immutable_trail: nil, max_attempts: 3)
  delay = 0.5

  max_attempts.times do |attempt|
    res = send_event(event_name: event_name, kind: kind,
                     payload: payload, immutable_trail: immutable_trail)
    code = res.code.to_i
    return res if code < 400

    # 429 = limite mensal — nao fazer retry.
    return res if code == 429

    if attempt + 1 < max_attempts
      sleep(delay)
      delay *= 2 # 0.5s -> 1s -> 2s
    end
  end
  nil
rescue StandardError
  nil
end

Sensitive data hashing

Never send raw personal data (email, CPF, IP) to ImmutableLog. Use SHA-256 to generate a deterministic digest — traceable without exposing the original data.

ruby

require "digest"

# Faz o hash de dados sensiveis antes de enviar — nunca logue PII bruto.
def sha256_hex(data)
  Digest::SHA256.hexdigest(data)
end

# Uso no payload do evento:
payload = {
  "user_id"    => "usr_123",
  "email_hash" => sha256_hex("user@example.com"),
  "ip_hash"    => sha256_hex("192.168.1.1"),
}

This documentation reflects the current API behavior. For questions or advanced integrations, contact the support team.