tracelit 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58eb691b0dfacebc7072a0ee10ebc4fb88ddc5074c659211a689532bf2e86f3b
-  data.tar.gz: 9a73dad4b506173c24f6e64a17c227812a0ab90651ef3a08e493ab9a68c602e1
+  metadata.gz: bcea7249159775e00167a1a64ca7160132286dcc622c6c49a118541a8e58d66e
+  data.tar.gz: 0ea2e6000cd63cb87be8f0859f0e2bbc1c371e15e7ab33592c3c8070fd806205
 SHA512:
-  metadata.gz: 7ca34cc0206da44b31ceb865848ec08ef39f015764ae7f1f20dcf6d2b9af78820de537f6994ea48a224415350878ea9c206a54f21dd434cb37146451a04a06ba
-  data.tar.gz: 999c495a4c363af34e4bdd1671d66611c42124040f2e20172040590dbb5e6a715f9123e4550a29c2378c77d5275cede91fdc8dd46ca1830c1eabfa2b6b92eac3
+  metadata.gz: e2c7a0461048ab10e848f09adb946dfb75480a5c11662cd53295638013d83bac6f17b2f653e82c4e3a15e73bbbb16fdcc6033a0e86e434440098744a44563471
+  data.tar.gz: e1f3b97721fcbc4c35dfd8957e17da621dd02bd3027f4a69fa69eb5e5e50133be1eb78a7727a460e695125c0913249337b300e37d4e0ef569ebaa7dda0704e14

data/README.md

@@ -8,87 +8,7 @@ Official Ruby SDK for [Tracelit](https://tracelit.io) — drop-in OpenTelemetry
 
 ## Set up with AI
 
-Copy the prompt below and paste it into Cursor, Claude, ChatGPT, or any AI assistant. It contains everything the AI needs to fully integrate Tracelit into your app — gem, initializer, manual spans, custom metrics, and test guard.
-
-````
-You are integrating the Tracelit Ruby SDK into this codebase.
-
-## What Tracelit does
-Tracelit is a drop-in OpenTelemetry SDK that sends traces, metrics, and logs
-to https://tracelit.io via OTLP/HTTP. It auto-instruments Rails, Sidekiq,
-ActiveRecord, Redis, Faraday, Net::HTTP, and more with zero code changes.
-
-## Steps
-
-### 1. Add the gem
-In Gemfile add:
-  gem "tracelit"
-Then run: bundle install
-
-### 2. Create the initializer
-Create config/initializers/tracelit.rb with this content
-(replace MY_SERVICE_NAME with the actual name of this service):
-
-  Tracelit.configure do |config|
-    config.api_key      = ENV["TRACELIT_API_KEY"]
-    config.service_name = "MY_SERVICE_NAME"
-    config.environment  = ENV.fetch("RAILS_ENV", "production")
-    config.sample_rate  = 1.0
-    config.enabled      = ENV["TRACELIT_ENABLED"] != "false"
-  end
-
-For Sinatra/Rack apps also add Tracelit.start! after the configure block.
-For Rails, the Railtie calls start! automatically — no extra line needed.
-
-### 3. Disable in tests
-In config/environments/test.rb (or .env.test) add:
-  TRACELIT_ENABLED=false
-
-### 4. Add manual spans (optional)
-Wrap any important operation with a custom span:
-
-  Tracelit.tracer.in_span("describe_the_operation") do |span|
-    span.set_attribute("relevant.attribute", value.to_s)
-    do_the_work
-  end
-
-### 5. Add custom metrics (optional)
-Use counters, histograms, or gauges for business-level signals:
-
-  # Counter — increment by 1 each time an event occurs
-  counter = Tracelit.metrics.counter("my.event.count",
-    description: "...", unit: "{events}")
-  counter.add(1, attributes: { "key" => "value" })
-
-  # Histogram — record a measured value (latency, size, etc.)
-  histogram = Tracelit.metrics.histogram("my.operation.duration",
-    description: "...", unit: "ms")
-  histogram.record(elapsed_ms, attributes: { "key" => "value" })
-
-  # Gauge — record a current level (queue depth, pool size, etc.)
-  gauge = Tracelit.metrics.gauge("my.queue.depth",
-    description: "...", unit: "{items}")
-  gauge.record(current_depth, attributes: { "queue" => "default" })
-
-## What you get automatically (no code required)
-- Traces for every HTTP request, SQL query, Redis call, Sidekiq job, etc.
-- Metrics: http.server.request.count/duration, http.server.error.count,
-  db.query.duration, sidekiq.job.count/duration/error.count,
-  db.connection_pool.size/busy/idle/waiting, process.memory.rss
-- Rails.logger lines forwarded to Tracelit logs, correlated to the active trace
-- Error spans always exported even when the trace is outside the sample ratio
-
-## Configuration reference
-| Option             | Env var                  | Default                        |
-|--------------------|--------------------------|--------------------------------|
-| api_key            | TRACELIT_API_KEY         | nil (required)                 |
-| service_name       | TRACELIT_SERVICE_NAME    | Rails app name (required)      |
-| environment        | TRACELIT_ENVIRONMENT     | "production"                   |
-| endpoint           | TRACELIT_ENDPOINT        | https://ingest.tracelit.app    |
-| sample_rate        | TRACELIT_SAMPLE_RATE     | 1.0                            |
-| enabled            | TRACELIT_ENABLED         | true                           |
-| resource_attributes| —                        | {} (extra span/metric tags)    |
-````
+Want an AI assistant (Cursor, Claude, ChatGPT, etc.) to integrate Tracelit into your app automatically? Copy the contents of [`llm_prompt.txt`](./llm_prompt.txt) and paste it as your prompt. It covers gem installation, initializer setup, manual spans, custom metrics, and test guard — everything the AI needs in one shot.
 
 ---
 

data/lib/tracelit/configuration.rb

@@ -29,19 +29,40 @@ module Tracelit
     attr_accessor :resource_attributes
 
     def initialize
-      @api_key            = ENV["TRACELIT_API_KEY"]
-      @service_name       = ENV["TRACELIT_SERVICE_NAME"]
-      @environment        = ENV["TRACELIT_ENVIRONMENT"] || "production"
-      @endpoint           = ENV["TRACELIT_ENDPOINT"]    || "https://ingest.tracelit.app"
-      @sample_rate        = (ENV["TRACELIT_SAMPLE_RATE"] || "1.0").to_f
-      @enabled            = ENV["TRACELIT_ENABLED"] != "false"
+      @api_key             = ENV["TRACELIT_API_KEY"]
+      @service_name        = ENV["TRACELIT_SERVICE_NAME"]
+      @environment         = ENV["TRACELIT_ENVIRONMENT"] || "production"
+      @endpoint            = ENV["TRACELIT_ENDPOINT"]    || "https://ingest.tracelit.app"
+      @sample_rate         = (ENV["TRACELIT_SAMPLE_RATE"] || "1.0").to_f
+      @enabled             = ENV["TRACELIT_ENABLED"] != "false"
       @resource_attributes = {}
     end
 
+    # Returns an array of human-readable error strings.
+    # Empty array means the configuration is valid.
+    # Never raises — callers decide whether to warn or abort.
+    def valid?
+      errors = []
+      errors << "api_key is required" if api_key.nil? || api_key.to_s.empty?
+
+      # Fix 3: check resolved_service_name so Rails apps that rely on automatic
+      # name inference (module_parent_name) are not incorrectly flagged.
+      if resolved_service_name == "unknown-service"
+        errors << "service_name is required (set config.service_name or TRACELIT_SERVICE_NAME)"
+      end
+
+      unless sample_rate.between?(0.0, 1.0)
+        errors << "sample_rate must be between 0.0 and 1.0 (got #{sample_rate})"
+      end
+
+      errors
+    end
+
+    # Kept for backwards compatibility. Previously raised ArgumentError;
+    # now a no-op because an observability SDK must never crash the host app.
+    # Use valid? to check for configuration errors programmatically.
     def validate!
-      raise ArgumentError, "Tracelit.config.api_key is required" if api_key.nil? || api_key.empty?
-      raise ArgumentError, "Tracelit.config.service_name is required" if service_name.nil? || service_name.empty?
-      raise ArgumentError, "sample_rate must be between 0.0 and 1.0" unless sample_rate.between?(0.0, 1.0)
+      # no-op — see valid? for soft validation
     end
 
     # Infer service name from Rails application if not explicitly set.

data/lib/tracelit/instrumentation.rb

@@ -12,68 +12,107 @@ require_relative "metrics"
 
 module Tracelit
   module Instrumentation
+    SETUP_MUTEX = Mutex.new
+
     # Sets up the OpenTelemetry SDK with the Tracelit OTLP exporter.
     # Called once at application boot. Idempotent — safe to call multiple times.
+    # Never raises — a misconfigured SDK must not crash the host application.
     def self.setup(config)
-      return if @configured
-      return unless config.enabled
-
-      config.validate!
-
-      OpenTelemetry::SDK.configure do |otel|
-        # Resource attributes identify this service in Tracelit.
-        # These populate the `resource` Map column on every telemetry row.
-        otel.resource = OpenTelemetry::SDK::Resources::Resource.create(
-          {
-            OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME    => config.resolved_service_name,
-            OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT => config.environment,
-            "telemetry.sdk.language" => "ruby",
-            "telemetry.sdk.name"     => detect_framework,
-            "telemetry.sdk.version"  => Tracelit::VERSION,
-          }.merge(config.resource_attributes)
-        )
-
-        # Build the OTLP exporter once — shared by both processors
-        exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
-          endpoint: "#{config.endpoint}/v1/traces",
-          headers: {
-            "Authorization"  => "Bearer #{config.api_key}",
-            "X-Service-Name" => config.resolved_service_name,
-            "X-Environment"  => config.environment,
-          }
-        )
-
-        # Primary processor: batches and exports sampled spans
-        otel.add_span_processor(
-          OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
-        )
-
-        # Error processor: always exports error spans regardless of
-        # sampling decision — fires on_finish after status is known
-        otel.add_span_processor(
-          Tracelit::ErrorSpanProcessor.new(exporter)
-        )
-
-        # Auto-instrumentation: instruments Rails, Rack, ActiveRecord,
-        # Action View, Net::HTTP, Faraday, Redis, Sidekiq, and more.
-        # use_all() enables every installed instrumentation gem.
-        otel.use_all
+      SETUP_MUTEX.synchronize do
+        return if @configured
+        return unless config.enabled
+
+        # Fix 1: Install a clean single-line error handler before any OTel SDK
+        # calls so that internal OTel errors never dump raw stack traces into
+        # the application's logs.
+        OpenTelemetry.error_handler = lambda do |exception:, message:|
+          msg = [message, exception&.message].compact.join(" — ")
+          OpenTelemetry.logger.warn("[Tracelit] #{msg}")
+        end
+
+        # Fix 2/3: Soft validation — warn and bail out rather than raise.
+        # An observability SDK must never crash the host application.
+        errors = config.valid?
+        if errors.any?
+          OpenTelemetry.logger.warn("[Tracelit] disabled — #{errors.join(', ')}")
+          return
+        end
+
+        OpenTelemetry::SDK.configure do |otel|
+          # Resource attributes identify this service in Tracelit.
+          # These populate the `resource` Map column on every telemetry row.
+          otel.resource = OpenTelemetry::SDK::Resources::Resource.create(
+            {
+              OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME    => config.resolved_service_name,
+              OpenTelemetry::SemanticConventions::Resource::DEPLOYMENT_ENVIRONMENT => config.environment,
+              "telemetry.sdk.language" => "ruby",
+              "telemetry.sdk.name"     => detect_framework,
+              "telemetry.sdk.version"  => Tracelit::VERSION,
+            }.merge(config.resource_attributes)
+          )
+
+          # Build the OTLP exporter once — shared by both processors
+          exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
+            endpoint: "#{config.endpoint}/v1/traces",
+            headers: {
+              "Authorization"  => "Bearer #{config.api_key}",
+              "X-Service-Name" => config.resolved_service_name,
+              "X-Environment"  => config.environment,
+            }
+          )
+
+          # Primary processor: batches and exports sampled spans
+          otel.add_span_processor(
+            OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+          )
+
+          # Error processor: always exports error spans regardless of
+          # sampling decision — fires on_finish after status is known
+          otel.add_span_processor(
+            Tracelit::ErrorSpanProcessor.new(exporter)
+          )
+
+          # Auto-instrumentation: instruments Rails, Rack, ActiveRecord,
+          # Action View, Net::HTTP, Faraday, Redis, Sidekiq, and more.
+          # use_all() enables every installed instrumentation gem.
+          otel.use_all
+        end
+
+        # Set sampler after configure — Configurator does not expose
+        # sampler= in OTel SDK 1.x, must be set on the provider directly.
+        # Skip at 1.0: the default AlwaysOn sampler is correct and we do not touch it.
+        if config.sample_rate < 1.0
+          OpenTelemetry.tracer_provider.sampler = error_always_on_sampler(config.sample_rate)
+        end
+
+        @configured = true
+        @config     = config
+
+        setup_logs(config)
+        Tracelit::Metrics.setup(config)
+
+        # Fix 5: Fork safety for Puma cluster mode and Unicorn.
+        # Background threads (pollers) are killed in forked worker processes.
+        # Process._fork (Ruby 3.1+) fires in the child after every fork so we
+        # can restart pollers in each worker without touching the master.
+        install_fork_hook(config)
+
+        # Fix 9: Flush and shut down both providers gracefully on process exit
+        # so the last metrics/traces batch is not lost during deploys.
+        at_exit { shutdown }
       end
+    end
 
-      # Set sampler after configure — Configurator does not expose
-      # sampler= in OTel SDK 1.x, must be set on the provider directly.
-      # Skip at 1.0: the default AlwaysOn sampler is correct and we do not touch it.
-      if config.sample_rate < 1.0
-        OpenTelemetry.tracer_provider.sampler = error_always_on_sampler(config.sample_rate)
+    def self.reset!
+      SETUP_MUTEX.synchronize do
+        @configured = false
+        @config     = nil
       end
-
-      @configured = true
-      setup_logs(config)
-      Tracelit::Metrics.setup(config)
     end
 
-    def self.reset!
-      @configured = false
+    def self.shutdown
+      OpenTelemetry.tracer_provider.shutdown rescue nil
+      OpenTelemetry.meter_provider.shutdown  rescue nil
     end
 
     private
@@ -124,7 +163,30 @@ module Tracelit
       # Called here (after Rails boot) so Rails.logger is already initialised.
       RailsLoggerBridge.install(logger_provider)
     rescue StandardError => e
-      OpenTelemetry.logger.warn("Tracelit: failed to set up logs: #{e.message}")
+      OpenTelemetry.logger.warn("[Tracelit] failed to set up logs: #{e.message}")
+    end
+
+    # Fix 5: Register a Process._fork hook (Ruby 3.1+) so that background
+    # polling threads are restarted inside each forked Puma/Unicorn worker.
+    # In the parent (pid != 0) nothing changes. In the child (pid == 0) we
+    # restart the metric pollers so each worker reports its own stats.
+    def self.install_fork_hook(config)
+      return unless Process.respond_to?(:_fork)
+
+      hook_module = Module.new do
+        define_method(:_fork) do
+          pid = super()
+          if pid == 0
+            # We are in the child — restart pollers for this worker
+            Tracelit::Metrics.restart_pollers(config)
+          end
+          pid
+        end
+      end
+
+      Process.singleton_class.prepend(hook_module)
+    rescue StandardError => e
+      OpenTelemetry.logger.warn("[Tracelit] could not install fork hook: #{e.message}")
     end
   end
 end

data/lib/tracelit/metrics.rb

@@ -4,16 +4,16 @@ require "opentelemetry/metrics"
 require "opentelemetry-metrics-sdk"
 require "opentelemetry/exporter/otlp_metrics"
 
+# Fix 8: Set at module load time with ||= so user-configured values are never
+# clobbered. Moving this out of setup() also prevents the mutation from
+# re-firing on every setup call in test scenarios.
+ENV["OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE"] ||= "delta"
+
 module Tracelit
   module Metrics
     # Sets up the OpenTelemetry MeterProvider with OTLP exporter.
     # Called once from Instrumentation.setup after trace setup.
     def self.setup(config)
-      # Force delta temporality for all instruments. The SDK aggregation classes
-      # (Sum, ExplicitBucketHistogram) read this env var at construction time;
-      # there is no constructor keyword on MetricsExporter for this in v0.8.0.
-      ENV["OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE"] = "delta"
-
       exporter = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
         endpoint: "#{config.endpoint}/v1/metrics",
         headers: {
@@ -46,13 +46,25 @@ module Tracelit
       install_connection_pool_poller  if defined?(::ActiveRecord)
       install_memory_poller
     rescue StandardError => e
-      OpenTelemetry.logger.warn("Tracelit: failed to set up metrics: #{e.message}")
+      OpenTelemetry.logger.warn("[Tracelit] failed to set up metrics: #{e.message}")
     end
 
     def self.meter
       @meter
     end
 
+    # Fix 5 (support): Called from the Process._fork hook in Instrumentation
+    # to restart background polling threads inside each forked Puma/Unicorn
+    # worker. The parent-process threads are dead in the child; this revives them.
+    def self.restart_pollers(config)
+      @connection_pool_poller_installed = false
+      @memory_poller_installed          = false
+      install_connection_pool_poller if defined?(::ActiveRecord)
+      install_memory_poller
+    rescue StandardError => e
+      OpenTelemetry.logger.warn("[Tracelit] failed to restart pollers after fork: #{e.message}")
+    end
+
     # Exposes a counter for manual instrumentation in user code:
     #   Tracelit::Metrics.counter("orders.placed").add(1)
     def self.counter(name, description: "", unit: "")
@@ -81,7 +93,13 @@ module Tracelit
     #   http.server.request.duration — histogram in milliseconds
     #   http.server.error.count      — counter for 5xx responses
     #   db.query.duration            — histogram for ActiveRecord time per request
+    #
+    # Fix 6: guarded against double-registration so reset! + re-setup in tests
+    # or Rails code-reloading scenarios does not duplicate metric counts.
     def self.install_rails_subscriber
+      return if @rails_subscriber_installed
+      @rails_subscriber_installed = true
+
       request_counter = @meter.create_counter(
         "http.server.request.count",
         description: "Total HTTP requests processed",
@@ -107,12 +125,15 @@ module Tracelit
       )
 
       ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
-        event = ActiveSupport::Notifications::Event.new(*args)
+        event   = ActiveSupport::Notifications::Event.new(*args)
         payload = event.payload
 
         attrs = {
+          # Fix 7: use controller#action (stable, low-cardinality route template)
+          # instead of payload[:path] which contains raw IDs and causes metric
+          # cardinality explosion on apps with resource IDs in URLs.
+          "http.route"       => "#{payload[:controller]}##{payload[:action]}",
           "http.method"      => payload[:method].to_s,
-          "http.route"       => payload[:path].to_s,
           "http.status_code" => payload[:status].to_s,
           "controller"       => payload[:controller].to_s,
           "action"           => payload[:action].to_s,
@@ -137,7 +158,12 @@ module Tracelit
     # Installs a Sidekiq server middleware that emits per-job metrics.
     # Uses a dynamically defined class so the instrument references are
     # captured in the closure without global state.
+    #
+    # Fix 6: guarded against double-registration.
     def self.install_sidekiq_middleware
+      return if @sidekiq_middleware_installed
+      @sidekiq_middleware_installed = true
+
       job_counter = @meter.create_counter(
         "sidekiq.job.count",
         description: "Total Sidekiq jobs processed",
@@ -192,13 +218,18 @@ module Tracelit
         end
       end
     rescue StandardError => e
-      warn "Tracelit: failed to install Sidekiq middleware: #{e.message}"
+      OpenTelemetry.logger.warn("[Tracelit] failed to install Sidekiq middleware: #{e.message}")
     end
 
     # Polls ActiveRecord connection pool stats every 30 seconds on a daemon
     # thread and records them as gauges. Does not require a live connection
     # at install time — errors during polling are silently retried next cycle.
+    #
+    # Fix 11: version-safe pool access that works on Rails 6.0–8.x.
     def self.install_connection_pool_poller
+      return if @connection_pool_poller_installed
+      @connection_pool_poller_installed = true
+
       pool_size = @meter.create_gauge(
         "db.connection_pool.size",
         description: "Maximum connections in the pool",
@@ -228,9 +259,30 @@ module Tracelit
         loop do
           sleep 30
           begin
-            pool  = ActiveRecord::Base.connection_pool
-            stat  = pool.stat
-            attrs = { "db.system" => pool.pool_config.db_config.adapter.to_s }
+            # Fix 11a: Rails 7.2 soft-deprecated connection_pool on the base
+            # class. Use the connection handler when available; fall back for
+            # Rails 6.0 compatibility.
+            pool = if ActiveRecord::Base.respond_to?(:connection_handler)
+              ActiveRecord::Base.connection_handler
+                .retrieve_connection_pool(ActiveRecord::Base.connection_specification_name) rescue
+              ActiveRecord::Base.connection_pool
+            else
+              ActiveRecord::Base.connection_pool
+            end
+
+            next unless pool
+
+            stat = pool.stat
+
+            # Fix 11b: pool_config.db_config was added in Rails 6.1.
+            # Fall back gracefully on older setups.
+            adapter = if pool.respond_to?(:pool_config)
+              pool.pool_config.db_config.adapter.to_s rescue "unknown"
+            else
+              "unknown"
+            end
+
+            attrs = { "db.system" => adapter }
             pool_size.record(stat[:size], attributes: attrs)
             pool_busy.record(stat[:busy], attributes: attrs)
             pool_idle.record(stat[:idle], attributes: attrs)
@@ -243,12 +295,19 @@ module Tracelit
       thread.abort_on_exception = false
       thread
     rescue StandardError => e
-      warn "Tracelit: failed to install connection pool poller: #{e.message}"
+      OpenTelemetry.logger.warn("[Tracelit] failed to install connection pool poller: #{e.message}")
     end
 
-    # Polls process RSS memory every 60 seconds on a daemon thread using ps,
-    # which works on both macOS (arm64-darwin) and Linux without /proc.
+    # Polls process RSS memory every 60 seconds on a daemon thread.
+    #
+    # Fix 12: On Linux use /proc/self/status (always present, no subprocess).
+    # Fall back to `ps` on macOS/BSD. The previous implementation always used
+    # a shell backtick which spawns a child process and fails silently in
+    # minimal Docker containers that lack procps.
     def self.install_memory_poller
+      return if @memory_poller_installed
+      @memory_poller_installed = true
+
       memory_gauge = @meter.create_gauge(
         "process.memory.rss",
         description: "Process resident set size (RSS)",
@@ -262,7 +321,14 @@ module Tracelit
         loop do
           sleep 60
           begin
-            rss_kb = `ps -o rss= -p #{pid} 2>/dev/null`.strip.to_i
+            rss_kb = if File.exist?("/proc/self/status")
+              # Linux: read VmRSS from /proc — no subprocess, always available
+              File.read("/proc/self/status")[/VmRSS:\s+(\d+)/, 1].to_i
+            else
+              # macOS / BSD fallback
+              `ps -o rss= -p #{Integer(pid)} 2>/dev/null`.strip.to_i
+            end
+
             next if rss_kb == 0
 
             rss_mb = rss_kb / 1024.0
@@ -271,14 +337,14 @@ module Tracelit
               "process.runtime" => "ruby",
             })
           rescue StandardError
-            # Ignore — ps may not be available in all environments
+            # Ignore — environment may not support RSS polling
           end
         end
       end
       thread.abort_on_exception = false
       thread
     rescue StandardError => e
-      warn "Tracelit: failed to install memory poller: #{e.message}"
+      OpenTelemetry.logger.warn("[Tracelit] failed to install memory poller: #{e.message}")
     end
   end
 end

data/lib/tracelit/rails_logger_bridge.rb

@@ -39,7 +39,7 @@ module Tracelit
         )
       end
     rescue StandardError => e
-      warn "Tracelit: failed to install Rails logger bridge: #{e.message}"
+      warn "[Tracelit] failed to install Rails logger bridge: #{e.message}"
     end
 
     # OTelLogger is a Logger subclass whose add method emits an OTel LogRecord
@@ -59,6 +59,14 @@ module Tracelit
       end
 
       def add(severity, message = nil, progname = nil)
+        # Fix 10: Re-entrancy guard. OTel SDK internals can call OpenTelemetry.logger
+        # which may route back through Rails.logger → this method. Without the
+        # guard, that creates a feedback loop where every OTel internal warning
+        # triggers another OTel log emit, infinitely.
+        return if Thread.current[:tracelit_logging]
+
+        Thread.current[:tracelit_logging] = true
+
         severity_number = SEVERITY_MAP[severity.to_i] || 9
         severity_text   = ::Logger::SEV_LABEL[severity.to_i] || "ANY"
 
@@ -76,6 +84,8 @@ module Tracelit
         )
       rescue StandardError
         # Never let OTel errors surface to the application
+      ensure
+        Thread.current[:tracelit_logging] = nil
       end
       alias_method :log, :add
 

data/lib/tracelit/version.rb

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

data/tracelit.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://tracelit.io"
   spec.license       = "MIT"
 
-  spec.required_ruby_version = ">= 3.0"
+  spec.required_ruby_version = ">= 3.3"
 
   spec.files = Dir[
     "lib/**/*.rb",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tracelit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Tracelit
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-sdk
@@ -131,7 +131,7 @@ homepage: https://tracelit.io
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -139,15 +139,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Official Ruby SDK for Tracelit backend observability
 test_files: []