e-volv-logs 0.1.0

data/lib/evolve_logs/flags/sse.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  module Flags
+    # Minimal text/event-stream parser: `event` and `data` fields, a blank
+    # line dispatches one event, `data` lines join with "\n". Port of
+    # logs-js/src/flags/sse.ts (and S2's Python).
+    class SseParser
+      def initialize(&on_event)
+        @on_event = on_event
+        @buffer = +""
+        @event = "message"
+        @data = []
+      end
+
+      def push(text)
+        @buffer << text
+        while (idx = @buffer.index("\n"))
+          line = @buffer[0...idx]
+          @buffer = @buffer[(idx + 1)..-1] || +""
+          line = line.chomp("\r")
+          if line.empty?
+            @on_event.call(@event, @data.join("\n")) unless @data.empty?
+            @event = "message"
+            @data = []
+            next
+          end
+          next if line.start_with?(":")
+
+          field, colon, value = line.partition(":")
+          value = value[1..-1] if colon == ":" && value.start_with?(" ")
+          if field == "event"
+            @event = value
+          elsif field == "data"
+            @data << value
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/evolve_logs/flags.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# e-volv Launch flags for the Ruby Observer SDK (docs/LAUNCH-SDK.md).
+#
+# One init and one key serve both logs and flags: the flags client binds to
+# the Observer client's key and runs flag delivery on its own background
+# thread, because a held-open stream would stall log flushing.
+#
+# Evaluation is synchronous, never raises and never performs I/O — the
+# delivery state machine (PORTING.md "Delivery behaviour") owns the network
+# on its own thread.
+
+require "digest/sha1"
+require "json"
+require "net/http"
+require "securerandom"
+require "tempfile"
+require "tmpdir"
+require "uri"
+
+module EvolveLogs
+  module Flags
+    # The production control plane (contract §2).
+    DEFAULT_FLAGS_BASE = "https://api.e-volv.io/api/public/v1/flags"
+
+    module_function
+
+    # base_url resolves the flags endpoint: an explicit flags url wins; else
+    # the origin of the Observer ingest url; else production. Never throws.
+    def base_url(observer_url, flags_url)
+      return flags_url.sub(%r{/+\z}, "") if flags_url.is_a?(String) && !flags_url.empty?
+
+      if observer_url.is_a?(String) && !observer_url.empty?
+        begin
+          uri = URI.parse(observer_url)
+          unless uri.scheme.nil? || uri.host.nil?
+            netloc = uri.host
+            netloc = "#{netloc}:#{uri.port}" if uri.port && uri.default_port != uri.port
+            return "#{uri.scheme}://#{netloc}/api/public/v1/flags"
+          end
+        rescue StandardError
+          # Fall through to production, like the JS URL() catch.
+        end
+      end
+      DEFAULT_FLAGS_BASE
+    end
+
+    # full_jitter_seconds is the reconnect/retry sleep (contract §4):
+    # random(0, min(60, 2^attempt)) seconds.
+    def full_jitter_seconds(attempt, rng = Random)
+      rng.rand * [60, 2**[0, attempt].max].min
+    end
+  end
+end
+
+require "evolve_logs/flags/js_values"
+require "evolve_logs/flags/context"
+require "evolve_logs/flags/regex_cache"
+require "evolve_logs/flags/kernel"
+require "evolve_logs/flags/options"
+require "evolve_logs/flags/cache"
+require "evolve_logs/flags/exposures"
+require "evolve_logs/flags/sse"
+require "evolve_logs/flags/delivery"
+require "evolve_logs/flags/client"

data/lib/evolve_logs/http.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module EvolveLogs
+  # Outbound traceparent injection, monkeypatch-free — helper modules you opt
+  # into per call site instead of patching Net::HTTP or Faraday globally.
+  module HTTP
+    # inject_traceparent sets the W3C traceparent header on a Net::HTTP
+    # request (or anything with Net::HTTPHeader-style #[]/#[]=) when called
+    # inside a trace. An existing traceparent header is never overwritten.
+    #
+    #     request = Net::HTTP::Post.new(uri)
+    #     EvolveLogs::HTTP.inject_traceparent(request)
+    #     http.request(request)
+    def self.inject_traceparent(request)
+      tp = EvolveLogs.traceparent
+      if tp && (request["traceparent"].nil? || request["traceparent"].empty?)
+        request["traceparent"] = tp
+      end
+      request
+    end
+  end
+
+  # FaradayMiddleware is a duck-typed Faraday middleware (no faraday require;
+  # any object with #call(env) works). Add it where the connection is built:
+  #
+  #     conn = Faraday.new(url: "https://internal") do |builder|
+  #       builder.use EvolveLogs::FaradayMiddleware
+  #       builder.adapter Faraday.default_adapter
+  #     end
+  #
+  # Outbound requests made inside a trace carry the traceparent header; an
+  # existing header is never overwritten.
+  class FaradayMiddleware
+    def initialize(app, _options = {})
+      @app = app
+    end
+
+    def call(env)
+      headers = env.request_headers
+      tp = EvolveLogs.traceparent
+      existing = headers["traceparent"]
+      headers["traceparent"] = tp if tp && (existing.nil? || existing.empty?)
+      @app.call(env)
+    end
+  end
+end

data/lib/evolve_logs/logger.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module EvolveLogs
+  # Logger is a stdlib ::Logger subclass that ships every line to Observer in
+  # addition to the underlying log device, so
+  #
+  #     Rails.logger = EvolveLogs::Logger.new($stdout)
+  #
+  # keeps the familiar Logger interface while every event reaches the ingest
+  # with its severity mapped to the OTel number. Logging an Exception as the
+  # message (`Rails.logger.error(err)`) becomes an exception.* error event.
+  class Logger < ::Logger
+    SEVERITY_TO_OTEL = {
+      ::Logger::DEBUG => EvolveLogs::OTEL_DEBUG,
+      ::Logger::INFO => EvolveLogs::OTEL_INFO,
+      ::Logger::WARN => EvolveLogs::OTEL_WARN,
+      ::Logger::ERROR => EvolveLogs::OTEL_ERROR,
+      ::Logger::FATAL => EvolveLogs::OTEL_FATAL,
+      ::Logger::UNKNOWN => EvolveLogs::OTEL_FATAL,
+    }.freeze
+
+    def initialize(logdev, client: nil)
+      @evolve_client = client
+      super(logdev)
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      severity ||= ::Logger::UNKNOWN
+      raw = message.nil? ? (block ? block.call : progname) : message
+      emit_to_evolve(severity, raw)
+      super(severity, message, progname, &block)
+    end
+
+    private
+
+    def emit_to_evolve(severity, raw)
+      client = @evolve_client || EvolveLogs.get_client
+      return if client.nil? || !client.enabled?
+      if raw.is_a?(Exception)
+        client.exception(raw)
+      else
+        otel = SEVERITY_TO_OTEL[severity] || EvolveLogs::OTEL_INFO
+        client.log(otel, raw.nil? ? "" : raw.to_s)
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/evolve_logs/rack_middleware.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  # RackMiddleware is plain Rack middleware: one root span per request,
+  # continuing an inbound traceparent header (or starting a fresh trace when
+  # there is none). Rack is a soft dependency — the middleware is duck-typed
+  # on #call and nothing requires "rack".
+  #
+  #     use EvolveLogs::RackMiddleware
+  #
+  # An app that raises ends the "http.request" span as failed and is
+  # re-raised, so the server sees the crash exactly as it would without the
+  # SDK.
+  class RackMiddleware
+    def initialize(app, client: nil, span_name: "http.request")
+      @app = app
+      @client = client
+      @span_name = span_name
+    end
+
+    def call(env)
+      client = @client || EvolveLogs.get_client
+      inbound = env["HTTP_TRACEPARENT"]
+      EvolveLogs.run_with_traceparent(inbound) do
+        attrs = {
+          "http.method" => env["REQUEST_METHOD"].to_s,
+          "http.path" => env["PATH_INFO"].to_s,
+        }
+        client.span(@span_name, attrs) { @app.call(env) }
+      end
+    end
+  end
+end

data/lib/evolve_logs/redact.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  # The backstop list: attribute keys matching this pattern are redacted
+  # before anything leaves the process. Pinned by the shared contract;
+  # redact_keys extends it (docs/OBSERVER-SDK.md).
+  BACKSTOP_PATTERN = /password|secret|token|authorization|cookie|set-cookie|api[-_]?key/i.freeze
+  REDACTED = "[redacted]"
+
+  # Redactor deep-walks hashes and arrays; values whose key matches the
+  # pattern (case-insensitive substring) are replaced with "[redacted]".
+  class Redactor
+    def initialize(extra_keys = nil)
+      sources = [BACKSTOP_PATTERN.source]
+      Array(extra_keys).each { |k| sources << Regexp.escape(k.to_s) }
+      @pattern = Regexp.new(sources.join("|"), Regexp::IGNORECASE)
+    end
+
+    def call(attrs)
+      walk(attrs || {})
+    end
+
+    private
+
+    def walk(value)
+      case value
+      when Hash
+        out = {}
+        value.each do |key, val|
+          out[key] = @pattern.match?(key.to_s) ? REDACTED : walk(val)
+        end
+        out
+      when Array
+        value.map { |val| walk(val) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/evolve_logs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EvolveLogs
+  VERSION = "0.1.0"
+end

data/lib/evolve_logs.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# e-volv Observer SDK for Ruby (gem: e-volv-logs).
+#
+# Speaks the one wire contract documented in docs/OBSERVER-SDK.md: batches
+# events (200 events / 2 s / 512 KB), gzips the payload, retries 429 with
+# backoff and 413 by halving, redacts sensitive attribute keys before
+# enqueue, and carries W3C traceparent in Thread/Fiber-local context.
+# Everything is fail-silent: a logging SDK never raises into user code.
+
+require "json"
+require "zlib"
+require "securerandom"
+require "net/http"
+require "uri"
+
+module EvolveLogs
+  # Shared batching and retry numbers — identical in every SDK
+  # (docs/OBSERVER-SDK.md §"The contract every SDK speaks").
+  MAX_BATCH = 200
+  FLUSH_INTERVAL = 2.0
+  MAX_PAYLOAD_BYTES = 512 * 1024
+  MAX_BUFFER = MAX_BATCH * 2 # then the oldest events are dropped
+  MAX_ATTEMPTS = 3
+  BACKOFF_BASE = 0.5 # seconds, doubling
+  BACKOFF_MAX = 10.0
+  DELIVERY_TIMEOUT = 10 # seconds per request; matches the ingest's budget
+
+  # OTel severity numbers (trace 1 … fatal 21).
+  OTEL_TRACE = 1
+  OTEL_DEBUG = 5
+  OTEL_INFO = 9
+  OTEL_WARN = 13
+  OTEL_ERROR = 17
+  OTEL_FATAL = 21
+end
+
+require "evolve_logs/version"
+require "evolve_logs/context"
+require "evolve_logs/redact"
+require "evolve_logs/flags"
+require "evolve_logs/client"
+require "evolve_logs/logger"
+require "evolve_logs/rack_middleware"
+require "evolve_logs/carriers"
+require "evolve_logs/http"
+
+module EvolveLogs
+  # Registry of live clients, flushed from the at_exit hook at the bottom of
+  # this file. A process that never calls init has nothing to flush.
+  module Registry
+    @clients = []
+    @mutex = Mutex.new
+
+    def self.register(client)
+      @mutex.synchronize { @clients << client }
+    end
+
+    def self.flush_all
+      clients = @mutex.synchronize { @clients.dup }
+      clients.each(&:flush)
+    end
+  end
+
+  @default_mutex = Mutex.new
+  @default_client = nil
+
+  class << self
+    # init installs the module-level default client built from the keyword
+    # options and returns it. Module-level helpers (EvolveLogs.info,
+    # EvolveLogs.span, …) delegate to it; a later init replaces the previous
+    # default. With an empty key or url the client is a no-op and warns once
+    # on stderr. `flags:` carries the Launch flags options (a
+    # EvolveLogs::Flags::Options or an options Hash); the flags handle is
+    # available as client.flags / EvolveLogs.flags.
+    def init(key: nil, url: nil, service: nil, environment: nil, release: nil,
+             redact_keys: nil, sample_rate: 1.0, flags: nil, **opts)
+      install(Client.new(key: key, url: url, service: service,
+                         environment: environment, release: release,
+                         redact_keys: redact_keys, sample_rate: sample_rate,
+                         flags: flags, **opts))
+    end
+
+    # install replaces the module-level default client (used by tests and
+    # custom wiring) and returns it.
+    def install(client)
+      @default_mutex.synchronize { @default_client = client }
+      client
+    end
+
+    # get_client returns the current default client, lazily a silent no-op —
+    # the one-warning contract belongs to init, not to the pre-init default.
+    def get_client
+      @default_mutex.synchronize { @default_client } ||
+        install(Client.new(key: nil, url: nil, silent: true))
+    end
+
+    # log enqueues an event at the given OTel severity number.
+    def log(severity, message, attrs = nil)
+      get_client.log(severity, message, attrs)
+    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 / exception.message / exception.stack
+    # attributes, which make the event an error occurrence on the group page.
+    def exception(err, attrs = nil)
+      get_client.exception(err, attrs)
+    end
+
+    # span opens a child span of the current trace (or a new root trace) and
+    # runs the block inside it. A raised exception ends the span failed —
+    # exception.* attrs, severity 17 — and is re-raised, so the caller sees
+    # the failure exactly as before.
+    def span(name, attrs = nil, &block)
+      get_client.span(name, attrs, &block)
+    end
+
+    # traceparent returns the W3C traceparent of the current trace,
+    # "00-<traceId>-<spanId>-01", or nil outside a trace.
+    def traceparent
+      Context.traceparent
+    end
+
+    # run_with_traceparent runs the block with the next hop of the trace
+    # named by a W3C traceparent header — the consumer side of a queue, the
+    # callee side of an inbound request. An absent or malformed header starts
+    # a fresh root trace.
+    def run_with_traceparent(header)
+      Context.with(Context.hop(header)) { yield }
+    end
+
+    def current_context
+      Context.current
+    end
+
+    # flush sends pending events on the default client; safe to call
+    # repeatedly (also from an at_exit hook).
+    def flush
+      get_client.flush
+    end
+
+    # flags returns the default client's Launch flags handle
+    # (docs/LAUNCH-SDK.md §3).
+    def flags
+      get_client.flags
+    end
+
+    # dropped returns the default client's dropped-event counter.
+    def dropped
+      get_client.dropped
+    end
+  end
+end
+
+at_exit { EvolveLogs::Registry.flush_all }

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: e-volv-logs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- e-volv
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+description: Batched log shipping, trace context and error capture for the e-volv
+  Observer ingest. Pure Ruby + stdlib; Rack middleware, Rails.logger bridge, ActiveJob
+  and Sidekiq carriers, Net::HTTP and Faraday injection.
+email:
+- support@e-volv.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/evolve_logs.rb
+- lib/evolve_logs/carriers.rb
+- lib/evolve_logs/client.rb
+- lib/evolve_logs/context.rb
+- lib/evolve_logs/flags.rb
+- lib/evolve_logs/flags/cache.rb
+- lib/evolve_logs/flags/client.rb
+- lib/evolve_logs/flags/context.rb
+- lib/evolve_logs/flags/delivery.rb
+- lib/evolve_logs/flags/exposures.rb
+- lib/evolve_logs/flags/js_values.rb
+- lib/evolve_logs/flags/kernel.rb
+- lib/evolve_logs/flags/options.rb
+- lib/evolve_logs/flags/regex_cache.rb
+- lib/evolve_logs/flags/sse.rb
+- lib/evolve_logs/http.rb
+- lib/evolve_logs/logger.rb
+- lib/evolve_logs/rack_middleware.rb
+- lib/evolve_logs/redact.rb
+- lib/evolve_logs/version.rb
+homepage: https://e-volv.io
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: e-volv Observer SDK for Ruby
+test_files: []