justanalytics 0.1.0

data/lib/justanalytics/integrations/net_http.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Monkey-patch for +Net::HTTP+ that automatically creates client spans
+  # for outgoing HTTP requests and injects +traceparent+ headers.
+  #
+  # The patch wraps +Net::HTTP#request+ to:
+  # 1. Create a client span with HTTP method, URL, and host attributes
+  # 2. Inject the W3C +traceparent+ header for distributed tracing
+  # 3. Record the response status code on the span
+  # 4. Set span status to "error" for 5xx responses
+  #
+  # @example Enable the patch
+  #   JustAnalytics::NetHttpPatch.enable!
+  #
+  # @example Disable the patch (restore original)
+  #   JustAnalytics::NetHttpPatch.disable!
+  module NetHttpPatch
+    # URLs to ignore (JustAnalytics server endpoints, health checks)
+    IGNORE_PATHS = %w[/api/ingest/ /health /ready /live /favicon.ico].freeze
+
+    class << self
+      # Enable the Net::HTTP monkey-patch.
+      #
+      # @return [void]
+      def enable!
+        return if @enabled
+
+        @enabled = true
+        Net::HTTP.prepend(Instrumentation)
+      end
+
+      # Check if the patch is enabled.
+      #
+      # @return [Boolean]
+      def enabled?
+        @enabled || false
+      end
+
+      # Disable the Net::HTTP monkey-patch.
+      #
+      # Note: Ruby's +prepend+ cannot be truly undone. This flag prevents
+      # span creation but the method override remains.
+      #
+      # @return [void]
+      def disable!
+        @enabled = false
+      end
+
+      # Check if a URL path should be ignored.
+      #
+      # @param path [String] URL path
+      # @param host [String] hostname
+      # @return [Boolean]
+      def ignore?(path, host)
+        return true if JustAnalytics.initialized? &&
+                       JustAnalytics.client.config.server_url.include?(host.to_s)
+
+        IGNORE_PATHS.any? { |p| path.to_s.start_with?(p) }
+      end
+    end
+
+    # Module prepended to Net::HTTP to instrument outgoing requests.
+    module Instrumentation
+      # Wrap Net::HTTP#request to create spans for outgoing HTTP calls.
+      #
+      # @param req [Net::HTTPRequest] the HTTP request
+      # @param body [String, nil] optional request body
+      # @return [Net::HTTPResponse] the response
+      def request(req, body = nil, &block)
+        return super unless NetHttpPatch.enabled? && JustAnalytics.initialized?
+
+        path = req.path || "/"
+        host = address.to_s
+
+        return super if NetHttpPatch.ignore?(path, host)
+
+        method = req.method || "GET"
+        span_name = "HTTP #{method} #{host}#{path.split('?').first}"
+
+        # Build attributes
+        attributes = {
+          "http.method" => method,
+          "http.url" => "#{use_ssl? ? 'https' : 'http'}://#{host}:#{port}#{path}",
+          "http.host" => host,
+          "net.peer.port" => port.to_s
+        }
+
+        span = JustAnalytics::Span.new(
+          operation_name: span_name,
+          service_name: JustAnalytics.client.config.service_name,
+          kind: "client",
+          trace_id: Context.current_trace_id || TraceContext.generate_trace_id,
+          parent_span_id: Context.current_span&.id,
+          attributes: attributes
+        )
+
+        child_ctx = Context.create_child(active_span: span, trace_id: span.trace_id)
+
+        # Inject traceparent header
+        req["traceparent"] = TraceContext.serialize_traceparent(span.trace_id, span.id)
+
+        response = nil
+        Context.with_context(child_ctx) do
+          response = super(req, body, &block)
+        rescue => e
+          span.set_status("error", e.message)
+          span.set_attribute("error.type", e.class.name)
+          raise
+        ensure
+          if response
+            status_code = response.code.to_i
+            span.set_attribute("http.status_code", status_code)
+            span.set_status(status_code >= 500 ? "error" : "ok")
+          end
+
+          span.end_span unless span.ended?
+          JustAnalytics.client.send(:enqueue_span, span)
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/justanalytics/integrations/rails.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Rack middleware for Rails applications that creates server spans for
+  # incoming HTTP requests and captures unhandled exceptions.
+  #
+  # @example Manual Rack middleware insertion
+  #   # config/application.rb
+  #   config.middleware.use JustAnalytics::RailsMiddleware
+  #
+  # @example Automatic via Railtie
+  #   # Just require 'justanalytics' in your Gemfile and the Railtie
+  #   # auto-inserts the middleware.
+  class RailsMiddleware
+    # @param app [#call] the downstream Rack application
+    def initialize(app)
+      @app = app
+    end
+
+    # Process an incoming request: parse traceparent, create server span,
+    # capture exceptions, and set response headers.
+    #
+    # @param env [Hash] Rack environment
+    # @return [Array] Rack response tuple [status, headers, body]
+    def call(env)
+      return @app.call(env) unless JustAnalytics.initialized?
+
+      request_method = env["REQUEST_METHOD"] || "GET"
+      request_path = env["PATH_INFO"] || "/"
+      span_name = "#{request_method} #{request_path}"
+
+      # Parse incoming traceparent header
+      traceparent_header = env["HTTP_TRACEPARENT"]
+      parent_data = nil
+      if traceparent_header
+        parent_data = TraceContext.parse_traceparent(traceparent_header)
+      end
+
+      # Determine trace ID and parent span ID
+      if parent_data
+        trace_id = parent_data.trace_id
+        parent_span_id = parent_data.parent_span_id
+      else
+        trace_id = TraceContext.generate_trace_id
+        parent_span_id = nil
+      end
+
+      # Build attributes from request
+      attributes = {
+        "http.method" => request_method,
+        "http.url" => request_path,
+        "http.host" => env["HTTP_HOST"] || env["SERVER_NAME"] || "unknown",
+        "http.user_agent" => env["HTTP_USER_AGENT"],
+        "http.scheme" => env["rack.url_scheme"] || "http"
+      }.compact
+
+      span = Span.new(
+        operation_name: span_name,
+        service_name: JustAnalytics.client.config.service_name,
+        kind: "server",
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        attributes: attributes
+      )
+
+      child_ctx = Context.create_child(active_span: span, trace_id: trace_id)
+
+      status = nil
+      headers = nil
+      body = nil
+
+      Context.with_context(child_ctx) do
+        status, headers, body = @app.call(env)
+      rescue => e
+        span.set_status("error", e.message)
+        span.set_attribute("error.type", e.class.name)
+        span.set_attribute("error.message", e.message)
+
+        # Capture the exception via SDK
+        JustAnalytics.capture_exception(e, tags: { "http.method" => request_method, "http.url" => request_path })
+
+        span.end_span
+        JustAnalytics.client.send(:enqueue_span, span)
+        raise
+      end
+
+      # Record response attributes
+      span.set_attribute("http.status_code", status.to_i)
+      span.set_status(status.to_i >= 500 ? "error" : "ok")
+
+      span.end_span
+      JustAnalytics.client.send(:enqueue_span, span)
+
+      # Inject traceparent into response headers for downstream correlation
+      if headers.is_a?(Hash)
+        headers["traceparent"] = TraceContext.serialize_traceparent(trace_id, span.id)
+      end
+
+      [status, headers, body]
+    end
+  end
+
+  # Rails Railtie that auto-configures the middleware in Rails applications.
+  #
+  # When the +justanalytics+ gem is loaded in a Rails app, this Railtie
+  # automatically inserts {RailsMiddleware} into the middleware stack.
+  #
+  # @example Gemfile
+  #   gem "justanalytics"
+  #
+  #   # Then in config/initializers/justanalytics.rb:
+  #   JustAnalytics.init(
+  #     site_id: ENV["JA_SITE_ID"],
+  #     api_key: ENV["JA_API_KEY"],
+  #     service_name: "rails-api"
+  #   )
+  class Railtie < defined?(::Rails::Railtie) ? ::Rails::Railtie : Object
+    if defined?(::Rails::Railtie)
+      initializer "justanalytics.configure_rails_middleware" do |app|
+        app.middleware.insert_before(0, JustAnalytics::RailsMiddleware)
+      end
+    end
+  end
+end

data/lib/justanalytics/integrations/sidekiq.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Sidekiq server middleware that traces job execution.
+  #
+  # Creates a span for each job, propagates trace context from the
+  # client middleware, and captures exceptions.
+  #
+  # @example Enable in Sidekiq config
+  #   Sidekiq.configure_server do |config|
+  #     config.server_middleware do |chain|
+  #       chain.add JustAnalytics::SidekiqServerMiddleware
+  #     end
+  #   end
+  class SidekiqServerMiddleware
+    # @param worker [Object] the Sidekiq worker instance
+    # @param job [Hash] the job payload hash
+    # @param queue [String] the queue name
+    # @yield the job execution block
+    def call(worker, job, queue)
+      return yield unless JustAnalytics.initialized?
+
+      job_class = job["class"] || worker.class.name
+      span_name = "sidekiq.#{job_class}"
+
+      # Extract trace context from job payload (injected by client middleware)
+      trace_id = job["_ja_trace_id"] || TraceContext.generate_trace_id
+      parent_span_id = job["_ja_parent_span_id"]
+
+      attributes = {
+        "sidekiq.queue" => queue,
+        "sidekiq.job_class" => job_class,
+        "sidekiq.job_id" => job["jid"],
+        "sidekiq.retry_count" => job["retry_count"] || 0
+      }
+
+      span = Span.new(
+        operation_name: span_name,
+        service_name: JustAnalytics.client.config.service_name,
+        kind: "consumer",
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        attributes: attributes
+      )
+
+      child_ctx = Context.create_child(active_span: span, trace_id: trace_id)
+
+      Context.with_context(child_ctx) do
+        yield
+      rescue => e
+        span.set_status("error", e.message)
+        span.set_attribute("error.type", e.class.name)
+        span.set_attribute("error.message", e.message)
+
+        JustAnalytics.capture_exception(e, tags: {
+          "sidekiq.queue" => queue,
+          "sidekiq.job_class" => job_class
+        })
+
+        raise
+      ensure
+        span.end_span unless span.ended?
+        JustAnalytics.client.send(:enqueue_span, span)
+      end
+    end
+  end
+
+  # Sidekiq client middleware that injects trace context into job payloads.
+  #
+  # When a job is enqueued from within a traced scope, the current trace ID
+  # and span ID are injected into the job hash so the server middleware
+  # can continue the trace.
+  #
+  # @example Enable in Sidekiq config
+  #   Sidekiq.configure_client do |config|
+  #     config.client_middleware do |chain|
+  #       chain.add JustAnalytics::SidekiqClientMiddleware
+  #     end
+  #   end
+  class SidekiqClientMiddleware
+    # @param worker_class [String, Class] the worker class name
+    # @param job [Hash] the job payload hash
+    # @param queue [String] the queue name
+    # @param redis_pool [Object] Sidekiq Redis pool
+    # @yield continues the middleware chain
+    def call(worker_class, job, queue, redis_pool)
+      if JustAnalytics.initialized?
+        active_span = Context.current_span
+        if active_span
+          job["_ja_trace_id"] = active_span.trace_id
+          job["_ja_parent_span_id"] = active_span.id
+        end
+      end
+
+      yield
+    end
+  end
+end

data/lib/justanalytics/logger.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Ruby Logger-compatible structured logger that ships log entries to JustAnalytics.
+  #
+  # Log entries are buffered in the Transport and flushed periodically to
+  # +POST /api/ingest/logs+. Trace ID and span ID are automatically attached
+  # from the thread-local context when logging inside a traced scope.
+  #
+  # Implements the same interface as Ruby's +::Logger+ for drop-in compatibility:
+  # +debug+, +info+, +warn+, +error+, +fatal+, +unknown+.
+  #
+  # @example
+  #   logger = JustAnalytics.logger
+  #   logger.info("User logged in", user_id: "u123")
+  #   logger.error("Payment failed", order_id: "o456", reason: "declined")
+  class Logger
+    # Map Ruby Logger severity constants to JA log levels.
+    SEVERITY_MAP = {
+      0 => "debug",  # Logger::DEBUG
+      1 => "info",   # Logger::INFO
+      2 => "warn",   # Logger::WARN
+      3 => "error",  # Logger::ERROR
+      4 => "fatal",  # Logger::FATAL
+      5 => "fatal"   # Logger::UNKNOWN
+    }.freeze
+
+    VALID_LEVELS = %w[debug info warn error fatal].freeze
+
+    # @param service_name [String] service name from SDK config
+    # @param transport [Transport, nil] transport for enqueuing logs
+    # @param enabled [Boolean] whether logging is active
+    # @param environment [String, nil] deployment environment
+    # @param release [String, nil] release version
+    # @param debug [Boolean] whether to echo logs to stderr
+    def initialize(service_name:, transport:, enabled: true, environment: nil, release: nil, debug: false)
+      @service_name = service_name
+      @transport = transport
+      @enabled = enabled
+      @environment = environment
+      @release = release
+      @debug = debug
+    end
+
+    # Log a debug-level message.
+    #
+    # @param message [String] log message
+    # @param attributes [Hash] optional metadata
+    # @return [void]
+    def debug(message = nil, **attributes, &block)
+      log_entry("debug", message, attributes, &block)
+    end
+
+    # Log an info-level message.
+    #
+    # @param message [String] log message
+    # @param attributes [Hash] optional metadata
+    # @return [void]
+    def info(message = nil, **attributes, &block)
+      log_entry("info", message, attributes, &block)
+    end
+
+    # Log a warn-level message.
+    #
+    # @param message [String] log message
+    # @param attributes [Hash] optional metadata
+    # @return [void]
+    def warn(message = nil, **attributes, &block)
+      log_entry("warn", message, attributes, &block)
+    end
+
+    # Log an error-level message.
+    #
+    # @param message [String] log message
+    # @param attributes [Hash] optional metadata
+    # @return [void]
+    def error(message = nil, **attributes, &block)
+      log_entry("error", message, attributes, &block)
+    end
+
+    # Log a fatal-level message.
+    #
+    # @param message [String] log message
+    # @param attributes [Hash] optional metadata
+    # @return [void]
+    def fatal(message = nil, **attributes, &block)
+      log_entry("fatal", message, attributes, &block)
+    end
+
+    # Log at a specified level (Ruby Logger compatible).
+    #
+    # @param level [String, Integer] severity level
+    # @param message [String] log message
+    # @param attributes [Hash] optional metadata
+    # @return [void]
+    def log(level, message = nil, **attributes, &block)
+      resolved_level = resolve_level(level)
+      log_entry(resolved_level, message, attributes, &block)
+    end
+
+    # Alias for compatibility with Ruby Logger.
+    alias_method :add, :log
+
+    private
+
+    # Build and enqueue a log entry payload.
+    def log_entry(level, message, attributes, &block)
+      return unless @enabled && @transport
+
+      message = block.call if message.nil? && block
+      return if message.nil? || message.to_s.empty?
+
+      active_span = Context.current_span
+      trace_id = Context.current_trace_id
+      span_id = active_span&.id
+
+      enriched = attributes.transform_keys(&:to_s)
+      enriched["environment"] = @environment if @environment
+      enriched["release"] = @release if @release
+
+      payload = {
+        "level" => level,
+        "message" => message.to_s,
+        "serviceName" => @service_name,
+        "timestamp" => Time.now.utc.iso8601(3),
+        "traceId" => trace_id,
+        "spanId" => span_id,
+        "attributes" => enriched
+      }
+
+      $stderr.puts "[JustAnalytics Logger] #{level.upcase} \"#{message}\" traceId=#{trace_id || 'none'}" if @debug
+
+      @transport.enqueue_log(payload)
+    rescue => e
+      $stderr.puts "[JustAnalytics Logger] Internal error: #{e.message}" if @debug
+    end
+
+    def resolve_level(level)
+      case level
+      when Integer
+        SEVERITY_MAP.fetch(level, "info")
+      when String, Symbol
+        l = level.to_s.downcase
+        VALID_LEVELS.include?(l) ? l : "info"
+      else
+        "info"
+      end
+    end
+  end
+end

data/lib/justanalytics/span.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Span represents a single timed operation within a distributed trace.
+  #
+  # Spans are created by {JustAnalytics.start_span} and automatically ended
+  # when the block completes. The {#to_h} method serializes the span to the
+  # exact format expected by +POST /api/ingest/spans+.
+  #
+  # @example
+  #   JustAnalytics.start_span("process-order", op: "task") do |span|
+  #     span.set_attribute("order.id", "12345")
+  #     span.add_event("payment.processed")
+  #   end
+  class Span
+    # Valid span kinds (OpenTelemetry-compatible).
+    VALID_KINDS = %w[client server producer consumer internal].freeze
+
+    # Valid span statuses.
+    VALID_STATUSES = %w[ok error unset].freeze
+
+    # @return [String] 16-character hex span ID
+    attr_reader :id
+
+    # @return [String] 32-character hex trace ID
+    attr_reader :trace_id
+
+    # @return [String, nil] parent span ID or nil for root spans
+    attr_reader :parent_span_id
+
+    # @return [String] operation name
+    attr_reader :operation_name
+
+    # @return [String] service name
+    attr_reader :service_name
+
+    # @return [String] span kind
+    attr_reader :kind
+
+    # @return [Time] wall-clock start time
+    attr_reader :start_time
+
+    # @return [Boolean] whether the span has ended
+    attr_reader :ended
+    alias_method :ended?, :ended
+
+    # Create a new Span.
+    #
+    # @param operation_name [String] operation/span name
+    # @param service_name [String] service that produced this span
+    # @param kind [String] span kind (default: "internal")
+    # @param trace_id [String] 32-char hex trace ID
+    # @param parent_span_id [String, nil] parent span ID or nil
+    # @param attributes [Hash] initial attributes
+    def initialize(operation_name:, service_name:, trace_id:, parent_span_id: nil, kind: "internal", attributes: {})
+      @id = TraceContext.generate_span_id
+      @trace_id = trace_id
+      @parent_span_id = parent_span_id
+      @operation_name = operation_name
+      @service_name = service_name
+      @kind = VALID_KINDS.include?(kind) ? kind : "internal"
+      @start_time = Time.now.utc
+      @start_monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      @end_time = nil
+      @duration = nil
+      @status = "unset"
+      @status_message = nil
+      @attributes = attributes.dup
+      @events = []
+      @ended = false
+    end
+
+    # Set a single attribute on the span.
+    #
+    # @param key [String] attribute key
+    # @param value [Object] attribute value
+    # @return [self]
+    def set_attribute(key, value)
+      return self if @ended
+
+      @attributes[key.to_s] = value
+      self
+    end
+
+    # Set multiple attributes on the span.
+    #
+    # @param attrs [Hash] key-value pairs to merge
+    # @return [self]
+    def set_attributes(attrs)
+      return self if @ended
+
+      attrs.each { |k, v| @attributes[k.to_s] = v }
+      self
+    end
+
+    # Set the span status.
+    #
+    # @param status [String] one of "ok", "error", "unset"
+    # @param message [String, nil] optional status message
+    # @return [self]
+    def set_status(status, message = nil)
+      return self if @ended
+
+      @status = VALID_STATUSES.include?(status) ? status : "unset"
+      @status_message = message
+      self
+    end
+
+    # Add a timestamped event to the span.
+    #
+    # @param name [String] event name
+    # @param attributes [Hash] optional event attributes
+    # @return [self]
+    def add_event(name, attributes: {})
+      return self if @ended
+
+      event = { "name" => name, "timestamp" => Time.now.utc.iso8601(3) }
+      event["attributes"] = attributes unless attributes.empty?
+      @events << event
+      self
+    end
+
+    # Update the operation name after creation.
+    #
+    # @param name [String] new operation name
+    # @return [self]
+    def update_operation_name(name)
+      return self if @ended
+
+      @operation_name = name
+      self
+    end
+
+    # Mark the span as ended.
+    #
+    # Calculates duration using monotonic clock for precision.
+    # Calling +end_span+ multiple times is a no-op (idempotent).
+    #
+    # @return [void]
+    def end_span
+      return if @ended
+
+      @ended = true
+      @end_time = Time.now.utc
+      end_monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      @duration = (end_monotonic - @start_monotonic).round
+    end
+
+    # Serialize the span to a Hash matching the /api/ingest/spans schema.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        "id" => @id,
+        "traceId" => @trace_id,
+        "parentSpanId" => @parent_span_id,
+        "operationName" => @operation_name,
+        "serviceName" => @service_name,
+        "kind" => @kind,
+        "startTime" => @start_time.iso8601(3),
+        "endTime" => @end_time&.iso8601(3),
+        "duration" => @duration,
+        "status" => @status,
+        "statusMessage" => @status_message,
+        "attributes" => @attributes.dup,
+        "events" => @events.dup
+      }
+    end
+  end
+end