tracekit 0.1.0

data/lib/tracekit/config.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Tracekit
+  # Configuration for the TraceKit SDK
+  # Follows the builder pattern with sensible defaults
+  class Config
+    attr_reader :api_key, :service_name, :endpoint, :use_ssl, :environment,
+                :service_version, :enable_code_monitoring,
+                :code_monitoring_poll_interval, :local_ui_port, :sampling_rate
+
+    def initialize(builder)
+      @api_key = builder.api_key
+      @service_name = builder.service_name
+      @endpoint = builder.endpoint || "app.tracekit.dev"
+      @use_ssl = builder.use_ssl.nil? ? true : builder.use_ssl
+      @environment = builder.environment || "production"
+      @service_version = builder.service_version || "1.0.0"
+      @enable_code_monitoring = builder.enable_code_monitoring.nil? ? true : builder.enable_code_monitoring
+      @code_monitoring_poll_interval = builder.code_monitoring_poll_interval || 30
+      @local_ui_port = builder.local_ui_port || 9999
+      @sampling_rate = builder.sampling_rate || 1.0
+
+      validate!
+      freeze # Make configuration immutable
+    end
+
+    # Builder pattern for fluent API
+    def self.build
+      builder = Builder.new
+      yield(builder) if block_given?
+      new(builder)
+    end
+
+    # Builder class for constructing Config instances
+    class Builder
+      attr_accessor :api_key, :service_name, :endpoint, :use_ssl, :environment,
+                    :service_version, :enable_code_monitoring,
+                    :code_monitoring_poll_interval, :local_ui_port, :sampling_rate
+
+      def initialize
+        # Set defaults in builder
+        @endpoint = "app.tracekit.dev"
+        @use_ssl = true
+        @environment = "production"
+        @service_version = "1.0.0"
+        @enable_code_monitoring = true
+        @code_monitoring_poll_interval = 30
+        @local_ui_port = 9999
+        @sampling_rate = 1.0
+      end
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.to_s.empty?
+      raise ArgumentError, "service_name is required" if service_name.nil? || service_name.to_s.empty?
+      raise ArgumentError, "sampling_rate must be between 0.0 and 1.0" unless (0.0..1.0).cover?(sampling_rate)
+    end
+  end
+end

data/lib/tracekit/endpoint_resolver.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Tracekit
+  # Resolves endpoint URLs for different TraceKit services (traces, metrics, snapshots)
+  # Implements the same logic as .NET, Go, and Java SDKs for consistency
+  #
+  # CRITICAL: This must match the exact behavior across all SDK implementations
+  class EndpointResolver
+    class << self
+      # Resolves a full endpoint URL from a base endpoint and path
+      #
+      # @param endpoint [String] The base endpoint (can be host, host with scheme, or full URL)
+      # @param path [String] The path to append (e.g., "/v1/traces", "/v1/metrics", or "")
+      # @param use_ssl [Boolean] Whether to use HTTPS (ignored if endpoint already has a scheme)
+      # @return [String] The resolved endpoint URL
+      #
+      # @example
+      #   resolve("app.tracekit.dev", "/v1/traces", true)
+      #   # => "https://app.tracekit.dev/v1/traces"
+      #
+      #   resolve("http://localhost:8081", "/v1/traces", true)
+      #   # => "http://localhost:8081/v1/traces"
+      #
+      #   resolve("https://app.tracekit.dev/v1/traces", "/v1/metrics", true)
+      #   # => "https://app.tracekit.dev/v1/metrics"
+      def resolve(endpoint, path, use_ssl)
+        # Case 1: Endpoint has a scheme (http:// or https://)
+        if endpoint.start_with?("http://", "https://")
+          # Remove trailing slash
+          endpoint = endpoint.chomp("/")
+
+          # Check if endpoint has a path component (anything after the host)
+          without_scheme = endpoint.sub(%r{^https?://}i, "")
+
+          if without_scheme.include?("/")
+            # Endpoint has a path component - extract base and append correct path
+            base_url = extract_base_url(endpoint)
+            return path.empty? ? base_url : "#{base_url}#{path}"
+          end
+
+          # Just host with scheme, add the path
+          return "#{endpoint}#{path}"
+        end
+
+        # Case 2: No scheme provided - build URL with scheme
+        scheme = use_ssl ? "https://" : "http://"
+        endpoint = endpoint.chomp("/")
+        "#{scheme}#{endpoint}#{path}"
+      end
+
+      # Extracts base URL (scheme + host + port) from full URL
+      # Always strips any path component, regardless of what it is
+      #
+      # @param full_url [String] The full URL to extract base from
+      # @return [String] The base URL (scheme + host + port)
+      #
+      # @example
+      #   extract_base_url("https://app.tracekit.dev/v1/traces")
+      #   # => "https://app.tracekit.dev"
+      #
+      #   extract_base_url("http://localhost:8081/custom/path")
+      #   # => "http://localhost:8081"
+      def extract_base_url(full_url)
+        match = full_url.match(%r{^(https?://[^/]+)})
+        match ? match[1] : full_url
+      end
+    end
+  end
+end

data/lib/tracekit/local_ui/detector.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Tracekit
+  module LocalUI
+    # Detects if TraceKit Local UI is running and provides the endpoint
+    class Detector
+      def initialize(port = 9999)
+        @port = port
+      end
+
+      # Checks if Local UI is running by attempting a health check
+      # @return [Boolean] true if Local UI is running
+      def running?
+        uri = URI("http://localhost:#{@port}/api/health")
+        response = Net::HTTP.get_response(uri)
+        response.is_a?(Net::HTTPSuccess)
+      rescue StandardError
+        false
+      end
+
+      # Gets the Local UI endpoint if it's running, otherwise nil
+      # @return [String, nil] The endpoint or nil
+      def endpoint
+        running? ? "http://localhost:#{@port}" : nil
+      end
+    end
+  end
+end

data/lib/tracekit/local_ui_detector.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "timeout"
+
+module Tracekit
+  # Detects if TraceKit Local UI is running on the developer's machine
+  class LocalUIDetector
+    attr_reader :port
+
+    def initialize(port = 9999)
+      @port = port
+    end
+
+    # Check if local UI is running by hitting the health endpoint
+    # @return [Boolean] true if local UI is accessible
+    def local_ui_running?
+      Timeout.timeout(0.5) do
+        uri = URI("http://localhost:#{@port}/api/health")
+        response = Net::HTTP.get_response(uri)
+        response.is_a?(Net::HTTPSuccess)
+      end
+    rescue StandardError
+      false
+    end
+
+    # Get the local UI endpoint if running
+    # @return [String, nil] the endpoint URL or nil if not running
+    def local_ui_endpoint
+      local_ui_running? ? "http://localhost:#{@port}" : nil
+    end
+  end
+end

data/lib/tracekit/metrics/counter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Metrics
+    # Counter metric - monotonically increasing value
+    # Used for tracking totals like request counts, error counts, etc.
+    class Counter
+      def initialize(name, tags, registry)
+        @name = name
+        @tags = tags || {}
+        @registry = registry
+        @value = 0.0
+        @mutex = Mutex.new
+      end
+
+      # Increments the counter by 1
+      def inc
+        add(1.0)
+      end
+
+      # Adds a value to the counter
+      # @param value [Numeric] Value to add (must be non-negative)
+      def add(value)
+        raise ArgumentError, "Counter values must be non-negative" if value < 0
+
+        @mutex.synchronize do
+          @value += value
+          @registry.record_metric(@name, "counter", @value, @tags)
+        end
+      end
+    end
+  end
+end

data/lib/tracekit/metrics/exporter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Tracekit
+  module Metrics
+    # Exports metrics to TraceKit in OTLP (OpenTelemetry Protocol) format
+    class Exporter
+      def initialize(endpoint, api_key, service_name)
+        @endpoint = endpoint
+        @api_key = api_key
+        @service_name = service_name
+      end
+
+      # Exports a batch of metric data points
+      def export(data_points)
+        return if data_points.empty?
+
+        payload = to_otlp(data_points)
+
+        uri = URI(@endpoint)
+        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,
+          "User-Agent" => "tracekit-ruby-sdk/#{Tracekit::VERSION}"
+        })
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          warn "Metrics export failed: HTTP #{response.code}"
+        end
+      rescue => e
+        warn "Metrics export error: #{e.message}"
+      end
+
+      private
+
+      # Converts data points to OTLP format
+      def to_otlp(data_points)
+        # Group by name and type
+        grouped = data_points.group_by { |dp| "#{dp.name}:#{dp.type}" }
+
+        metrics = grouped.map do |key, points|
+          name, type = key.split(":")
+
+          otlp_data_points = points.map do |dp|
+            {
+              attributes: dp.tags.map { |k, v| { key: k, value: { stringValue: v.to_s } } },
+              timeUnixNano: dp.timestamp_nanos.to_s,
+              asDouble: dp.value.to_f
+            }
+          end
+
+          if type == "counter"
+            {
+              name: name,
+              sum: {
+                dataPoints: otlp_data_points,
+                aggregationTemporality: 2, # DELTA
+                isMonotonic: true
+              }
+            }
+          else # gauge or histogram
+            {
+              name: name,
+              gauge: {
+                dataPoints: otlp_data_points
+              }
+            }
+          end
+        end
+
+        {
+          resourceMetrics: [
+            {
+              resource: {
+                attributes: [
+                  { key: "service.name", value: { stringValue: @service_name } }
+                ]
+              },
+              scopeMetrics: [
+                {
+                  scope: { name: "tracekit" },
+                  metrics: metrics
+                }
+              ]
+            }
+          ]
+        }
+      end
+    end
+  end
+end

data/lib/tracekit/metrics/gauge.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Metrics
+    # Gauge metric - point-in-time value that can increase or decrease
+    # Used for tracking current values like active connections, memory usage, etc.
+    class Gauge
+      def initialize(name, tags, registry)
+        @name = name
+        @tags = tags || {}
+        @registry = registry
+        @value = 0.0
+        @mutex = Mutex.new
+      end
+
+      # Sets the gauge to a specific value
+      # @param value [Numeric] Value to set
+      def set(value)
+        @mutex.synchronize do
+          @value = value
+          @registry.record_metric(@name, "gauge", @value, @tags)
+        end
+      end
+
+      # Increments the gauge by 1
+      def inc
+        @mutex.synchronize do
+          @value += 1
+          @registry.record_metric(@name, "gauge", @value, @tags)
+        end
+      end
+
+      # Decrements the gauge by 1
+      def dec
+        @mutex.synchronize do
+          @value -= 1
+          @registry.record_metric(@name, "gauge", @value, @tags)
+        end
+      end
+    end
+  end
+end

data/lib/tracekit/metrics/histogram.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Metrics
+    # Histogram metric - records distribution of values
+    # Used for tracking request durations, payload sizes, etc.
+    class Histogram
+      def initialize(name, tags, registry)
+        @name = name
+        @tags = tags || {}
+        @registry = registry
+      end
+
+      # Records a value in the histogram
+      # @param value [Numeric] Value to record
+      def record(value)
+        @registry.record_metric(@name, "histogram", value, @tags)
+      end
+    end
+  end
+end

data/lib/tracekit/metrics/metric_data_point.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tracekit
+  module Metrics
+    # Represents a single metric data point for export
+    class MetricDataPoint
+      attr_reader :name, :type, :value, :tags, :timestamp_nanos
+
+      def initialize(name:, type:, value:, tags:)
+        @name = name
+        @type = type  # "counter", "gauge", "histogram"
+        @value = value
+        @tags = tags
+        @timestamp_nanos = (Time.now.to_f * 1_000_000_000).to_i
+      end
+    end
+  end
+end

data/lib/tracekit/metrics/registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "concurrent/array"
+require "concurrent/timer_task"
+
+module Tracekit
+  module Metrics
+    # Registry for managing metrics and exporting them to TraceKit
+    # Implements automatic buffering and periodic export (100 metrics or 10 seconds)
+    class Registry
+      MAX_BUFFER_SIZE = 100
+      FLUSH_INTERVAL_SECONDS = 10
+
+      def initialize(endpoint, api_key, service_name)
+        @endpoint = endpoint
+        @api_key = api_key
+        @service_name = service_name
+        @buffer = Concurrent::Array.new
+        @exporter = Exporter.new(endpoint, api_key, service_name)
+        @flush_mutex = Mutex.new
+
+        # Start periodic flush timer
+        @flush_task = Concurrent::TimerTask.new(execution_interval: FLUSH_INTERVAL_SECONDS) do
+          flush
+        end
+        @flush_task.execute
+      end
+
+      # Records a metric data point
+      def record_metric(name, type, value, tags)
+        data_point = MetricDataPoint.new(
+          name: name,
+          type: type,
+          value: value,
+          tags: tags.dup
+        )
+
+        @buffer << data_point
+
+        # Auto-flush if buffer is full
+        flush if @buffer.size >= MAX_BUFFER_SIZE
+      end
+
+      # Flushes all buffered metrics
+      def flush
+        return if @buffer.empty?
+
+        @flush_mutex.synchronize do
+          return if @buffer.empty?
+
+          data_points = @buffer.dup
+          @buffer.clear
+
+          begin
+            @exporter.export(data_points)
+          rescue => e
+            warn "Failed to export metrics: #{e.message}"
+          end
+        end
+      end
+
+      # Shuts down the registry and flushes remaining metrics
+      def shutdown
+        @flush_task&.shutdown
+        flush
+      end
+    end
+  end
+end

data/lib/tracekit/middleware.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Tracekit
+  # Rack middleware for automatic TraceKit instrumentation of HTTP requests
+  # Creates server spans with kind: :server for all incoming HTTP requests
+  class Middleware
+    def initialize(app)
+      @app = app
+      @tracer = OpenTelemetry.tracer_provider.tracer('tracekit-ruby', Tracekit::VERSION)
+    end
+
+    def call(env)
+      sdk = SDK.current
+      return @app.call(env) unless sdk
+
+      request = Rack::Request.new(env)
+      path = request.path
+      method = request.request_method
+
+      # Create server span for incoming HTTP request
+      @tracer.in_span(
+        span_name(request),
+        attributes: span_attributes(request),
+        kind: :server
+      ) do |span|
+        # Track metrics
+        request_counter = sdk.counter("http.server.requests", {
+          "http.method" => method,
+          "http.route" => path
+        })
+
+        active_gauge = sdk.gauge("http.server.active_requests", {
+          "http.method" => method
+        })
+
+        duration_histogram = sdk.histogram("http.server.request.duration", {
+          "unit" => "ms"
+        })
+
+        active_gauge.inc
+        start_time = Time.now
+
+        # Add client IP to span
+        if client_ip = extract_client_ip(request)
+          span.set_attribute("http.client_ip", client_ip)
+        end
+
+        begin
+          status, headers, body = @app.call(env)
+
+          # Set response attributes
+          span.set_attribute("http.status_code", status)
+
+          # Set span status based on HTTP status code
+          if status >= 500
+            span.status = OpenTelemetry::Trace::Status.error("HTTP #{status}")
+          elsif status >= 400
+            span.status = OpenTelemetry::Trace::Status.error("HTTP #{status}")
+          else
+            span.status = OpenTelemetry::Trace::Status.ok
+          end
+
+          # Record successful request
+          request_counter.inc
+
+          # Record errors
+          if status >= 400
+            error_counter = sdk.counter("http.server.errors", {
+              "http.method" => method,
+              "http.status_code" => status.to_s
+            })
+            error_counter.inc
+          end
+
+          [status, headers, body]
+        rescue => e
+          # Record exception on span
+          span.record_exception(e)
+          span.status = OpenTelemetry::Trace::Status.error("Exception: #{e.class.name}")
+
+          # Record exception metric
+          error_counter = sdk.counter("http.server.errors", {
+            "http.method" => method,
+            "error.type" => e.class.name
+          })
+          error_counter.inc
+
+          raise
+        ensure
+          active_gauge.dec
+          duration = ((Time.now - start_time) * 1000).round(2)
+          duration_histogram.record(duration)
+        end
+      end
+    end
+
+    private
+
+    def span_name(request)
+      # Use route if available (Rails), otherwise method + path
+      route = request.env['action_dispatch.request.path_parameters']&.[](:controller)
+      if route
+        action = request.env['action_dispatch.request.path_parameters']&.[](:action)
+        "#{request.request_method} #{route}##{action}"
+      else
+        "#{request.request_method} #{request.path}"
+      end
+    end
+
+    def span_attributes(request)
+      {
+        'http.method' => request.request_method,
+        'http.url' => request.url,
+        'http.target' => request.path,
+        'http.host' => request.host,
+        'http.scheme' => request.scheme,
+        'http.user_agent' => request.user_agent,
+        'net.host.name' => request.host,
+        'net.host.port' => request.port
+      }.compact
+    end
+
+    def extract_client_ip(request)
+      # Try X-Forwarded-For first
+      forwarded = request.env["HTTP_X_FORWARDED_FOR"]
+      return forwarded.split(",").first.strip if forwarded
+
+      # Try X-Real-IP
+      real_ip = request.env["HTTP_X_REAL_IP"]
+      return real_ip if real_ip
+
+      # Fall back to remote IP
+      request.ip
+    end
+  end
+end

data/lib/tracekit/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tracekit
+  # Rails integration via Railtie
+  # Auto-loads when Rails is detected
+  class Railtie < ::Rails::Railtie
+    config.tracekit = ActiveSupport::OrderedOptions.new
+
+    initializer "tracekit.configure" do |app|
+      # Load configuration from Rails config or ENV vars
+      tracekit_config = Config.build do |c|
+        c.api_key = app.config.tracekit.api_key || ENV["TRACEKIT_API_KEY"]
+        c.service_name = app.config.tracekit.service_name || ENV["TRACEKIT_SERVICE_NAME"] || Rails.application.class.module_parent_name.underscore
+        c.endpoint = app.config.tracekit.endpoint || ENV["TRACEKIT_ENDPOINT"] || "app.tracekit.dev"
+        c.use_ssl = app.config.tracekit.use_ssl.nil? ? (ENV["TRACEKIT_USE_SSL"] != "false") : app.config.tracekit.use_ssl
+        c.environment = app.config.tracekit.environment || ENV["TRACEKIT_ENVIRONMENT"] || Rails.env
+        c.service_version = app.config.tracekit.service_version || ENV["TRACEKIT_SERVICE_VERSION"] || "1.0.0"
+        c.enable_code_monitoring = app.config.tracekit.enable_code_monitoring.nil? ? (ENV["TRACEKIT_CODE_MONITORING"] != "false") : app.config.tracekit.enable_code_monitoring
+        c.code_monitoring_poll_interval = (app.config.tracekit.code_monitoring_poll_interval || ENV["TRACEKIT_POLL_INTERVAL"] || 30).to_i
+        c.local_ui_port = (app.config.tracekit.local_ui_port || ENV["TRACEKIT_LOCAL_UI_PORT"] || 9999).to_i
+        c.sampling_rate = (app.config.tracekit.sampling_rate || ENV["TRACEKIT_SAMPLING_RATE"] || 1.0).to_f
+      end
+
+      # Initialize SDK
+      SDK.configure(tracekit_config)
+
+      # Insert middleware
+      app.middleware.use Tracekit::Middleware
+    end
+
+    # Shutdown SDK when Rails shuts down
+    config.after_initialize do
+      at_exit { SDK.current&.shutdown }
+    end
+  end
+end