opentrace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba760f415dab6abc4ce324ec9f63aaaa961d4cd115555fce4b4f11fa718c1327
+  data.tar.gz: 2d40538689afa5fafa0ab678d5b81f64a2ee2cccbf8b69143f1f0786422b71fa
+SHA512:
+  metadata.gz: c4e5a1c1f97d166b2905f139c9035876a627f0affd604092fead4a64a8795913ab8e4dec1b86c7c2b337ce1fc070c776105e758fb16624fb28e5342bbcf0eb5c
+  data.tar.gz: 7f3a034f7fbc791d73201e57a0ac25fe4307a92436873fa0256517887e19a689d11e1d5fd29c9f203894e3847557ebb417f8c9e8d5fff897a1fac7f15b62d4bd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenTrace
+
+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,175 @@
+# OpenTrace Ruby
+
+A thin, safe Ruby client that forwards structured application logs to an [OpenTrace](https://github.com/opentrace/opentrace) server over HTTP.
+
+**This gem will never crash or slow down your application.** All network errors are swallowed silently. If the server is unreachable, logs are dropped.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "opentrace"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+```ruby
+OpenTrace.configure do |c|
+  c.endpoint    = "https://opentrace.example.com"   # required
+  c.api_key     = ENV["OPENTRACE_API_KEY"]           # required
+  c.service     = "billing-api"                      # required
+  c.environment = "production"                       # optional
+  c.timeout     = 1.0                                # optional, seconds (default: 1.0)
+  c.enabled     = true                               # optional (default: true)
+end
+```
+
+If any required field (`endpoint`, `api_key`, `service`) is missing or empty, the gem **disables itself automatically**. No errors, no logs sent.
+
+## Usage
+
+### Direct logging
+
+```ruby
+OpenTrace.log("INFO", "User signed in", { user_id: 42, ip: "1.2.3.4" })
+
+OpenTrace.log("ERROR", "Payment failed", {
+  trace_id: "abc-123",
+  user_id: 99,
+  exception: {
+    class: "Stripe::CardError",
+    message: "Your card was declined"
+  }
+})
+```
+
+Pass `trace_id` inside metadata and it will be promoted to a top-level field automatically.
+
+### Logger wrapper
+
+Wrap any Ruby `Logger` to forward all log output to OpenTrace while keeping the original logger working exactly as before:
+
+```ruby
+require "logger"
+
+logger = Logger.new($stdout)
+logger = OpenTrace::Logger.new(logger)
+
+logger.info("This goes to STDOUT and to OpenTrace")
+logger.error("So does this")
+```
+
+You can attach default metadata to every log from this logger:
+
+```ruby
+logger = OpenTrace::Logger.new(original_logger, metadata: { component: "worker" })
+```
+
+### Rails
+
+In a Rails app, add an initializer:
+
+```ruby
+# config/initializers/opentrace.rb
+OpenTrace.configure do |c|
+  c.endpoint    = ENV["OPENTRACE_ENDPOINT"]
+  c.api_key     = ENV["OPENTRACE_API_KEY"]
+  c.service     = "my-rails-app"
+  c.environment = Rails.env
+end
+```
+
+The gem auto-detects Rails and will:
+
+- Wrap `Rails.logger` so all log output is forwarded to OpenTrace
+- Subscribe to `process_action.action_controller` notifications to capture:
+  - `request_id`
+  - `controller` and `action`
+  - `method`, `path`, `status`, `duration_ms`
+  - `user_id` (if your controller responds to `current_user`)
+
+Requests that return 5xx status codes are logged as `ERROR`, everything else as `INFO`.
+
+### TaggedLogging
+
+If your wrapped logger uses `ActiveSupport::TaggedLogging`, tags are preserved and injected into the metadata:
+
+```ruby
+Rails.logger.tagged("RequestID-123") do
+  Rails.logger.info("Processing request")
+  # metadata will include: { tags: ["RequestID-123"] }
+end
+```
+
+## Runtime controls
+
+```ruby
+OpenTrace.enabled?  # check if logging is active
+OpenTrace.disable!  # turn off (logs are silently dropped)
+OpenTrace.enable!   # turn back on
+```
+
+## Graceful shutdown
+
+If your app needs a clean shutdown (e.g. a Sidekiq worker), drain the queue before exiting:
+
+```ruby
+OpenTrace.shutdown(timeout: 5)
+```
+
+This gives the background thread up to 5 seconds to send any remaining queued logs.
+
+## How it works
+
+- Logs are serialized to JSON and pushed onto an in-memory queue
+- A single background thread reads from the queue and sends each payload via `POST /api/logs`
+- The thread is started lazily on the first log call -- no threads are created at boot
+- If the queue exceeds 1,000 items, new logs are dropped (oldest are preserved)
+- Payloads larger than 32 KB are dropped
+- All network errors (timeouts, connection refused, DNS failures) are swallowed silently
+- The HTTP timeout defaults to 1 second
+
+## Log payload format
+
+Each log is sent as a JSON object:
+
+```json
+{
+  "timestamp": "2026-02-08T12:41:00.000000Z",
+  "level": "ERROR",
+  "service": "billing-api",
+  "environment": "production",
+  "trace_id": "abc-123",
+  "message": "PG::UniqueViolation",
+  "metadata": {
+    "user_id": 42,
+    "request_id": "req-456"
+  }
+}
+```
+
+| Field         | Type   | Required |
+|---------------|--------|----------|
+| `timestamp`   | string | yes      |
+| `level`       | string | yes      |
+| `message`     | string | yes      |
+| `service`     | string | no       |
+| `environment` | string | no       |
+| `trace_id`    | string | no       |
+| `metadata`    | object | no       |
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 6+ (optional, auto-detected)
+
+## License
+
+MIT

data/lib/opentrace/client.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module OpenTrace
+  class Client
+    MAX_QUEUE_SIZE = 1000
+    PAYLOAD_MAX_BYTES = 32_768 # 32 KB
+    POLL_INTERVAL = 0.05 # 50ms
+
+    def initialize(config)
+      @config = config
+      @queue  = Thread::Queue.new
+      @mutex  = Mutex.new
+      @thread = nil
+    end
+
+    def enqueue(payload)
+      return unless @config.enabled?
+
+      # Drop newest if queue is full
+      return if @queue.size >= MAX_QUEUE_SIZE
+
+      @queue.push(payload)
+      ensure_thread_running
+    end
+
+    def shutdown(timeout: 5)
+      @queue.close
+      @thread&.join(timeout)
+    end
+
+    private
+
+    def ensure_thread_running
+      return if @thread&.alive?
+
+      @mutex.synchronize do
+        return if @thread&.alive?
+
+        @thread = Thread.new { dispatch_loop }
+        @thread.abort_on_exception = false
+        @thread.report_on_exception = false
+      end
+    end
+
+    def dispatch_loop
+      uri = URI.join(@config.endpoint.chomp("/") + "/", "api/logs")
+
+      loop do
+        batch = drain_queue
+        break if batch.nil?
+        next if batch.empty?
+
+        send_batch(uri, batch)
+      end
+    rescue Exception # rubocop:disable Lint/RescueException
+      # Swallow all errors including thread kill
+    end
+
+    def drain_queue
+      batch = []
+      deadline = Time.now + @config.flush_interval
+
+      loop do
+        if batch.empty?
+          # Block until first item arrives or timeout
+          item = pop_with_timeout(deadline - Time.now)
+          return nil if item.nil? && @queue.closed?
+          batch << item if item
+        else
+          # Non-blocking drain up to batch_size
+          while batch.size < @config.batch_size
+            begin
+              item = @queue.pop(true) # non_block = true
+              batch << item
+            rescue ThreadError
+              break # queue empty
+            end
+          end
+        end
+
+        break if batch.size >= @config.batch_size
+        break if Time.now >= deadline && !batch.empty?
+        break if @queue.closed?
+      end
+
+      batch
+    end
+
+    def pop_with_timeout(timeout)
+      deadline = Time.now + [timeout, 0].max
+      loop do
+        begin
+          return @queue.pop(true)
+        rescue ThreadError
+          return nil if Time.now >= deadline || @queue.closed?
+          sleep(POLL_INTERVAL)
+        end
+      end
+    rescue ClosedQueueError
+      nil
+    end
+
+    def send_batch(uri, batch)
+      # Apply per-payload truncation
+      batch = batch.map { |p| fit_payload(p) }.compact
+      return if batch.empty?
+
+      json = JSON.generate(batch)
+
+      # If entire batch exceeds limit, split and retry
+      if json.bytesize > PAYLOAD_MAX_BYTES
+        mid = batch.size / 2
+        send_batch(uri, batch[0...mid]) if mid > 0
+        send_batch(uri, batch[mid..]) if mid < batch.size
+        return
+      end
+
+      http = build_http(uri)
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Authorization"] = "Bearer #{@config.api_key}"
+      request["Content-Type"]  = "application/json"
+      request["User-Agent"]    = "opentrace-ruby/#{OpenTrace::VERSION}"
+      request.body = json
+
+      http.request(request)
+    rescue StandardError
+      # Swallow all network errors silently
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+      http.write_timeout = @config.timeout
+      http
+    end
+
+    def fit_payload(payload)
+      json = JSON.generate(payload)
+      if json.bytesize > PAYLOAD_MAX_BYTES
+        payload = truncate_payload(payload)
+        json = JSON.generate(payload)
+        return nil if json.bytesize > PAYLOAD_MAX_BYTES
+      end
+      payload
+    rescue StandardError
+      nil
+    end
+
+    def truncate_payload(payload)
+      meta = payload[:metadata]&.dup || {}
+
+      # Truncation priority: remove largest optional fields first
+      meta.delete(:backtrace)
+      meta.delete(:params)
+      meta.delete(:job_arguments)
+      meta[:sql] = meta[:sql][0, 200] + "..." if meta[:sql].is_a?(String) && meta[:sql].length > 200
+      meta[:exception_message] = meta[:exception_message][0, 200] + "..." if meta[:exception_message].is_a?(String) && meta[:exception_message].length > 200
+
+      payload.merge(metadata: meta)
+    end
+  end
+end

data/lib/opentrace/config.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OpenTrace
+  class Config
+    REQUIRED_FIELDS = %i[endpoint api_key service].freeze
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }.freeze
+
+    attr_accessor :endpoint, :api_key, :service, :environment, :timeout, :enabled,
+                  :context, :min_level, :hostname, :pid, :git_sha,
+                  :batch_size, :flush_interval,
+                  :sql_logging, :sql_duration_threshold_ms
+
+    def initialize
+      @endpoint    = nil
+      @api_key     = nil
+      @service     = nil
+      @environment = nil
+      @timeout     = 1.0
+      @enabled     = true
+      @context     = nil    # nil | Hash | Proc
+      @min_level   = :debug # send everything by default
+      @hostname       = nil
+      @pid            = nil
+      @git_sha        = nil
+      @batch_size     = 50
+      @flush_interval = 5.0
+      @sql_logging    = true
+      @sql_duration_threshold_ms = 0.0
+    end
+
+    def valid?
+      REQUIRED_FIELDS.all? { |f| value = send(f); value.is_a?(String) && !value.empty? }
+    end
+
+    def enabled?
+      @enabled && valid?
+    end
+
+    def min_level_value
+      LEVELS[min_level.to_s.downcase.to_sym] || 0
+    end
+  end
+end

data/lib/opentrace/log_forwarder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module OpenTrace
+  # Minimal Logger-compatible class that forwards log messages to OpenTrace.
+  # Designed to be used as a broadcast target with Rails 7.1+ BroadcastLogger.
+  # Does NOT wrap another logger — its only job is to forward to OpenTrace.
+  class LogForwarder < ::Logger
+    SEVERITY_MAP = {
+      ::Logger::DEBUG   => "DEBUG",
+      ::Logger::INFO    => "INFO",
+      ::Logger::WARN    => "WARN",
+      ::Logger::ERROR   => "ERROR",
+      ::Logger::FATAL   => "FATAL",
+      ::Logger::UNKNOWN => "UNKNOWN"
+    }.freeze
+
+    def initialize
+      super(nil)
+      self.level = ::Logger::DEBUG
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      severity ||= ::Logger::UNKNOWN
+      return true if severity < level
+
+      msg = resolve_message(message, progname, &block)
+      return true if msg.nil? || (msg.is_a?(String) && msg.strip.empty?)
+
+      level_str = SEVERITY_MAP.fetch(severity, "UNKNOWN")
+      OpenTrace.log(level_str, msg.to_s)
+
+      true
+    rescue StandardError
+      true
+    end
+
+    def close
+      # no-op — nothing to close
+    end
+
+    private
+
+    def resolve_message(message, progname, &block)
+      if message.nil?
+        block ? block.call : progname
+      else
+        message
+      end
+    end
+  end
+end

data/lib/opentrace/logger.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module OpenTrace
+  class Logger < ::Logger
+    SEVERITY_MAP = {
+      ::Logger::DEBUG   => "DEBUG",
+      ::Logger::INFO    => "INFO",
+      ::Logger::WARN    => "WARN",
+      ::Logger::ERROR   => "ERROR",
+      ::Logger::FATAL   => "FATAL",
+      ::Logger::UNKNOWN => "UNKNOWN"
+    }.freeze
+
+    attr_reader :wrapped_logger
+
+    def initialize(wrapped_logger, metadata: {})
+      @wrapped_logger = wrapped_logger
+      @default_metadata = metadata
+      # Initialize with nil logdev - we override #add to handle output
+      super(nil)
+      self.level = wrapped_logger.level if wrapped_logger.respond_to?(:level)
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      # Delegate to wrapped logger first (synchronous, as required)
+      @wrapped_logger.add(severity, message, progname, &block)
+
+      # Forward to OpenTrace, never raise
+      forward_to_opentrace(severity, message, progname, &block)
+
+      true
+    rescue StandardError
+      # Never raise to the host app
+      true
+    end
+
+    # Support TaggedLogging if the wrapped logger uses it
+    def tagged(*tags, &block)
+      if @wrapped_logger.respond_to?(:tagged)
+        @wrapped_logger.tagged(*tags) do
+          @current_tags = current_tags_from_wrapped
+          block.call(self)
+        end
+      else
+        block.call(self)
+      end
+    rescue StandardError
+      block.call(self)
+    end
+
+    def flush
+      @wrapped_logger.flush if @wrapped_logger.respond_to?(:flush)
+    end
+
+    def close
+      @wrapped_logger.close if @wrapped_logger.respond_to?(:close)
+    end
+
+    # Proxy formatter to wrapped logger
+    def formatter
+      if @wrapped_logger.respond_to?(:formatter)
+        @wrapped_logger.formatter
+      else
+        super
+      end
+    end
+
+    def formatter=(f)
+      if @wrapped_logger&.respond_to?(:formatter=)
+        @wrapped_logger.formatter = f
+      else
+        super
+      end
+    end
+
+    private
+
+    def forward_to_opentrace(severity, message, progname, &block)
+      return unless OpenTrace.enabled?
+
+      msg = resolve_message(message, progname, &block)
+      return if msg.nil? || (msg.is_a?(String) && msg.strip.empty?)
+
+      level_str = SEVERITY_MAP.fetch(severity || ::Logger::UNKNOWN, "UNKNOWN")
+
+      metadata = @default_metadata.dup
+      tags = current_tags_from_wrapped
+      metadata[:tags] = tags if tags && !tags.empty?
+
+      OpenTrace.log(level_str, msg.to_s, metadata)
+    rescue StandardError
+      # Swallow - never affect the host app
+    end
+
+    def resolve_message(message, progname, &block)
+      if message.nil?
+        if block
+          block.call
+        else
+          progname
+        end
+      else
+        message
+      end
+    end
+
+    def current_tags_from_wrapped
+      if @wrapped_logger.respond_to?(:formatter) &&
+         @wrapped_logger.formatter.respond_to?(:current_tags)
+        @wrapped_logger.formatter.current_tags.dup
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/opentrace/middleware.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OpenTrace
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request_id = env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+      OpenTrace.current_request_id = request_id
+
+      @app.call(env)
+    ensure
+      OpenTrace.current_request_id = nil
+    end
+  end
+end

data/lib/opentrace/rails.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+if defined?(::Rails::Railtie)
+  module OpenTrace
+    class Railtie < ::Rails::Railtie
+      # Use config.after_initialize so that config/initializers/ files
+      # (where the user calls OpenTrace.configure) have already run.
+      # Register middleware early — before the stack is frozen
+      initializer "opentrace.middleware" do |app|
+        app.middleware.use OpenTrace::Middleware
+      end
+
+      config.after_initialize do |app|
+        next unless OpenTrace.enabled?
+
+        if Rails.logger.respond_to?(:broadcast_to)
+          # Rails 7.1+: register as a broadcast target (non-invasive)
+          Rails.logger.broadcast_to(OpenTrace::LogForwarder.new)
+        else
+          # Pre-7.1 fallback: wrap the logger directly
+          if app.config.logger
+            app.config.logger = OpenTrace::Logger.new(app.config.logger)
+            Rails.logger = app.config.logger
+          elsif Rails.logger
+            Rails.logger = OpenTrace::Logger.new(Rails.logger)
+          end
+        end
+
+        # Subscribe to controller request notifications
+        ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          forward_request_log(event)
+        rescue StandardError
+          # Swallow - never affect the host app
+        end
+
+        # Subscribe to SQL query notifications
+        if OpenTrace.config.sql_logging
+          ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            forward_sql_log(event)
+          rescue StandardError
+            # Swallow
+          end
+        end
+
+        # Subscribe to ActiveJob notifications
+        ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          forward_job_log(event)
+        rescue StandardError
+          # Swallow
+        end
+      end
+
+      class << self
+        private
+
+        def forward_request_log(event)
+          return unless OpenTrace.enabled?
+
+          payload = event.payload
+          metadata = {
+            request_id: payload[:headers]&.env&.dig("action_dispatch.request_id"),
+            controller: payload[:controller],
+            action: payload[:action],
+            method: payload[:method],
+            path: payload[:path],
+            status: payload[:status],
+            duration_ms: event.duration&.round(1)
+          }.compact
+
+          # Attempt to capture current user ID if available
+          user_id = extract_user_id(payload)
+          metadata[:user_id] = user_id if user_id
+
+          # Exception auto-capture
+          if payload[:exception]
+            metadata[:exception_class]   = payload[:exception][0]
+            metadata[:exception_message] = truncate(payload[:exception][1], 500)
+          end
+
+          if payload[:exception_object]&.backtrace
+            cleaned = clean_backtrace(payload[:exception_object].backtrace)
+            metadata[:backtrace] = cleaned.first(15)
+          end
+
+          # Filtered request params
+          extract_params(payload, metadata)
+
+          level = if payload[:exception]
+                    "ERROR"
+                  elsif payload[:status].to_i >= 500
+                    "ERROR"
+                  elsif payload[:status].to_i >= 400
+                    "WARN"
+                  else
+                    "INFO"
+                  end
+          message = "#{payload[:method]} #{payload[:path]} #{payload[:status]} #{event.duration&.round(1)}ms"
+
+          OpenTrace.log(level, message, metadata)
+        rescue StandardError
+          # Swallow
+        end
+
+        def forward_job_log(event)
+          return unless OpenTrace.enabled?
+
+          payload = event.payload
+          job = payload[:job]
+
+          metadata = {
+            job_class: job.class.name,
+            job_id: job.respond_to?(:job_id) ? job.job_id : nil,
+            queue_name: job.respond_to?(:queue_name) ? job.queue_name : nil,
+            executions: job.respond_to?(:executions) ? job.executions : nil,
+            duration_ms: event.duration&.round(1)
+          }.compact
+
+          # Capture arguments (truncated)
+          if job.respond_to?(:arguments)
+            args_json = JSON.generate(job.arguments)
+            metadata[:job_arguments] = if args_json.bytesize > 512
+                                         args_json[0, 512] + "..."
+                                       else
+                                         job.arguments
+                                       end
+          end
+
+          # Capture exceptions from job failures
+          if payload[:exception_object]
+            metadata[:exception_class]   = payload[:exception_object].class.name
+            metadata[:exception_message] = truncate(payload[:exception_object].message, 500)
+            if payload[:exception_object].backtrace
+              metadata[:backtrace] = clean_backtrace(payload[:exception_object].backtrace).first(15)
+            end
+          end
+
+          level = payload[:exception_object] ? "ERROR" : "INFO"
+          message = if payload[:exception_object]
+                      "Job #{job.class.name} FAILED (attempt #{job.respond_to?(:executions) ? job.executions : '?'})"
+                    else
+                      "Job #{job.class.name} completed #{event.duration&.round(1)}ms"
+                    end
+
+          OpenTrace.log(level, message, metadata)
+        rescue StandardError
+          # Swallow
+        end
+
+        def forward_sql_log(event)
+          return unless OpenTrace.enabled?
+
+          payload = event.payload
+          duration = event.duration&.round(2)
+          threshold = OpenTrace.config.sql_duration_threshold_ms
+
+          # Skip if below threshold
+          return if threshold > 0 && duration && duration < threshold
+
+          # Skip SCHEMA queries (migrations, structure dumps)
+          return if payload[:name] == "SCHEMA"
+
+          metadata = {
+            sql_name: payload[:name],
+            sql: truncate(payload[:sql], 1000),
+            sql_duration_ms: duration,
+            sql_cached: payload[:cached] || false
+          }.compact
+
+          # Extract table name from SQL for easier filtering
+          if payload[:sql] =~ /\b(?:FROM|INTO|UPDATE|JOIN)\s+[`"]?(\w+)[`"]?/i
+            metadata[:sql_table] = $1
+          end
+
+          level = (duration && duration > 1000) ? "WARN" : "DEBUG"
+          message = "SQL #{payload[:name]} #{duration}ms"
+
+          OpenTrace.log(level, message, metadata)
+        rescue StandardError
+          # Swallow
+        end
+
+        def extract_user_id(payload)
+          controller = payload[:controller_instance]
+          return unless controller
+
+          if controller.respond_to?(:current_user, true)
+            user = controller.send(:current_user)
+            user.respond_to?(:id) ? user.id : nil
+          end
+        rescue StandardError
+          nil
+        end
+
+        def extract_params(payload, metadata)
+          controller = payload[:controller_instance]
+          return unless controller
+
+          if controller.respond_to?(:request, true) && controller.request.respond_to?(:filtered_parameters)
+            params = controller.request.filtered_parameters
+            params = params.except("controller", "action")
+            metadata[:params] = truncate_hash(params, 2048) unless params.empty?
+          end
+        rescue StandardError
+          # Swallow
+        end
+
+        def truncate(str, max)
+          return str if str.nil? || str.length <= max
+          str[0, max] + "..."
+        end
+
+        def clean_backtrace(backtrace)
+          if defined?(::Rails) && ::Rails.respond_to?(:backtrace_cleaner)
+            ::Rails.backtrace_cleaner.clean(backtrace)
+          else
+            backtrace.reject { |line| line.include?("/gems/") }
+          end
+        end
+
+        def truncate_hash(hash, max_bytes)
+          json = JSON.generate(hash)
+          return hash if json.bytesize <= max_bytes
+          { _truncated: true, _size: json.bytesize }
+        rescue StandardError
+          { _truncated: true }
+        end
+      end
+    end
+  end
+end

data/lib/opentrace/version.rb

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

data/lib/opentrace.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "opentrace/version"
+require_relative "opentrace/config"
+require_relative "opentrace/client"
+require_relative "opentrace/logger"
+require_relative "opentrace/log_forwarder"
+require_relative "opentrace/middleware"
+
+module OpenTrace
+  LEVEL_VALUES = { "DEBUG" => 0, "INFO" => 1, "WARN" => 2, "ERROR" => 3, "FATAL" => 4 }.freeze
+
+  class << self
+    def configure
+      yield config
+      reset_client!
+    end
+
+    def config
+      @config ||= Config.new
+    end
+
+    def log(level, message, metadata = {})
+      return unless enabled?
+      return unless level_meets_threshold?(level)
+
+      # 1. Start with user-defined context (lowest priority)
+      meta = resolve_context
+
+      # 2. Merge caller-provided metadata (overrides context)
+      meta.merge!(metadata) if metadata.is_a?(Hash)
+
+      # 3. Static context — only fills in keys not already set
+      static_context.each { |k, v| meta[k] ||= v }
+
+      # 4. Request ID from middleware (if not already set by caller or context)
+      meta[:request_id] ||= current_request_id if current_request_id
+
+      # Extract trace_id to top level before building payload
+      trace_id = meta.delete(:trace_id)
+
+      payload = {
+        timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ"),
+        level: level.to_s.upcase,
+        service: config.service,
+        environment: config.environment,
+        message: message.to_s,
+        metadata: meta.compact
+      }
+
+      payload[:trace_id] = trace_id.to_s if trace_id
+
+      client.enqueue(payload)
+    rescue StandardError
+      # Never raise to the host app
+    end
+
+    def error(exception, metadata = {})
+      return unless enabled?
+
+      meta = metadata.is_a?(Hash) ? metadata.dup : {}
+      meta[:exception_class]   = exception.class.name
+      meta[:exception_message] = exception.message&.slice(0, 500)
+
+      if exception.backtrace
+        cleaned = if defined?(::Rails) && ::Rails.respond_to?(:backtrace_cleaner)
+                    ::Rails.backtrace_cleaner.clean(exception.backtrace)
+                  else
+                    exception.backtrace.reject { |l| l.include?("/gems/") }
+                  end
+        meta[:backtrace] = cleaned.first(15)
+      end
+
+      log("ERROR", exception.message.to_s, meta)
+    rescue StandardError
+      # Never raise to the host app
+    end
+
+    def enabled?
+      config.enabled?
+    end
+
+    def disable!
+      config.enabled = false
+    end
+
+    def enable!
+      config.enabled = true
+    end
+
+    def current_request_id
+      Thread.current[:opentrace_request_id]
+    end
+
+    def current_request_id=(id)
+      Thread.current[:opentrace_request_id] = id
+    end
+
+    def shutdown(timeout: 5)
+      @client&.shutdown(timeout: timeout)
+    end
+
+    def reset!
+      shutdown(timeout: 1)
+      @config = nil
+      @client = nil
+      @static_context = nil
+    end
+
+    private
+
+    def client
+      @client ||= Client.new(config)
+    end
+
+    def reset_client!
+      @client&.shutdown(timeout: 1)
+      @client = nil
+      @static_context = nil
+    end
+
+    def level_meets_threshold?(level)
+      LEVEL_VALUES[level.to_s.upcase].to_i >= config.min_level_value
+    end
+
+    def static_context
+      @static_context ||= {
+        hostname: config.hostname || Socket.gethostname,
+        pid: config.pid || Process.pid,
+        git_sha: config.git_sha || ENV["REVISION"] || ENV["GIT_SHA"] || ENV["HEROKU_SLUG_COMMIT"]
+      }.compact
+    rescue StandardError
+      {}
+    end
+
+    def resolve_context
+      ctx = case config.context
+            when Proc then config.context.call
+            when Hash then config.context
+            end
+      ctx.is_a?(Hash) ? ctx.dup : {}
+    rescue StandardError
+      {} # Broken proc? Swallow, never crash.
+    end
+  end
+end
+
+# Auto-load Rails integration if Rails is present
+require_relative "opentrace/rails" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: opentrace
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- OpenTrace
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Forwards structured application logs to an OpenTrace server over HTTP.
+  Designed to never affect application behavior or uptime.
+email:
+- hello@opentrace.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/opentrace.rb
+- lib/opentrace/client.rb
+- lib/opentrace/config.rb
+- lib/opentrace/log_forwarder.rb
+- lib/opentrace/logger.rb
+- lib/opentrace/middleware.rb
+- lib/opentrace/rails.rb
+- lib/opentrace/version.rb
+homepage: https://github.com/adham90/opentrace-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Thin, safe Ruby client for OpenTrace log ingestion
+test_files: []