e-volv-logs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a038bda7b8de408b1355408bddc11c2a15d131bffb1079c79ae8234507495af8
+  data.tar.gz: bae9886d0cf9622f5cd7dcbdc85aa9465411ebd2a6569eeae0911e5ae0e88fe0
+SHA512:
+  metadata.gz: 829a85718b9ca629f29df44bf4e6bfe362a17f674419322b75f6aaf1e643f03cff93bc59936a2353c91bb8badb95ca008614acab1e0010bea644f00a5bf3554a
+  data.tar.gz: 9858b58c19c56ec8013c8e633532932d084b735b49165a661ba7796804d5ae39c746a25ef3c082d53744b1e2b03e967a8af5e97b6f4537288a6b51bd50b113a6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 e-volv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# e-volv-logs (Ruby)
+
+e-volv Observer SDK for Ruby — batched log shipping, trace context and error
+capture against the e-volv ingest endpoint (`POST /api/public/v1/logs`).
+Companions: the Node.js SDK `@e-volv/logs`, the Python SDK `e-volv-logs` and
+the Go SDK `e-volv-logs-go`. All four speak one wire contract
+(`docs/OBSERVER-SDK.md`).
+
+Ruby 2.6+. Standard library only — no runtime dependencies. `rack` and
+`faraday` are soft, duck-typed integrations; nothing is monkeypatched.
+
+## Quick start
+
+```bash
+gem install e-volv-logs
+```
+
+```ruby
+require "evolve_logs"
+
+EvolveLogs.init(
+  key: ENV["EVOLVE_LOGS_KEY"], # project ingest key
+  url: "https://api.e-volv.io/api/public/v1/logs",
+  service: "orders-api",
+  environment: ENV["RACK_ENV"],
+  release: ENV["GIT_SHA"]
+)
+
+EvolveLogs.info("order created", { "orderId" => "o_1", "total" => 42.5 })
+EvolveLogs.error("payment failed", { "orderId" => "o_1" })
+
+begin
+  charge
+rescue StandardError => err
+  EvolveLogs.exception(err, { "orderId" => "o_1" }) # exception.type/message/stack
+end
+```
+
+If `key` or `url` is empty, `init` returns a no-op client and warns once on
+stderr. The SDK never raises into your code.
+
+Use `EvolveLogs::Client.new(...)` for a non-default client; module-level
+helpers (`EvolveLogs.info`, `EvolveLogs.span`, `EvolveLogs.flush`, …)
+delegate to the client installed by `EvolveLogs.init`.
+
+## Traces and spans
+
+Trace context lives in `Thread.current` (fiber-local): it flows into fibers
+under the current thread and never leaks across threads.
+
+```ruby
+EvolveLogs.span("db.query", { "table" => "orders" }) do
+  db.query("SELECT …")
+end # an exception inside ends the span as failed and is re-raised
+```
+
+The span end is recorded as an event with `span.name` and `durationMs`
+attributes; the span's trace and span ids ride on the event.
+`EvolveLogs.traceparent` returns the W3C `00-<traceId>-<spanId>-01` header,
+or `nil` outside a trace.
+
+### Rack / Rails
+
+```ruby
+# config.ru — one root span per request; an inbound traceparent is continued
+use EvolveLogs::RackMiddleware
+```
+
+```ruby
+# config/application.rb — every Rails.logger line also ships to Observer;
+# Rails.logger.error(err) carries exception.*
+config.logger = EvolveLogs::Logger.new($stdout)
+```
+
+An app that raises ends the `http.request` span as failed and is re-raised,
+so the server crashes exactly as it would without the SDK.
+
+### Queue hops (ActiveJob, Sidekiq)
+
+Send `EvolveLogs.traceparent` with the job; in the worker, wrap the body:
+
+```ruby
+# producer
+MyJob.perform_later(args, traceparent: EvolveLogs.traceparent)
+
+# consumer
+EvolveLogs::ActiveJob.perform(
+  EvolveLogs::ActiveJob.traceparent_in(arguments),
+  self.class.name
+) do
+  # one trace with the producer
+end
+```
+
+`EvolveLogs::Sidekiq.perform(traceparent, worker, attrs) { … }` is the
+Sidekiq shape; `EvolveLogs::Carriers.wrap(header, span_name, attrs) { … }`
+covers anything else. For raw headers,
+`EvolveLogs.run_with_traceparent(header) { … }` runs the block with the next
+hop of that trace — an absent or malformed header starts a fresh trace.
+
+### Outbound HTTP (Net::HTTP, Faraday)
+
+Monkeypatch-free — opt in per call site:
+
+```ruby
+request = Net::HTTP::Post.new(uri)
+EvolveLogs::HTTP.inject_traceparent(request) # never overwrites an existing header
+http.request(request)
+```
+
+```ruby
+conn = Faraday.new(url: "https://internal") do |builder|
+  builder.use EvolveLogs::FaradayMiddleware
+  builder.adapter Faraday.default_adapter
+end
+```
+
+## Errors
+
+`EvolveLogs.exception(err, attrs)` sends severity 17 with `err.message` as
+the message and `exception.type` (the class name), `exception.message` and
+`exception.stack` (`err.backtrace`) as attributes — an error occurrence with
+a stack on the group page. A failed `span` records `exception.type` and
+`exception.message` without a stack.
+
+## Batching, retries, drops
+
+- Flushes at **200 events**, every **2 s**, or a **512 KB** payload —
+  whichever comes first. Bodies are always gzipped (`Content-Encoding: gzip`).
+- **429** honours `Retry-After`, otherwise exponential backoff (500 ms
+  doubling, capped at 10 s), up to 3 attempts. **413** halves the batch; the
+  excess half is dropped and counted.
+- When the pending buffer exceeds **2× batch size**, the **oldest** events
+  are dropped; losses are visible on `client.dropped`.
+- `EvolveLogs.flush` sends what is pending; it is safe to call repeatedly
+  (also from an `at_exit` hook, which the SDK installs itself).
+
+## Redaction and sampling
+
+Attribute keys matching `password|secret|token|authorization|cookie|set-cookie|api[-_]?key`
+(case-insensitive substring, recursing into nested hashes and arrays) are
+replaced with `[redacted]` before enqueue; `redact_keys:` extends the list.
+`sample_rate:` (0–1) randomly drops events below 1.
+
+Every event carries `service.name`, `deployment.environment` and
+`service.release` from `init`.
+
+## Feature flags (e-volv Launch)
+
+Evaluate e-volv Launch flags locally, in-process, on the same key as
+telemetry:
+
+```ruby
+EvolveLogs.init(
+  key: ENV["EVOLVE_LOGS_KEY"],
+  url: "https://api.e-volv.io/api/public/v1/logs",
+  flags: { mode: "stream" } # optional; see the options table below
+)
+
+EvolveLogs.flags.bool("checkout.new", false, { "targetingKey" => "u_1", "plan" => "pro" })
+EvolveLogs.flags.string("banner.copy", "Hello")
+EvolveLogs.flags.number("limits.maxItems", 10)
+EvolveLogs.flags.json("theme.config", {})
+EvolveLogs.flags.detail("checkout.new", false, ctx) # Evaluation(value, variant, reason)
+
+EvolveLogs.flags.ready(timeout: 5)     # the only call that waits
+EvolveLogs.flags.on_change { |keys| }  # returns an unsubscribe proc
+EvolveLogs.flags.last_updated_at       # epoch seconds, nil before the first payload
+EvolveLogs.flags.verify                # install check against GET /ping
+```
+
+Flag options (Ruby spellings of the Launch contract, §4) — an
+`EvolveLogs::Flags::Options` or a Hash with the same keys:
+
+| Option                  | Default    | Meaning                                         |
+| ----------------------- | ---------- | ----------------------------------------------- |
+| `enabled`               | `true`     | start the flags client                          |
+| `mode`                  | `"stream"` | `stream` \| `poll` \| `offline`                 |
+| `poll_interval_seconds` | `30`       | poll period; minimum 15                         |
+| `cache`                 | temp dir   | last-known-payload dir; `false` disables        |
+| `bootstrap`             | none       | a bundled ruleset served before the first fetch |
+| `exposures`             | see below  | a Hash of exposure options (§7)                 |
+| `private_attributes`    | `[]`       | attribute names never sent anywhere             |
+
+`exposures` carries `enabled` (default `true`), `sample_rate` (`1.0`),
+`dedupe_window_seconds` (`60`) and `send_attributes` (`false`).
+
+Guarantees (the e-volv Launch SDK contract):
+
+- Evaluation is **synchronous, never raises, never performs I/O** — every
+  call answers from the last-held ruleset or your default.
+- Wrong type → your default with reason `TYPE_MISMATCH`.
+- Absent flag → your default with reason `FLAG_NOT_FOUND`.
+- The control plane unreachable → last held value; a cold start serves a
+  valid cache file instantly while fetching in the background.
+- Flag delivery runs on its own `e-volv-flags` thread (a held-open stream
+  would stall log flushing) and survives `fork` — the threads relaunch on
+  the first evaluation in a forked child (Puma, Unicorn, Resque, Sidekiq).
+- Server keys never send `Origin` or `x-evolve-app-id`; requests carry
+  `User-Agent: e-volv-logs-ruby/<version>`.
+- Flag evaluation is byte-for-byte identical to every other e-volv SDK: the
+  Ruby kernel is a port held to `packages/flags-kernel/fixture.json`.
+
+## Conformance
+
+```bash
+npx tsx packages/logs-conformance/run.ts packages/logs-conformance/fixture.json -- \
+  ruby packages/logs-ruby/conformance_runner.rb
+```
+
+Replays the shared fixture (`packages/logs-conformance/fixture.json`) through
+this runner against a stub ingest — the same gate every SDK runs, pinning the
+wire contract. See `packages/logs-conformance/runner-protocol.md`.
+
+The Launch flags gates:
+
+```bash
+ruby packages/logs-ruby/flags_kernel_runner.rb packages/flags-kernel/fixture.json
+npx tsx packages/flags-conformance/run.ts server -- ruby packages/logs-ruby/flags_delivery_runner.rb
+```
+
+## Development
+
+```bash
+cd packages/logs-ruby
+ruby -Ilib -Itests tests/all.rb
+```
+
+No bundler install is required — the tests use minitest, which ships with
+Ruby.

data/lib/evolve_logs/carriers.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  # Queue carriers. Every queue speaks strings, so the producer captures
+  # EvolveLogs.traceparent when enqueuing and the consumer wraps the job body
+  # in the matching helper:
+  #
+  #     # producer
+  #     MyJob.perform_later(args, traceparent: EvolveLogs.traceparent)
+  #
+  #     # consumer (ActiveJob)
+  #     EvolveLogs::ActiveJob.perform(traceparent, self.class.name) do
+  #       # job body — one trace with the producer
+  #     end
+  module Carriers
+    # wrap continues `traceparent` (a W3C header captured at enqueue time)
+    # and opens a span around the block. An absent or malformed header
+    # starts a fresh trace, so a producer that sends nothing still yields a
+    # trace of its own.
+    def self.wrap(traceparent, span_name = "queue.job", attrs = nil, &block)
+      EvolveLogs.run_with_traceparent(traceparent) do
+        EvolveLogs.span(span_name, attrs, &block)
+      end
+    end
+  end
+
+  # ActiveJob carrier: wrap the perform body with the traceparent stored in
+  # the job's serialized arguments.
+  module ActiveJob
+    def self.perform(traceparent, job_class, attrs = nil, &block)
+      merged = { "job.class" => job_class.to_s }
+      (attrs || {}).each { |k, v| merged[k] = v }
+      Carriers.wrap(traceparent, "queue.active_job", merged, &block)
+    end
+
+    # traceparent_in reads the traceparent a producer stored as the last
+    # serialized job argument, e.g. MyJob.perform_later(args,
+    # traceparent: EvolveLogs.traceparent).
+    def self.traceparent_in(arguments)
+      last = Array(arguments).last
+      last["traceparent"] if last.is_a?(Hash)
+    end
+  end
+
+  # Sidekiq carrier: wrap the perform body with the traceparent carried in
+  # the job payload.
+  module Sidekiq
+    def self.perform(traceparent, worker, attrs = nil, &block)
+      merged = { "worker" => worker.to_s }
+      (attrs || {}).each { |k, v| merged[k] = v }
+      Carriers.wrap(traceparent, "queue.sidekiq", merged, &block)
+    end
+
+    # traceparent_in reads the traceparent from a Sidekiq job hash
+    # ({ "traceparent" => ... } in the payload).
+    def self.traceparent_in(job)
+      job["traceparent"] if job.is_a?(Hash)
+    end
+  end
+end

data/lib/evolve_logs/client.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  # Client batches and delivers events. Construct one directly for a
+  # non-default instance, or through EvolveLogs.init for the module-level
+  # default. With an empty key or url the client is a no-op and warns once on
+  # stderr (unless silent: true). All public methods are safe for concurrent
+  # use and never raise.
+  class Client
+    attr_reader :key, :url, :service, :environment, :release, :sample_rate, :flags
+
+    def initialize(key: nil, url: nil, service: nil, environment: nil,
+                   release: nil, redact_keys: nil, sample_rate: 1.0,
+                   transport: nil, background: true, silent: false, flags: nil)
+      @key = key
+      @url = url
+      @service = service
+      @environment = environment
+      @release = release
+      @sample_rate = clamp_sample_rate(sample_rate)
+      @redact = Redactor.new(redact_keys)
+      @transport = transport || method(:net_http_deliver)
+      @enabled = present?(@key) && present?(@url)
+      @mutex = Mutex.new
+      @flush_mutex = Mutex.new
+      @buffer = []
+      @buffered_bytes = 0
+      @dropped = 0
+      @stop = false
+      @flusher = nil
+      # Flags bind to the same key and run delivery on their own thread, so
+      # a held-open stream never stalls log flushing. Built before the
+      # `enabled` early path: flags work without an ingest url.
+      flags_options = Flags::Options.build(flags)
+      @flags = key.to_s.empty? || flags_options.enabled == false ?
+        Flags::Disabled.new :
+        Flags::Client.new(key, flags_options, observer_url: url, post_json: method(:post_json))
+      @flags.start
+      if @enabled
+        Registry.register(self)
+        @flusher = Thread.new { flusher_loop } if background
+      elsif !silent
+        # Kernel#warn, not Client#warn — this is the one-time stderr notice.
+        Kernel.warn "e-volv-logs: init without key and url — the client is a no-op."
+      end
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    # dropped returns the number of events dropped: evicted past the pending
+    # buffer cap (2× the batch size, oldest first) or abandoned after
+    # retries. Visible so buffer losses are never silent.
+    def dropped
+      @mutex.synchronize { @dropped }
+    end
+
+    # ------------------------------------------------------------------ logging
+
+    # log enqueues an event at the given OTel severity number.
+    def log(severity, message, attrs = nil)
+      enqueue(severity, message, attrs, nil)
+    rescue StandardError
+      nil
+    end
+
+    def trace(message, attrs = nil)
+      log(OTEL_TRACE, message, attrs)
+    end
+
+    def debug(message, attrs = nil)
+      log(OTEL_DEBUG, message, attrs)
+    end
+
+    def info(message, attrs = nil)
+      log(OTEL_INFO, message, attrs)
+    end
+
+    def warn(message, attrs = nil)
+      log(OTEL_WARN, message, attrs)
+    end
+
+    def error(message, attrs = nil)
+      log(OTEL_ERROR, message, attrs)
+    end
+
+    def fatal(message, attrs = nil)
+      log(OTEL_FATAL, message, attrs)
+    end
+
+    # exception logs err as an error event: severity 17, err.message as the
+    # message, and exception.type (the class name), exception.message and
+    # exception.stack attributes — an error occurrence with a stack on the
+    # group page.
+    def exception(err, attrs = nil)
+      return if err.nil?
+      merged = {}
+      (attrs || {}).each { |k, v| merged[k] = v }
+      merged["exception.type"] = err.class.name
+      merged["exception.message"] = err.message.to_s
+      merged["exception.stack"] = Array(err.backtrace).join("\n")
+      log(OTEL_ERROR, err.message.to_s, merged)
+    rescue StandardError
+      nil
+    end
+
+    # ------------------------------------------------------------------ spans
+
+    # span opens a child span of the current trace (or a new root trace when
+    # there is none) and runs the block inside it. The span end is recorded
+    # as an event with span.name and durationMs attributes; the span's trace
+    # and span ids ride on the event. A raised exception ends the span as
+    # failed (severity 17, "span <name> failed", exception.type and
+    # exception.message) and is re-raised.
+    def span(name, attrs = nil)
+      raise ArgumentError, "EvolveLogs.span requires a block" unless block_given?
+      tc = Context.child(Context.current)
+      start_ms = monotonic_ms
+      Context.with(tc) do
+        begin
+          result = yield
+          end_span(name, attrs, tc, start_ms, nil)
+          result
+        rescue Exception => err # rubocop:disable Lint/RescueException — re-raised below
+          end_span(name, attrs, tc, start_ms, err)
+          raise
+        end
+      end
+    end
+
+    # ----------------------------------------------------------------- batching
+
+    # flush sends pending events, then pending flag exposures. Safe to call
+    # repeatedly; never raises. 429 honours Retry-After (otherwise
+    # exponential backoff, 500 ms doubling to 10 s, 3 attempts); 413 halves
+    # the batch, dropping the excess half. Exposures flush even when
+    # telemetry is disabled (contract §7).
+    def flush
+      flush_events
+      @flags&.flush_exposures
+      nil
+    end
+
+    # close stops the background flusher and flushes what is pending.
+    # Delivery is best-effort; events still in flight are dropped.
+    def close
+      @flags&.close
+      @stop = true
+      flush
+      @flusher&.join(1)
+      nil
+    end
+
+    private
+
+    # flush_events drains the pending event buffer with the retry policy.
+    def flush_events
+      return unless enabled?
+      @flush_mutex.synchronize do
+        batch = nil
+        @mutex.synchronize do
+          unless @buffer.empty?
+            batch = @buffer.map(&:first)
+            @buffer = []
+            @buffered_bytes = 0
+          end
+        end
+        return if batch.nil? || batch.empty?
+
+        attempt = 0
+        loop do
+          status, resp_headers = begin
+            deliver(batch)
+          rescue StandardError
+            # A raising transport counts as a transport error: [0, {}].
+            [0, {}]
+          end
+          return if status >= 200 && status < 300
+
+          if status == 429 && attempt < MAX_ATTEMPTS - 1
+            attempt += 1
+            interruptible_sleep(backoff(attempt, resp_headers["retry-after"]))
+            next
+          end
+
+          if status == 413 && batch.length > 1
+            # Halve the batch; the excess half is dropped — visible on dropped.
+            half = (batch.length / 2.0).ceil
+            @mutex.synchronize { @dropped += batch.length - half }
+            batch = batch[0, half]
+            next
+          end
+
+          if status.zero? && attempt < MAX_ATTEMPTS - 1
+            # Transport error: retry with plain exponential backoff.
+            attempt += 1
+            interruptible_sleep(backoff(attempt, nil))
+            next
+          end
+
+          # Other statuses and exhausted retries drop the batch.
+          @mutex.synchronize { @dropped += batch.length }
+          return
+        end
+      end
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def enqueue(severity, message, attrs, explicit_context)
+      return unless enabled?
+      return if @sample_rate < 1 && rand >= @sample_rate
+
+      tc = explicit_context || Context.current
+      event_attrs = @redact.call(attrs)
+      event_attrs["service.name"] = @service if present?(@service)
+      event_attrs["deployment.environment"] = @environment if present?(@environment)
+      event_attrs["service.release"] = @release if present?(@release)
+
+      event = {
+        "ts" => now_ts,
+        "severity" => severity,
+        "message" => message.to_s,
+        "attrs" => event_attrs,
+      }
+      unless tc.nil?
+        event["traceId"] = tc.trace_id
+        event["spanId"] = tc.span_id
+        event["parentSpanId"] = tc.parent_span_id unless tc.root?
+      end
+
+      size = JSON.generate(event).bytesize
+      should_flush = false
+      @mutex.synchronize do
+        @buffer << [event, size]
+        @buffered_bytes += size
+        while @buffer.length > MAX_BUFFER
+          @dropped += 1
+          @buffered_bytes -= @buffer.first[1]
+          @buffer.shift
+        end
+        should_flush = @buffer.length >= MAX_BATCH || @buffered_bytes >= MAX_PAYLOAD_BYTES
+      end
+      # Threshold flush on a background thread so enqueue never blocks on the
+      # network; the periodic flusher covers the background: false case.
+      Thread.new { flush } if should_flush && @flusher && !@stop
+      nil
+    end
+
+    def end_span(name, attrs, tc, start_ms, err)
+      span_attrs = {}
+      (attrs || {}).each { |k, v| span_attrs[k] = v }
+      span_attrs["span.name"] = name
+      span_attrs["durationMs"] = (monotonic_ms - start_ms).round
+      if err
+        span_attrs["exception.type"] = err.class.name
+        span_attrs["exception.message"] = err.message.to_s
+        enqueue(OTEL_ERROR, "span #{name} failed", span_attrs, tc)
+      else
+        enqueue(OTEL_INFO, "span #{name} completed", span_attrs, tc)
+      end
+    end
+
+    def deliver(batch)
+      payload = JSON.generate("events" => batch)
+      @transport.call(@url, request_headers, Zlib.gzip(payload))
+    end
+
+    def request_headers
+      {
+        "authorization" => "Bearer #{@key}",
+        "content-type" => "application/json",
+        "content-encoding" => "gzip",
+      }
+    end
+
+    # post_json sends one JSON payload (flag exposures) through the same
+    # transport injection point as events and returns the last status: 2xx
+    # sent, an unrecoverable 4xx dropped, 429 and transport errors retried
+    # with the existing backoff up to MAX_ATTEMPTS.
+    def post_json(url, payload)
+      status = 0
+      MAX_ATTEMPTS.times do |attempt|
+        status, resp_headers = begin
+          @transport.call(url, json_headers, JSON.generate(payload))
+        rescue StandardError
+          [0, {}]
+        end
+        return status if status >= 200 && status < 300
+        return status if status != 429 && status >= 400 && status < 500
+
+        break if attempt >= MAX_ATTEMPTS - 1
+
+        interruptible_sleep(backoff(attempt + 1, resp_headers["retry-after"]))
+      end
+      status
+    end
+
+    def json_headers
+      {
+        "authorization" => "Bearer #{@key}",
+        "content-type" => "application/json",
+        "user-agent" => "e-volv-logs-ruby/#{VERSION}",
+      }
+    end
+
+    # net_http_deliver is the default transport: POST the gzipped body.
+    # Returns [status, headers], or [0, {}] on any transport error — the
+    # retry loop turns that into backoff instead of an exception.
+    def net_http_deliver(url, headers, body)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = DELIVERY_TIMEOUT
+      http.read_timeout = DELIVERY_TIMEOUT
+      path = uri.request_uri
+      path = "/" if path.nil? || path.empty?
+      request = Net::HTTP::Post.new(path)
+      headers.each { |k, v| request[k] = v }
+      request.body = body
+      response = http.start { |conn| conn.request(request) }
+      resp_headers = {}
+      response.each_header { |k, v| resp_headers[k] = v }
+      [response.code.to_i, resp_headers]
+    rescue StandardError
+      [0, {}]
+    end
+
+    # backoff computes the retry delay: Retry-After (seconds) when the ingest
+    # sent one, otherwise exponential backoff from 500 ms doubling to 10 s.
+    def backoff(attempt, retry_after)
+      text = retry_after.to_s.strip
+      unless text.empty?
+        begin
+          seconds = Float(text)
+          return seconds if seconds >= 0
+        rescue ArgumentError, TypeError
+          # Fall through to exponential backoff.
+        end
+      end
+      delay = BACKOFF_BASE
+      (attempt - 1).times { delay *= 2 }
+      [delay, BACKOFF_MAX].min
+    end
+
+    def interruptible_sleep(seconds)
+      sleep(seconds) unless @stop
+    end
+
+    def flusher_loop
+      loop do
+        sleep(FLUSH_INTERVAL)
+        break if @stop
+        flush
+      end
+    rescue StandardError
+      nil
+    end
+
+    # now_ts formats Time as ISO 8601 UTC with millisecond precision, e.g.
+    # 2026-09-06T14:00:00.123Z.
+    def now_ts
+      Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    def monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+    end
+
+    def clamp_sample_rate(rate)
+      rate = rate.to_f
+      return 1.0 if rate.nan?
+      [[rate, 0.0].max, 1.0].min
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.empty?
+    end
+  end
+end