tracelit 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baa72093ff99cee94e4ba7221714f16691cac2907b37fc8973be2db9d58995cd
-  data.tar.gz: f18620a662414111c86741d4acf81da3add9db0577a384b973842cab3053721e
+  metadata.gz: e7f493aa08c7a1d3595be84019013d49bfa48e2daae3a653cb38b17ad702a8f4
+  data.tar.gz: 07e1c738fb2a5eee274b48f30ff6fea1b97c613b14778de081471fd1fa9ed1d0
 SHA512:
-  metadata.gz: 7a7961d36cb65b10d80b43cfecea3f767798ca5eb38d12352a8933ab2969d86d9a73d947e6d25eb0444ab1ea4374300ce215a8f34a65621b3a465f009ac24d28
-  data.tar.gz: c45e5931a15e408165258bea86c2ffd70285286a27e08e36c9dd30e0e9a705fff8ec2a2104cb35ae177a33f46379700c032bd91fd1b76d307bf2e409722df16a
+  metadata.gz: 4a9c56ef732bc424fbc7a04484c5967bba3d9714d1f520f2b017b07c9fd939b8126b6fc7ff575fe538911be951a0a0da8025dde7e50724c42bdab005703219a8
+  data.tar.gz: 728eefa18600408fcb6475ec87fe83669a0f373500bcbe2a010e2f0f0776c8bd8a5120c4f16ffcca886125be307a58ab369e38161345ed1df567464ee7777ec8

data/README.md

@@ -6,12 +6,6 @@ Official Ruby SDK for [Tracelit](https://tracelit.io) — drop-in OpenTelemetry
 
 ---
 
-## Set up with AI
-
-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.
-
----
-
 ## Installation
 
 Add to your `Gemfile` and run `bundle install`:
@@ -273,9 +267,6 @@ TRACELIT_ENABLED=false
 
 ---
 
-## Running the SDK's own tests
+## Changelog
 
-```bash
-bundle install
-bundle exec rspec
-```
+See the [release history](https://docs.tracelit.io/changelog) on the Tracelit docs.

data/lib/tracelit/error_span_processor.rb

@@ -13,12 +13,27 @@ module Tracelit
   #   so there is no double-export for sampled error spans
   #
   # NOTE: opentelemetry-sdk 1.x uses on_finish (not on_end) as the hook name.
+  #
+  # Important: this processor must never block application threads. Exporting an
+  # unsampled error span synchronously in on_finish can block request / console
+  # threads when the ingest endpoint is slow or retrying. We enqueue span data
+  # into a bounded in-memory queue and export on a background worker thread.
   class ErrorSpanProcessor
+    QUEUE_CAPACITY = 512
+    SHUTDOWN_SENTINEL = Object.new
+
     def initialize(exporter)
       @exporter = exporter
+      @queue = SizedQueue.new(QUEUE_CAPACITY)
+      @shutdown = false
+      @worker = Thread.new do
+        Thread.current[:tracelit_error_export_worker] = true
+        worker_loop
+      end
+      @worker.abort_on_exception = false
     end
 
-    def on_start(span, parent_context)
+    def on_start(_span, _parent_context)
       # nothing to do at start
     end
 
@@ -30,19 +45,71 @@ module Tracelit
       # This prevents double-export of error spans on traces that were sampled.
       return if span.context.trace_flags.sampled?
 
-      # Force-export this error span regardless of sampling decision
-      @exporter.export([span.to_span_data])
+      # Queue for background export; never block the caller.
+      enqueue(span.to_span_data)
     rescue StandardError
       # Never let processor errors propagate to the application
     end
 
     def force_flush(timeout: nil)
+      wait_for_queue_drain(timeout)
       @exporter.force_flush(timeout: timeout)
     end
 
     def shutdown(timeout: nil)
+      return if @shutdown
+      @shutdown = true
+      enqueue_shutdown_signal
+      @worker&.join(timeout || 1)
       # Do not shut down the shared exporter here —
       # the BatchSpanProcessor owns its lifecycle
     end
+
+    private
+
+    def worker_loop
+      loop do
+        item = @queue.pop
+        break if item.equal?(SHUTDOWN_SENTINEL)
+
+        begin
+          @exporter.export([item])
+        rescue StandardError
+          # Never let exporter failures crash the app worker thread
+        end
+      end
+    rescue StandardError
+      # Last-ditch guard: processor background failures must stay isolated.
+    end
+
+    def enqueue(span_data)
+      @queue.push(span_data, true)
+    rescue ThreadError
+      # Queue full — drop to protect application latency.
+    end
+
+    def enqueue_shutdown_signal
+      @queue.push(SHUTDOWN_SENTINEL, true)
+    rescue ThreadError
+      # Queue is full: drop one oldest item and retry so shutdown can proceed.
+      begin
+        @queue.pop(true)
+      rescue ThreadError
+        # no-op
+      end
+      begin
+        @queue.push(SHUTDOWN_SENTINEL, true)
+      rescue ThreadError
+        # no-op — join timeout is a final guard
+      end
+    end
+
+    def wait_for_queue_drain(timeout)
+      deadline = timeout ? Time.now + timeout : nil
+      until @queue.empty?
+        break if deadline && Time.now >= deadline
+        sleep(0.01)
+      end
+    end
   end
 end

data/lib/tracelit/metrics.rb

@@ -48,6 +48,7 @@ module Tracelit
       install_sidekiq_middleware      if defined?(::Sidekiq)
       install_connection_pool_poller  if defined?(::ActiveRecord)
       install_memory_poller
+      install_cpu_poller
     rescue StandardError => e
       OpenTelemetry.logger.warn("[Tracelit] failed to set up metrics: #{e.message}")
     end
@@ -62,8 +63,10 @@ module Tracelit
     def self.restart_pollers(config)
       @connection_pool_poller_installed = false
       @memory_poller_installed          = false
+      @cpu_poller_installed             = false
       install_connection_pool_poller if defined?(::ActiveRecord)
       install_memory_poller
+      install_cpu_poller
     rescue StandardError => e
       OpenTelemetry.logger.warn("[Tracelit] failed to restart pollers after fork: #{e.message}")
     end
@@ -349,5 +352,100 @@ module Tracelit
     rescue StandardError => e
       OpenTelemetry.logger.warn("[Tracelit] failed to install memory poller: #{e.message}")
     end
+
+    # Polls process CPU utilisation every 30 seconds on a daemon thread.
+    # Computes a percentage by tracking the delta in CPU time (user + system)
+    # against wall-clock elapsed time — same approach as the Go and Node SDKs.
+    #
+    # On Linux:  reads /proc/self/stat (utime + stime in jiffies at 100 Hz).
+    # On macOS:  reads `ps -o %cpu= -p <pid>` as a direct percentage.
+    #
+    # Emits: process.runtime.cpu.usage (%)
+    # Attributes: process.pid, process.runtime
+    def self.install_cpu_poller
+      return if @cpu_poller_installed
+      @cpu_poller_installed = true
+
+      cpu_gauge = @meter.create_gauge(
+        "process.runtime.cpu.usage",
+        description: "Process CPU utilisation percentage",
+        unit: "%"
+      )
+
+      pid      = Process.pid
+      linux    = File.exist?("/proc/self/stat")
+      interval = 30 # seconds
+
+      thread = Thread.new do
+        Thread.current[:tracelit_cpu_poller] = true
+
+        last_cpu_time  = read_cpu_time_s(pid, linux)
+        last_wall_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        loop do
+          sleep interval
+          begin
+            now      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            elapsed  = now - last_wall_time
+            cpu_time = read_cpu_time_s(pid, linux)
+
+            next if elapsed <= 0 || cpu_time.nil? || last_cpu_time.nil?
+
+            delta = cpu_time - last_cpu_time
+            last_cpu_time  = cpu_time
+            last_wall_time = now
+
+            next if delta < 0
+
+            pct = [[delta / elapsed * 100.0, 100.0].min, 0.0].max
+
+            cpu_gauge.record(pct, attributes: {
+              "process.pid"     => pid.to_s,
+              "process.runtime" => "ruby",
+            })
+          rescue StandardError
+            # Retry next cycle — never crash on a metric poll failure
+          end
+        end
+      end
+      thread.abort_on_exception = false
+      thread
+    rescue StandardError => e
+      OpenTelemetry.logger.warn("[Tracelit] failed to install CPU poller: #{e.message}")
+    end
+
+    # Returns cumulative CPU time (user + system) for this process in seconds.
+    # On Linux reads /proc/self/stat; on macOS/BSD falls back to ps %cpu
+    # which gives an instantaneous percentage instead (treated as fractional
+    # seconds over a 1-second window — good enough for a 30 s gauge).
+    def self.read_cpu_time_s(pid, linux)
+      if linux
+        stat = begin
+          File.read("/proc/self/stat")
+        rescue
+          return nil
+        end
+        # Format: pid (comm) state ppid ... utime stime ...
+        # comm can contain spaces — find last ')' and split from there.
+        after_comm = stat[stat.rindex(")").to_i + 1..]
+        return nil unless after_comm
+
+        fields = after_comm.split
+        # After ')': state(0) ppid(1) ... utime(11) stime(12)
+        utime = fields[11]&.to_i
+        stime = fields[12]&.to_i
+        return nil unless utime && stime
+
+        # Jiffies at 100 Hz → seconds
+        (utime + stime) / 100.0
+      else
+        # macOS/BSD: `ps` gives current CPU % directly.
+        # Return it as a fractional "seconds per second" proxy so the
+        # delta calculation above yields the right percentage.
+        out = `ps -o %cpu= -p #{Integer(pid)} 2>/dev/null`.strip
+        return nil if out.empty?
+        out.to_f / 100.0
+      end
+    end
   end
 end

data/lib/tracelit/version.rb

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

metadata

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