tracestax 0.1.0

data/lib/tracestax/good_job.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module TraceStax
+  module GoodJob
+    # ActiveSupport::Notifications subscriber for Good Job.
+    #
+    # Usage:
+    #   TraceStax::GoodJob.subscribe!
+    def self.subscribe!
+      ActiveSupport::Notifications.subscribe("perform.good_job") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        handle_perform(event)
+      end
+    end
+
+    def self.handle_perform(event)
+      client = TraceStax::Client.instance
+      payload = event.payload
+      job = payload[:good_job] || payload[:job]
+
+      task_name = job&.job_class || job&.class&.name || "unknown"
+      job_id = job&.good_job_concurrency_key || job&.provider_job_id || SecureRandom.uuid
+      queue = job&.queue_name || "default"
+      attempt = (job&.executions || 0) + 1
+      duration_ms = (event.duration || 0).round
+
+      worker_info = {
+        key: "#{Socket.gethostname}:#{Process.pid}",
+        hostname: Socket.gethostname,
+        pid: Process.pid,
+        queues: [queue],
+      }
+
+      error = event.payload[:error] || event.payload[:exception_object]
+      status = error ? "failed" : "succeeded"
+
+      event_payload = {
+        type: "task_event", framework: "good_job", language: "ruby",
+        sdk_version: TraceStax::VERSION, status: status,
+        worker: worker_info,
+        task: { name: task_name, id: job_id.to_s, queue: queue, attempt: attempt },
+        metrics: { duration_ms: duration_ms },
+      }
+
+      if error
+        event_payload[:error] = {
+          type: error.class.name,
+          message: error.message,
+          stack_trace: error.backtrace&.first(20)&.join("\n"),
+        }
+      end
+
+      client.send_event(event_payload)
+    rescue => e
+      # Never crash the host app
+      $stderr.puts "[tracestax] GoodJob tracking error: #{e.message}"
+    end
+  end
+end

data/lib/tracestax/resque.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module TraceStax
+  module Resque
+    # Include this module in your Resque job classes, or use the global hook.
+    #
+    # Usage (per-job):
+    #   class OrderProcessor
+    #     extend TraceStax::Resque::Job
+    #     def self.perform(order_id) ... end
+    #   end
+    #
+    # Usage (global — all jobs):
+    #   Resque.before_fork { TraceStax::Client.instance.start }
+    #   Resque::Job.send(:extend, TraceStax::Resque::Job)
+    module Job
+      def around_perform_tracestax(*args)
+        client = TraceStax::Client.instance
+        job_id = args.first&.to_s || SecureRandom.uuid
+        task_name = self.name
+        queue = ::Resque.queue_from_class(self) || "default"
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        client.send_event({
+          type: "task_event",
+          framework: "resque",
+          language: "ruby",
+          sdk_version: TraceStax::VERSION,
+          status: "started",
+          worker: build_worker_info,
+          task: { name: task_name, id: job_id, queue: queue.to_s, attempt: 1 },
+          metrics: {},
+        })
+
+        begin
+          yield
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+          client.send_event({
+            type: "task_event",
+            framework: "resque",
+            language: "ruby",
+            sdk_version: TraceStax::VERSION,
+            status: "succeeded",
+            worker: build_worker_info,
+            task: { name: task_name, id: job_id, queue: queue.to_s, attempt: 1 },
+            metrics: { duration_ms: duration_ms },
+          })
+        rescue => e
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+          client.send_event({
+            type: "task_event",
+            framework: "resque",
+            language: "ruby",
+            sdk_version: TraceStax::VERSION,
+            status: "failed",
+            worker: build_worker_info,
+            task: { name: task_name, id: job_id, queue: queue.to_s, attempt: 1 },
+            metrics: { duration_ms: duration_ms },
+            error: { type: e.class.name, message: e.message, stack_trace: e.backtrace&.first(20)&.join("\n") },
+          })
+          raise
+        end
+      end
+
+      private
+
+      def build_worker_info
+        {
+          key: "#{Socket.gethostname}:#{Process.pid}",
+          hostname: Socket.gethostname,
+          pid: Process.pid,
+          queues: [::Resque.queue_from_class(self) || "default"].map(&:to_s),
+        }
+      end
+    end
+  end
+end

data/lib/tracestax/sidekiq/client.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "singleton"
+
+module TraceStax
+  module Sidekiq
+    class Client
+      include Singleton
+
+      def initialize
+        @queue   = Queue.new
+        @mutex   = Mutex.new
+        @running = false
+      end
+
+      def start
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @thread = Thread.new { flush_loop }
+          @thread.abort_on_exception = false
+
+          at_exit { shutdown }
+        end
+      end
+
+      def send_event(payload)
+        return unless config.enabled
+
+        if config.dry_run
+          puts "[tracestax dry-run] #{payload.to_json}"
+          return
+        end
+
+        @queue.push(payload)
+      end
+
+      def flush
+        batch = []
+        batch.push(@queue.pop(true)) while !@queue.empty? && batch.size < config.max_batch_size
+        return if batch.empty?
+
+        conn = Faraday.new(url: config.endpoint) do |f|
+          f.request :json
+          f.adapter Faraday.default_adapter
+        end
+
+        batch.each do |event|
+          endpoint = case event[:type]
+                     when "task_event" then "/v1/ingest"
+                     when "snapshot"   then "/v1/snapshot"
+                     when "heartbeat"  then "/v1/heartbeat"
+                     else "/v1/ingest"
+                     end
+
+          conn.post(endpoint) do |req|
+            req.headers["Authorization"] = "Bearer #{config.api_key}"
+            req.headers["Content-Type"]  = "application/json"
+            req.body = event.to_json
+          end
+        rescue StandardError
+          # Swallow send errors — monitoring should never break the app
+        end
+      rescue ThreadError
+        # Queue empty
+      end
+
+      def shutdown
+        @mutex.synchronize { @running = false }
+        flush
+      end
+
+      private
+
+      def config
+        TraceStax::Sidekiq.configuration
+      end
+
+      def flush_loop
+        while @running
+          sleep(config.flush_interval)
+          flush
+        end
+      rescue StandardError
+        # Swallow unexpected errors in the background thread
+      end
+    end
+  end
+end

data/lib/tracestax/sidekiq/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TraceStax
+  module Sidekiq
+    class Configuration
+      attr_accessor :api_key, :endpoint, :flush_interval, :max_batch_size, :enabled, :dry_run
+
+      def initialize
+        @endpoint       = "https://ingest.tracestax.com"
+        @flush_interval = 5.0
+        @max_batch_size = 100
+        @enabled        = ENV["TRACESTAX_ENABLED"] != "false"
+        @dry_run        = ENV["TRACESTAX_DRY_RUN"] == "true"
+      end
+
+      def validate!
+        raise Error, "api_key is required" if api_key.nil? || api_key.empty?
+      end
+    end
+  end
+end

data/lib/tracestax/sidekiq/heartbeat_poller.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module TraceStax
+  module Sidekiq
+    class HeartbeatPoller
+      INTERVAL = 60 # seconds
+
+      def self.start
+        new.start
+      end
+
+      def start
+        @thread = Thread.new { poll_loop }
+        @thread.abort_on_exception = false
+        self
+      end
+
+      private
+
+      def poll_loop
+        loop do
+          sleep(INTERVAL)
+          send_heartbeat
+          send_snapshots
+        end
+      rescue StandardError
+        # Swallow unexpected errors — monitoring should never break the app
+      end
+
+      def send_heartbeat
+        payload = {
+          framework:   "sidekiq",
+          language:    "ruby",
+          sdk_version: TraceStax::Sidekiq::VERSION,
+          timestamp:   Time.now.utc.iso8601,
+          worker: {
+            key:         "#{Socket.gethostname}:#{Process.pid}",
+            hostname:    Socket.gethostname,
+            pid:         Process.pid,
+            queues:      sidekiq_queue_names,
+            concurrency: sidekiq_concurrency
+          }
+        }
+
+        TraceStax::Sidekiq.client.send_event(payload.merge(type: "heartbeat"))
+      rescue StandardError
+        # Swallow instrumentation errors — monitoring should never break the app
+      end
+
+      def send_snapshots
+        ::Sidekiq::Queue.all.each do |q|
+          payload = {
+            framework:         "sidekiq",
+            language:          "ruby",
+            sdk_version:       TraceStax::Sidekiq::VERSION,
+            timestamp:         Time.now.utc.iso8601,
+            type:              "snapshot",
+            queue_name:        q.name,
+            depth:             q.size,
+            throughput_per_min: q.latency.round(3)
+          }
+          TraceStax::Sidekiq.client.send_event(payload)
+        end
+      rescue StandardError
+        # Swallow instrumentation errors — monitoring should never break the app
+      end
+
+      def sidekiq_concurrency
+        ::Sidekiq.default_configuration[:concurrency]
+      rescue StandardError
+        nil
+      end
+
+      def sidekiq_queue_names
+        ::Sidekiq::Queue.all.map(&:name)
+      rescue StandardError
+        []
+      end
+
+      def queue_stats
+        ::Sidekiq::Queue.all.map do |q|
+          { name: q.name, depth: q.size, latency: q.latency.round(3) }
+        end
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/tracestax/sidekiq/server_middleware.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module TraceStax
+  module Sidekiq
+    class ServerMiddleware
+      def call(worker, job, queue)
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          yield
+        rescue => err
+          duration_ms = elapsed_ms(start_time)
+          send_task_event(worker, job, queue, "failed", duration_ms, err)
+          raise
+        end
+
+        duration_ms = elapsed_ms(start_time)
+        send_task_event(worker, job, queue, "succeeded", duration_ms, nil)
+      end
+
+      private
+
+      def elapsed_ms(start_time)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+      end
+
+      def send_task_event(worker, job, queue, status, duration_ms, err)
+        payload = {
+          framework:   "sidekiq",
+          language:    "ruby",
+          sdk_version: TraceStax::Sidekiq::VERSION,
+          type:        "task_event",
+          worker: {
+            key:         "#{Socket.gethostname}:#{Process.pid}",
+            hostname:    Socket.gethostname,
+            pid:         Process.pid,
+            concurrency: sidekiq_concurrency,
+            queues:      sidekiq_queue_names
+          },
+          task: {
+            name:     job_class_name(worker, job),
+            id:       job["jid"].to_s,
+            queue:    queue.to_s,
+            attempt:  (job["retry_count"] || 0) + 1,
+            chain_id: job["bid"]
+          }.compact,
+          status:  status,
+          metrics: { duration_ms: duration_ms }
+        }
+
+        if err
+          payload[:error] = {
+            type:        err.class.name,
+            message:     err.message,
+            stack_trace: err.backtrace&.first(20)&.join("\n")
+          }
+        end
+
+        TraceStax::Sidekiq.client.send_event(payload)
+      rescue StandardError
+        # Swallow instrumentation errors — monitoring should never break the app
+      end
+
+      def job_class_name(worker, job)
+        # Prefer the worker object's class name; fall back to the job hash's "class" key
+        if worker.respond_to?(:class) && worker.class.name && worker.class.name != "Object"
+          worker.class.name
+        else
+          job["class"].to_s
+        end
+      end
+
+      def sidekiq_concurrency
+        ::Sidekiq.default_configuration[:concurrency]
+      rescue StandardError
+        nil
+      end
+
+      def sidekiq_queue_names
+        ::Sidekiq::Queue.all.map(&:name)
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/tracestax/sidekiq/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TraceStax
+  module Sidekiq
+    VERSION = "0.1.0"
+  end
+end

data/lib/tracestax/sidekiq.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "sidekiq/version"
+require_relative "sidekiq/configuration"
+require_relative "sidekiq/client"
+require_relative "sidekiq/server_middleware"
+require_relative "sidekiq/heartbeat_poller"
+
+module TraceStax
+  module Sidekiq
+    class Error < StandardError; end
+
+    class << self
+      attr_accessor :configuration
+
+      # Configure the TraceStax Sidekiq integration.
+      #
+      #   TraceStax::Sidekiq.configure do |config|
+      #     config.api_key = ENV["TRACESTAX_API_KEY"]
+      #   end
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration)
+        configuration.validate!
+        Client.instance.start
+      end
+
+      def client
+        Client.instance
+      end
+
+      # Install TraceStax into the Sidekiq server middleware chain and start the
+      # heartbeat poller.  Called automatically when you use `install!`; safe to
+      # call more than once.
+      def install!
+        ::Sidekiq.configure_server do |config|
+          config.server_middleware do |chain|
+            chain.prepend TraceStax::Sidekiq::ServerMiddleware
+          end
+        end
+
+        HeartbeatPoller.start
+      end
+    end
+  end
+end

data/lib/tracestax/solid_queue.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module TraceStax
+  class SolidQueueSubscriber
+    def self.attach
+      return unless defined?(SolidQueue)
+
+      ActiveSupport::Notifications.subscribe("perform_start.solid_queue") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Thread.current[:tracestax_start_time] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        Thread.current[:tracestax_job_data] = event.payload
+      end
+
+      ActiveSupport::Notifications.subscribe("perform.solid_queue") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        start_time = Thread.current[:tracestax_start_time]
+        job_data = Thread.current[:tracestax_job_data] || {}
+        duration_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round : nil
+
+        payload = {
+          framework: "solid_queue",
+          language: "ruby",
+          sdk_version: TraceStax::VERSION,
+          type: "task_event",
+          worker: {
+            key: "#{Socket.gethostname}:#{Process.pid}",
+            hostname: Socket.gethostname,
+            pid: Process.pid,
+            concurrency: SolidQueue.config&.dig(:workers, :threads) || 1,
+            queues: Array(job_data[:queue_name] || "default")
+          },
+          task: {
+            name: job_data[:job_class] || "unknown",
+            id: job_data[:job_id]&.to_s || SecureRandom.uuid,
+            queue: job_data[:queue_name] || "default",
+            attempt: job_data[:executions] || 1
+          },
+          status: event.payload[:error] ? "failed" : "succeeded",
+          metrics: {
+            duration_ms: duration_ms
+          }
+        }
+
+        if event.payload[:error]
+          err = event.payload[:error]
+          payload[:error] = {
+            type: err.class.name,
+            message: err.message,
+            stack_trace: err.backtrace&.first(20)&.join("\n")
+          }
+        end
+
+        TraceStax.client.send_event(payload)
+      end
+    end
+  end
+end

data/lib/tracestax/version.rb

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

data/lib/tracestax.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "tracestax/client"
+require_relative "tracestax/configuration"
+require_relative "tracestax/version"
+
+# Framework integrations are NOT auto-required — load only what you need:
+#
+#   require "tracestax/sidekiq"       # Sidekiq 6.x / 7.x
+#   require "tracestax/solid_queue"   # Solid Queue (Rails 8)
+#   require "tracestax/resque"        # Resque 2.x
+#   require "tracestax/delayed_job"   # Delayed::Job 4.x
+#   require "tracestax/good_job"      # Good Job 3.x+
+
+module TraceStax
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+      configuration.validate!
+      Client.instance.start
+    end
+
+    def client
+      Client.instance
+    end
+  end
+end