tracelit 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e3ee121cb2164e53dfa5ba358f760e84686bdbb26c94196ee26fac6ed40f9ca
-  data.tar.gz: 8eb2b4285c0b360098b412f22a9f629c064cc4b35aa83dff2e5ae095734b6e27
+  metadata.gz: 86262dd99fea01fd4acc26d9f1ab54b5915773a6cceb6b6c8ee6ed7f5dcda873
+  data.tar.gz: 0c20478da0332cee72943c947e35fd47a298406672d719cccd2ee7a437261307
 SHA512:
-  metadata.gz: 25ce2b06f568a1f4553269ffe52366e2b63aab998f03ab2fbb0f33de52a39901ad32268b99a1bd2e61b9cc9c2e81825e66771986741f9176e4a6e4c8890da848
-  data.tar.gz: 542aa2c3a219425fcfddaa44fada6e37610020a82819f0dfd14808a22fd8abadd0dfe0280cd3f5a7cfdaaaa2662a17658b0105f46baba80a2d9164506e084a12
+  metadata.gz: 3a5dfff925583f87d19772888916e24d7864ab4b63b341a53393db72fe0bdf7b4caaaf582a88a5583edb2167f399d498dfd055c76ad42c228ba7c4acbe6baa28
+  data.tar.gz: 22143eb50a74f98d630e227e4aa695685b06914ce4ef72b8b5eaa84a142a5da20793a5f1e5fd694fab210dbda53d0bb358c90dbc9a19331b63d5f903f80df9bd

data/lib/tracelit/configuration.rb

@@ -29,19 +29,68 @@ 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
 
+    # Resolves the current commit SHA with zero developer friction.
+    # Checks common CI/CD environment variables first, then falls back
+    # to running `git rev-parse HEAD` in the project directory.
+    def resolved_commit_sha
+      return @resolved_commit_sha if defined?(@resolved_commit_sha)
+
+      sha = ENV["COMMIT_SHA"] ||
+            ENV["GIT_COMMIT_SHA"] ||
+            ENV["GIT_COMMIT"] ||
+            ENV["GITHUB_SHA"] ||
+            ENV["HEROKU_SLUG_COMMIT"] ||
+            ENV["SOURCE_VERSION"] ||        # Heroku alt
+            ENV["RENDER_GIT_COMMIT"] ||     # Render
+            ENV["FLY_APP_VERSION"] ||       # Fly.io
+            ENV["RAILWAY_GIT_COMMIT_SHA"]   # Railway
+
+      if sha.nil? || sha.empty?
+        begin
+          sha = `git rev-parse HEAD 2>/dev/null`.strip
+          sha = nil if sha.empty?
+        rescue StandardError
+          sha = nil
+        end
+      end
+
+      @resolved_commit_sha = sha
+    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,111 @@ 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(
-          {
+      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.
+          base_attrs = {
             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
+          sha = config.resolved_commit_sha
+          base_attrs["service.commit_sha"] = sha if sha
+
+          otel.resource = OpenTelemetry::SDK::Resources::Resource.create(
+            base_attrs.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 +167,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.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tracelit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Tracelit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-sdk