tracekit 0.1.0

data/lib/tracekit/sdk.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "opentelemetry/exporter/otlp"
+
+# Optional instrumentation - load if available
+begin
+  require "opentelemetry/instrumentation/http"
+rescue LoadError
+  # HTTP instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/net_http"
+rescue LoadError
+  # Net::HTTP instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/rails"
+rescue LoadError
+  # Rails instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/active_record"
+rescue LoadError
+  # ActiveRecord instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/pg"
+rescue LoadError
+  # PG instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/mysql2"
+rescue LoadError
+  # MySQL2 instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/redis"
+rescue LoadError
+  # Redis instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/sidekiq"
+rescue LoadError
+  # Sidekiq instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/action_view"
+rescue LoadError
+  # ActionView instrumentation not available
+end
+
+begin
+  require "opentelemetry/instrumentation/action_pack"
+rescue LoadError
+  # ActionPack instrumentation not available
+end
+
+module Tracekit
+  # Main SDK class for TraceKit Ruby SDK with OpenTelemetry integration
+  # Provides distributed tracing, metrics collection, and code monitoring capabilities
+  class SDK
+    attr_reader :config, :service_name
+
+    def initialize(config)
+      @config = config
+      @service_name = config.service_name
+
+      puts "Initializing TraceKit SDK v#{Tracekit::VERSION} for service: #{config.service_name}, environment: #{config.environment}"
+
+      # Auto-detect local UI
+      local_ui_detector = LocalUIDetector.new(config.local_ui_port)
+      if local_endpoint = local_ui_detector.local_ui_endpoint
+        puts "Local UI detected at #{local_endpoint}"
+      end
+
+      # Resolve endpoints
+      traces_endpoint = EndpointResolver.resolve(config.endpoint, "/v1/traces", config.use_ssl)
+      metrics_endpoint = EndpointResolver.resolve(config.endpoint, "/v1/metrics", config.use_ssl)
+      snapshot_base_url = EndpointResolver.resolve(config.endpoint, "", config.use_ssl)
+
+      # Initialize OpenTelemetry tracer
+      setup_tracing(traces_endpoint)
+
+      # Initialize metrics registry
+      @metrics_registry = Metrics::Registry.new(metrics_endpoint, config.api_key, config.service_name)
+
+      # Initialize snapshot client if code monitoring is enabled
+      if config.enable_code_monitoring
+        @snapshot_client = Snapshots::Client.new(
+          config.api_key,
+          snapshot_base_url,
+          config.service_name,
+          config.code_monitoring_poll_interval
+        )
+        puts "Code monitoring enabled - Snapshot client started"
+      end
+
+      puts "TraceKit SDK initialized successfully. Traces: #{traces_endpoint}, Metrics: #{metrics_endpoint}"
+    end
+
+    # Creates a Counter metric for tracking monotonically increasing values
+    # @param name [String] Metric name (e.g., "http.requests.total")
+    # @param tags [Hash] Optional tags for the metric
+    # @return [Metrics::Counter]
+    def counter(name, tags = {})
+      Metrics::Counter.new(name, tags, @metrics_registry)
+    end
+
+    # Creates a Gauge metric for tracking point-in-time values
+    # @param name [String] Metric name (e.g., "http.requests.active")
+    # @param tags [Hash] Optional tags for the metric
+    # @return [Metrics::Gauge]
+    def gauge(name, tags = {})
+      Metrics::Gauge.new(name, tags, @metrics_registry)
+    end
+
+    # Creates a Histogram metric for tracking value distributions
+    # @param name [String] Metric name (e.g., "http.request.duration")
+    # @param tags [Hash] Optional tags for the metric
+    # @return [Metrics::Histogram]
+    def histogram(name, tags = {})
+      Metrics::Histogram.new(name, tags, @metrics_registry)
+    end
+
+    # Captures a snapshot of local variables at the current code location
+    # Only active if code monitoring is enabled and there's an active breakpoint
+    # @param label [String] Stable identifier for this snapshot location
+    # @param variables [Hash] Variables to capture in the snapshot
+    def capture_snapshot(label, variables)
+      return unless @snapshot_client
+
+      caller_location = caller_locations(1, 1).first
+      @snapshot_client.capture_snapshot(label, variables, caller_location)
+    end
+
+    # Shuts down the SDK and flushes any pending data
+    def shutdown
+      @metrics_registry&.shutdown
+      @snapshot_client&.shutdown
+      OpenTelemetry.tracer_provider&.shutdown
+      puts "TraceKit SDK shutdown complete"
+    end
+
+    private
+
+    def setup_tracing(traces_endpoint)
+      OpenTelemetry::SDK.configure do |c|
+        c.service_name = @config.service_name
+        c.service_version = @config.service_version
+
+        c.resource = OpenTelemetry::SDK::Resources::Resource.create(
+          {
+            "service.name" => @config.service_name,
+            "service.version" => @config.service_version,
+            "deployment.environment" => @config.environment
+          }
+        )
+
+        # Auto-instrument libraries if available
+        # Rails framework
+        begin
+          c.use "OpenTelemetry::Instrumentation::Rails" if defined?(OpenTelemetry::Instrumentation::Rails)
+        rescue StandardError => e
+          puts "Rails instrumentation failed: #{e.message}"
+        end
+
+        # HTTP clients
+        begin
+          c.use "OpenTelemetry::Instrumentation::HTTP" if defined?(OpenTelemetry::Instrumentation::HTTP)
+        rescue StandardError
+          # HTTP instrumentation not available or failed
+        end
+
+        begin
+          c.use "OpenTelemetry::Instrumentation::NetHTTP" if defined?(OpenTelemetry::Instrumentation::NetHTTP) && defined?(Net::HTTP)
+        rescue StandardError
+          # NetHTTP instrumentation not available or failed
+        end
+
+        # Database - ActiveRecord
+        begin
+          c.use "OpenTelemetry::Instrumentation::ActiveRecord" if defined?(OpenTelemetry::Instrumentation::ActiveRecord)
+        rescue StandardError
+          # ActiveRecord instrumentation not available or failed
+        end
+
+        # Database - PG (PostgreSQL)
+        begin
+          c.use "OpenTelemetry::Instrumentation::PG" if defined?(OpenTelemetry::Instrumentation::PG)
+        rescue StandardError
+          # PG instrumentation not available or failed
+        end
+
+        # Database - MySQL2
+        begin
+          c.use "OpenTelemetry::Instrumentation::Mysql2" if defined?(OpenTelemetry::Instrumentation::Mysql2)
+        rescue StandardError
+          # MySQL2 instrumentation not available or failed
+        end
+
+        # Redis
+        begin
+          c.use "OpenTelemetry::Instrumentation::Redis" if defined?(OpenTelemetry::Instrumentation::Redis)
+        rescue StandardError
+          # Redis instrumentation not available or failed
+        end
+
+        # Sidekiq
+        begin
+          c.use "OpenTelemetry::Instrumentation::Sidekiq" if defined?(OpenTelemetry::Instrumentation::Sidekiq)
+        rescue StandardError
+          # Sidekiq instrumentation not available or failed
+        end
+
+        # Rails components
+        begin
+          c.use "OpenTelemetry::Instrumentation::ActionView" if defined?(OpenTelemetry::Instrumentation::ActionView)
+        rescue StandardError
+          # ActionView instrumentation not available or failed
+        end
+
+        begin
+          c.use "OpenTelemetry::Instrumentation::ActionPack" if defined?(OpenTelemetry::Instrumentation::ActionPack)
+        rescue StandardError
+          # ActionPack instrumentation not available or failed
+        end
+
+        c.add_span_processor(
+          OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+            OpenTelemetry::Exporter::OTLP::Exporter.new(
+              endpoint: traces_endpoint,
+              headers: { "X-API-Key" => @config.api_key },
+              compression: "none"  # Disable compression to match Go SDK default behavior
+            )
+          )
+        )
+
+        # Note: Sampler configuration API changed in OpenTelemetry 1.x
+        # For now, using default sampler (ALWAYS_ON)
+        # TODO: Implement custom sampler if needed via span processor
+      end
+    end
+
+    class << self
+      # Global SDK instance
+      attr_accessor :instance
+
+      # Creates and configures the SDK singleton
+      # @param config [Config] SDK configuration
+      # @return [SDK]
+      def configure(config)
+        @instance = new(config)
+      end
+
+      # Returns the global SDK instance
+      # @return [SDK, nil]
+      def current
+        @instance
+      end
+    end
+  end
+end

data/lib/tracekit/security/detector.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Security
+    # Detects and redacts sensitive data (PII, credentials) from variable snapshots
+    class Detector
+      SecurityFlag = Struct.new(:type, :category, :severity, :variable, :redacted, keyword_init: true)
+      ScanResult = Struct.new(:sanitized_variables, :security_flags, keyword_init: true)
+
+      def scan(variables)
+        sanitized = {}
+        flags = []
+
+        variables.each do |key, value|
+          sanitized_value, detected_flags = scan_value(key, value)
+          sanitized[key] = sanitized_value
+          flags.concat(detected_flags)
+        end
+
+        ScanResult.new(sanitized_variables: sanitized, security_flags: flags)
+      end
+
+      private
+
+      def scan_value(key, value)
+        return ["[NULL]", []] if value.nil?
+
+        flags = []
+        value_str = value.to_s
+
+        # Check PII
+        if Patterns::EMAIL.match?(value_str)
+          flags << SecurityFlag.new(type: "pii", category: "email", severity: "medium", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::SSN.match?(value_str)
+          flags << SecurityFlag.new(type: "pii", category: "ssn", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::CREDIT_CARD.match?(value_str)
+          flags << SecurityFlag.new(type: "pii", category: "credit_card", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::PHONE.match?(value_str)
+          flags << SecurityFlag.new(type: "pii", category: "phone", severity: "medium", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        # Check Credentials
+        if Patterns::API_KEY.match?(value_str)
+          flags << SecurityFlag.new(type: "credential", category: "api_key", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::AWS_KEY.match?(value_str)
+          flags << SecurityFlag.new(type: "credential", category: "aws_key", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::STRIPE_KEY.match?(value_str)
+          flags << SecurityFlag.new(type: "credential", category: "stripe_key", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::PASSWORD.match?(value_str)
+          flags << SecurityFlag.new(type: "credential", category: "password", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::JWT.match?(value_str)
+          flags << SecurityFlag.new(type: "credential", category: "jwt", severity: "high", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        if Patterns::PRIVATE_KEY.match?(value_str)
+          flags << SecurityFlag.new(type: "credential", category: "private_key", severity: "critical", variable: key, redacted: true)
+          return ["[REDACTED]", flags]
+        end
+
+        [value, flags]
+      end
+    end
+  end
+end

data/lib/tracekit/security/patterns.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Security
+    # Regex patterns for detecting sensitive data in snapshots
+    module Patterns
+      # PII Patterns
+      EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/
+      SSN = /\b\d{3}-\d{2}-\d{4}\b/
+      CREDIT_CARD = /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/
+      PHONE = /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/
+
+      # Credential Patterns
+      API_KEY = /(api[_-]?key|apikey|access[_-]?key)[\s:=]+['"  ]?([a-zA-Z0-9_-]{20,})['"]?/i
+      AWS_KEY = /AKIA[0-9A-Z]{16}/
+      STRIPE_KEY = /sk_live_[0-9a-zA-Z]{24}/
+      PASSWORD = /(password|pwd|pass)[\s:=]+['" ]?([^\s'" ]{6,})['"]?/i
+      JWT = /eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/
+      PRIVATE_KEY = /-----BEGIN (RSA |EC )?PRIVATE KEY-----/
+    end
+  end
+end

data/lib/tracekit/snapshots/client.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "concurrent/hash"
+require "concurrent/timer_task"
+
+module Tracekit
+  module Snapshots
+    # Client for code monitoring - polls breakpoints and captures snapshots
+    class Client
+      def initialize(api_key, base_url, service_name, poll_interval_seconds = 30)
+        @api_key = api_key
+        @base_url = base_url
+        @service_name = service_name
+        @security_detector = Security::Detector.new
+        @breakpoints_cache = Concurrent::Hash.new
+        @registration_cache = Concurrent::Hash.new
+
+        # Start polling timer
+        @poll_task = Concurrent::TimerTask.new(execution_interval: poll_interval_seconds) do
+          fetch_active_breakpoints
+        end
+        @poll_task.execute
+
+        # Initial fetch
+        fetch_active_breakpoints
+      end
+
+      # Captures a snapshot at the caller's location
+      def capture_snapshot(label, variables, caller_location = nil)
+        # Extract caller information
+        caller_location ||= caller_locations(1, 1).first
+        file_path = caller_location.path
+        line_number = caller_location.lineno
+        function_name = caller_location.label
+
+        # Auto-register breakpoint
+        auto_register_breakpoint(file_path, line_number, function_name, label)
+
+        # Check if breakpoint is active
+        location_key = "#{function_name}:#{label}"
+        breakpoint = @breakpoints_cache[location_key] || @breakpoints_cache["#{file_path}:#{line_number}"]
+
+        return unless breakpoint
+        return unless breakpoint.enabled
+        return if breakpoint.expire_at && Time.now > breakpoint.expire_at
+        return if breakpoint.max_captures > 0 && breakpoint.capture_count >= breakpoint.max_captures
+
+        # Scan for security issues
+        scan_result = @security_detector.scan(variables)
+
+        # Get trace context from OpenTelemetry
+        trace_id = nil
+        span_id = nil
+        if defined?(OpenTelemetry::Trace)
+          span = OpenTelemetry::Trace.current_span
+          if span && span.context.valid?
+            trace_id = span.context.hex_trace_id
+            span_id = span.context.hex_span_id
+          end
+        end
+
+        # Get stack trace
+        stack_trace = caller.join("\n")
+
+        snapshot = Snapshot.new(
+          breakpoint_id: breakpoint.id,
+          service_name: @service_name,
+          file_path: file_path,
+          function_name: function_name,
+          label: label,
+          line_number: line_number,
+          variables: scan_result.sanitized_variables,
+          security_flags: scan_result.security_flags.map(&:to_h),
+          stack_trace: stack_trace,
+          trace_id: trace_id,
+          span_id: span_id,
+          captured_at: Time.now.utc.iso8601
+        )
+
+        # Submit asynchronously
+        Thread.new { submit_snapshot(snapshot) }
+      end
+
+      # Shuts down the client
+      def shutdown
+        @poll_task&.shutdown
+      end
+
+      private
+
+      def fetch_active_breakpoints
+        url = "#{@base_url}/sdk/snapshots/active/#{@service_name}"
+        uri = URI(url)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = 10
+
+        request = Net::HTTP::Get.new(uri.path)
+        request["X-API-Key"] = @api_key
+
+        response = http.request(request)
+        return unless response.is_a?(Net::HTTPSuccess)
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        update_breakpoint_cache(data[:breakpoints]) if data[:breakpoints]
+      rescue => e
+        # Silently ignore errors fetching breakpoints
+        warn "Error fetching breakpoints: #{e.message}" if ENV["DEBUG"]
+      end
+
+      def update_breakpoint_cache(breakpoints)
+        @breakpoints_cache.clear
+
+        breakpoints.each do |bp_data|
+          bp = BreakpointConfig.new(
+            id: bp_data[:id],
+            file_path: bp_data[:file_path],
+            line_number: bp_data[:line_number],
+            function_name: bp_data[:function_name],
+            label: bp_data[:label],
+            enabled: bp_data[:enabled],
+            max_captures: bp_data[:max_captures] || 0,
+            capture_count: bp_data[:capture_count] || 0,
+            expire_at: bp_data[:expire_at] ? Time.parse(bp_data[:expire_at]) : nil
+          )
+
+          # Key by function + label
+          if bp.label && bp.function_name
+            label_key = "#{bp.function_name}:#{bp.label}"
+            @breakpoints_cache[label_key] = bp
+          end
+
+          # Key by file + line
+          line_key = "#{bp.file_path}:#{bp.line_number}"
+          @breakpoints_cache[line_key] = bp
+        end
+      end
+
+      def auto_register_breakpoint(file_path, line_number, function_name, label)
+        reg_key = "#{function_name}:#{label}"
+        return if @registration_cache[reg_key]
+
+        @registration_cache[reg_key] = true
+
+        Thread.new do
+          begin
+            registration = {
+              service_name: @service_name,
+              file_path: file_path,
+              line_number: line_number,
+              function_name: function_name,
+              label: label
+            }
+
+            uri = URI("#{@base_url}/sdk/snapshots/auto-register")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = uri.scheme == "https"
+            http.read_timeout = 10
+
+            request = Net::HTTP::Post.new(uri.path, {
+              "Content-Type" => "application/json",
+              "X-API-Key" => @api_key
+            })
+            request.body = JSON.generate(registration)
+
+            response = http.request(request)
+
+            # Refresh breakpoints cache after successful registration
+            if response.is_a?(Net::HTTPSuccess)
+              sleep 0.5 # Small delay for backend processing
+              fetch_active_breakpoints
+            end
+          rescue => e
+            # Silently ignore auto-registration errors
+            warn "Error auto-registering breakpoint: #{e.message}" if ENV["DEBUG"]
+          end
+        end
+      end
+
+      def submit_snapshot(snapshot)
+        uri = URI("#{@base_url}/sdk/snapshots/capture")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri.path, {
+          "Content-Type" => "application/json",
+          "X-API-Key" => @api_key
+        })
+        request.body = JSON.generate(snapshot.to_h)
+
+        http.request(request)
+      rescue => e
+        # Silently ignore snapshot submission errors
+        warn "Error submitting snapshot: #{e.message}" if ENV["DEBUG"]
+      end
+    end
+  end
+end

data/lib/tracekit/snapshots/models.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Snapshots
+    # Represents a breakpoint configuration from the backend
+    BreakpointConfig = Struct.new(
+      :id, :file_path, :line_number, :function_name, :label,
+      :enabled, :max_captures, :capture_count, :expire_at,
+      keyword_init: true
+    )
+
+    # Represents a snapshot capture
+    Snapshot = Struct.new(
+      :breakpoint_id, :service_name, :file_path, :function_name, :label,
+      :line_number, :variables, :security_flags, :stack_trace,
+      :trace_id, :span_id, :captured_at,
+      keyword_init: true
+    )
+
+    # Represents a breakpoint registration request
+    BreakpointRegistration = Struct.new(
+      :service_name, :file_path, :line_number, :function_name, :label,
+      keyword_init: true
+    )
+  end
+end

data/lib/tracekit/version.rb

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