justanalytics 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7fb7497381f0737b13c5ac642233e584d8a6761305a761deb076c3097b182e60
+  data.tar.gz: 1ba4d29f18dd7add59d685c6e37cc8f94a23a9b4a9bea91e8777040d90e296f7
+SHA512:
+  metadata.gz: 69f41c7257fd38b4b77d1a5920cabc2f23203da91934130f9c902f1713a5b9138302c44870da936b7318d69f45d2b79f86dbb5c1c52d306b23bedb2eba2310aa
+  data.tar.gz: a177161441f4ba169a54cb5af6c2b7b8ba4b5a60813d3432c7a6f71587db0381fcdbbc42f1fa03876d82cec3deb6ae90bbc72c9277146a52f9e088c51e57f5e2

data/README.md

@@ -0,0 +1,103 @@
+# JustAnalytics Ruby SDK
+
+End-to-end observability for Ruby applications. Distributed tracing, error tracking, structured logging, and infrastructure metrics — all in one gem.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "justanalytics"
+```
+
+Then run `bundle install`.
+
+## Quick Start
+
+```ruby
+require "justanalytics"
+
+JustAnalytics.init(
+  site_id: ENV["JA_SITE_ID"],
+  api_key: ENV["JA_API_KEY"],
+  service_name: "rails-api",
+  environment: "production",
+  release: "1.2.3"
+)
+```
+
+## Usage
+
+### Tracing
+
+```ruby
+JustAnalytics.start_span("process-order", op: "task") do |span|
+  span.set_attribute("order.id", order.id)
+  span.add_event("payment.started")
+  process_payment(order)
+end
+```
+
+### Error Tracking
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  JustAnalytics.capture_exception(e, tags: { module: "payments" })
+end
+
+JustAnalytics.capture_message("Rate limit exceeded", level: "warning")
+```
+
+### Structured Logging
+
+```ruby
+JustAnalytics.logger.info("User logged in", user_id: "u123")
+JustAnalytics.logger.error("Payment failed", order_id: "o456")
+```
+
+### User Context
+
+```ruby
+JustAnalytics.set_user(id: "user-123", email: "alice@example.com")
+```
+
+### Rails Integration
+
+The SDK auto-configures Rails middleware via a Railtie. Just add the gem and initialize:
+
+```ruby
+# config/initializers/justanalytics.rb
+JustAnalytics.init(
+  site_id: ENV["JA_SITE_ID"],
+  api_key: ENV["JA_API_KEY"],
+  service_name: "rails-api"
+)
+```
+
+### Sidekiq Integration
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add JustAnalytics::SidekiqServerMiddleware
+  end
+end
+
+Sidekiq.configure_client do |config|
+  config.client_middleware do |chain|
+    chain.add JustAnalytics::SidekiqClientMiddleware
+  end
+end
+```
+
+### Net::HTTP Auto-Instrumentation
+
+```ruby
+JustAnalytics::NetHttpPatch.enable!
+```
+
+## License
+
+MIT

data/lib/justanalytics/client.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+
+module JustAnalytics
+  # Core client class managing configuration, lifecycle, span creation,
+  # error capture, context propagation, and batched transport.
+  #
+  # Typically accessed through the module-level methods on {JustAnalytics}
+  # rather than instantiated directly.
+  class Client
+    # @return [Configuration] current configuration
+    attr_reader :config
+
+    # @return [Logger] structured logger instance
+    attr_reader :logger
+
+    # @return [Boolean] whether init has been called
+    attr_reader :initialized
+    alias_method :initialized?, :initialized
+
+    def initialize
+      @config = nil
+      @transport = nil
+      @logger = nil
+      @initialized = false
+    end
+
+    # Initialize the SDK with configuration.
+    #
+    # @param site_id [String] site ID (required)
+    # @param api_key [String] API key (required)
+    # @param service_name [String] service name (required)
+    # @param environment [String, nil] deployment environment
+    # @param release [String, nil] release/version string
+    # @param server_url [String, nil] JA server URL override
+    # @param debug [Boolean] enable debug logging
+    # @param flush_interval [Float] flush interval in seconds
+    # @param max_batch_size [Integer] max batch size
+    # @param enabled [Boolean] enable/disable SDK
+    # @return [void]
+    def init(site_id:, api_key:, service_name:, environment: nil, release: nil,
+             server_url: nil, debug: false, flush_interval: 2.0, max_batch_size: 100,
+             enabled: true)
+      if @initialized
+        $stderr.puts "[JustAnalytics] Warning: init() already called. Ignoring."
+        return
+      end
+
+      @config = Configuration.new
+      @config.site_id = site_id
+      @config.api_key = api_key
+      @config.service_name = service_name
+      @config.environment = environment
+      @config.release = release
+      @config.server_url = server_url if server_url
+      @config.debug = debug
+      @config.flush_interval = flush_interval
+      @config.max_batch_size = max_batch_size
+      @config.enabled = enabled
+
+      @config.validate!
+
+      if debug
+        key_prefix = api_key[0, 10]
+        $stderr.puts "[JustAnalytics] Initializing SDK: service=#{service_name}, " \
+                     "server=#{@config.server_url}, apiKey=#{key_prefix}..., enabled=#{enabled}"
+      end
+
+      if enabled
+        @transport = Transport.new(
+          server_url: @config.server_url,
+          api_key: @config.api_key,
+          site_id: @config.site_id,
+          flush_interval: @config.flush_interval,
+          max_batch_size: @config.max_batch_size,
+          debug: @config.debug
+        )
+        @transport.start
+
+        @logger = JustAnalytics::Logger.new(
+          service_name: @config.service_name,
+          transport: @transport,
+          enabled: true,
+          environment: @config.environment,
+          release: @config.release,
+          debug: @config.debug
+        )
+      else
+        @logger = JustAnalytics::Logger.new(
+          service_name: service_name,
+          transport: nil,
+          enabled: false
+        )
+      end
+
+      @initialized = true
+    end
+
+    # Create and execute a span.
+    #
+    # The block runs within a context scope with the span as the active span.
+    # Nested +start_span+ calls automatically create parent-child relationships.
+    #
+    # @param name [String] operation name for the span
+    # @param op [String] span kind (default: "internal")
+    # @param attributes [Hash] initial span attributes
+    # @yield [Span] the created span
+    # @return the return value of the block
+    #
+    # @example
+    #   result = JustAnalytics.start_span("process-order", op: "task") do |span|
+    #     span.set_attribute("order.id", "12345")
+    #     process_order
+    #   end
+    def start_span(name, op: "internal", attributes: {})
+      # Determine parent and trace ID
+      parent_span = Context.current_span
+      if parent_span
+        trace_id = parent_span.trace_id
+        parent_span_id = parent_span.id
+      else
+        trace_id = TraceContext.generate_trace_id
+        parent_span_id = nil
+      end
+
+      should_enqueue = @initialized && @config&.enabled
+
+      # Merge context tags into attributes
+      str_attrs = {}
+      attributes.each { |k, v| str_attrs[k.to_s] = v }
+      merged_attrs = Context.current_tags.merge(str_attrs)
+      merged_attrs["environment"] = @config.environment if @config&.environment
+      merged_attrs["release"] = @config.release if @config&.release
+
+      span = Span.new(
+        operation_name: name,
+        service_name: @config&.service_name || "unknown",
+        kind: op,
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        attributes: merged_attrs
+      )
+
+      child_ctx = Context.create_child(active_span: span, trace_id: trace_id)
+
+      result = nil
+      Context.with_context(child_ctx) do
+        result = yield(span) if block_given?
+      rescue => e
+        span.set_status("error", e.message) unless span.ended?
+        span.end_span unless span.ended?
+        enqueue_span(span) if should_enqueue
+        raise
+      end
+
+      span.end_span unless span.ended?
+      enqueue_span(span) if should_enqueue
+      result
+    end
+
+    # Capture an exception and send it to JustAnalytics.
+    #
+    # @param error [Exception, String, Object] the error to capture
+    # @param tags [Hash] additional tags
+    # @param extra [Hash] arbitrary extra data
+    # @param user [Hash] user context override
+    # @param level [String] severity level (default: "error")
+    # @param fingerprint [Array<String>] custom fingerprint
+    # @return [String] unique event ID, or empty string if disabled
+    def capture_exception(error, tags: {}, extra: {}, user: nil, level: "error", fingerprint: nil)
+      return "" unless @initialized && @config&.enabled
+
+      payload = build_error_payload(
+        error,
+        mechanism_type: "manual",
+        handled: true,
+        level: level,
+        tags: tags,
+        extra: extra,
+        user: user,
+        fingerprint: fingerprint
+      )
+      @transport&.enqueue_error(payload)
+      payload["eventId"]
+    rescue => e
+      $stderr.puts "[JustAnalytics] captureException() internal error: #{e.message}" if @config&.debug
+      ""
+    end
+
+    # Capture a message and send it to JustAnalytics.
+    #
+    # @param message [String] the message string
+    # @param level [String] severity level (default: "info")
+    # @param tags [Hash] additional tags
+    # @return [String] unique event ID, or empty string if disabled
+    def capture_message(message, level: "info", tags: {})
+      return "" unless @initialized && @config&.enabled
+
+      payload = build_error_payload(
+        message,
+        mechanism_type: "manual",
+        handled: true,
+        level: level,
+        tags: tags,
+        extra: {},
+        user: nil,
+        fingerprint: nil
+      )
+      payload["error"]["type"] = "Message"
+      @transport&.enqueue_error(payload)
+      payload["eventId"]
+    rescue => e
+      $stderr.puts "[JustAnalytics] captureMessage() internal error: #{e.message}" if @config&.debug
+      ""
+    end
+
+    # Set user context for the current thread scope.
+    #
+    # @param id [String, nil] user ID
+    # @param email [String, nil] user email
+    # @param username [String, nil] username
+    # @return [void]
+    def set_user(id: nil, email: nil, username: nil)
+      return unless @initialized
+
+      user = {}
+      user["id"] = id if id
+      user["email"] = email if email
+      user["username"] = username if username
+      Context.set_user(user)
+    end
+
+    # Set a tag on the current thread scope.
+    #
+    # @param key [String] tag key
+    # @param value [String] tag value
+    # @return [void]
+    def set_tag(key, value)
+      return unless @initialized
+
+      Context.set_tag(key, value)
+    end
+
+    # Record a custom infrastructure metric.
+    #
+    # @param metric_name [String] metric name (dot notation)
+    # @param value [Numeric] metric value
+    # @param tags [Hash] optional tags
+    # @return [void]
+    def record_metric(metric_name, value, tags: {})
+      return unless @initialized && @config&.enabled
+
+      payload = {
+        "metricName" => metric_name,
+        "value" => value,
+        "serviceName" => @config.service_name,
+        "timestamp" => Time.now.utc.iso8601(3),
+        "tags" => {
+          "hostname" => Socket.gethostname,
+          "runtime" => "ruby",
+          "rubyVersion" => RUBY_VERSION
+        }.merge(@config.environment ? { "environment" => @config.environment } : {})
+         .merge(tags.transform_keys(&:to_s))
+      }
+      @transport&.enqueue_metric(payload)
+    rescue => e
+      $stderr.puts "[JustAnalytics] recordMetric() internal error: #{e.message}" if @config&.debug
+    end
+
+    # Flush all pending data to the server.
+    #
+    # @return [void]
+    def flush
+      @transport&.flush
+    end
+
+    # Shut down the SDK: flush remaining data, stop worker thread.
+    #
+    # @return [void]
+    def close
+      return unless @initialized
+
+      $stderr.puts "[JustAnalytics] Closing SDK..." if @config&.debug
+
+      @transport&.shutdown
+      @transport = nil
+      @logger = nil
+      @initialized = false
+
+      $stderr.puts "[JustAnalytics] SDK closed." if @config&.debug
+    end
+
+    private
+
+    # Enqueue a completed span for transport.
+    def enqueue_span(span)
+      @transport&.enqueue_span(span.to_h)
+    end
+
+    # Build an error payload matching the /api/ingest/errors schema.
+    #
+    # @param value [Exception, String, Object] the error or message
+    # @param mechanism_type [String] how the error was captured
+    # @param handled [Boolean] whether the error was handled
+    # @param level [String] severity level
+    # @param tags [Hash] additional tags
+    # @param extra [Hash] extra data
+    # @param user [Hash, nil] user context override
+    # @param fingerprint [Array<String>, nil] custom fingerprint
+    # @return [Hash] the serialized payload
+    def build_error_payload(value, mechanism_type:, handled:, level:, tags:, extra:, user:, fingerprint:)
+      error_data = serialize_error(value)
+
+      # Get trace context
+      active_span = Context.current_span
+      trace_id = active_span&.trace_id || Context.current_trace_id
+      span_id = active_span&.id
+
+      # Get user context (parameter overrides context)
+      context_user = Context.current_user
+      resolved_user = user || context_user
+
+      # Merge context tags with provided tags
+      context_tags = Context.current_tags
+      merged_tags = context_tags.merge((tags || {}).transform_keys(&:to_s).transform_values(&:to_s))
+
+      event_id = SecureRandom.hex(12)
+
+      {
+        "eventId" => event_id,
+        "timestamp" => Time.now.utc.iso8601(3),
+        "error" => error_data,
+        "level" => level,
+        "mechanism" => {
+          "type" => mechanism_type,
+          "handled" => handled
+        },
+        "context" => {
+          "serviceName" => @config.service_name,
+          "environment" => @config.environment,
+          "release" => @config.release,
+          "runtime" => "ruby",
+          "rubyVersion" => RUBY_VERSION
+        },
+        "trace" => trace_id ? { "traceId" => trace_id, "spanId" => span_id } : nil,
+        "user" => resolved_user && !resolved_user.empty? ? resolved_user : nil,
+        "tags" => merged_tags.empty? ? nil : merged_tags,
+        "extra" => (extra || {}).empty? ? nil : extra.transform_keys(&:to_s),
+        "fingerprint" => fingerprint
+      }
+    end
+
+    # Serialize an error value into the error payload shape.
+    #
+    # @param value [Exception, String, Object] the error to serialize
+    # @return [Hash] with "message", "type", "stack" keys
+    def serialize_error(value)
+      case value
+      when Exception
+        {
+          "message" => value.message.to_s.empty? ? value.class.name : value.message,
+          "type" => value.class.name,
+          "stack" => value.backtrace&.join("\n")
+        }
+      when String
+        { "message" => value, "type" => "Error", "stack" => nil }
+      else
+        { "message" => value.to_s, "type" => "Error", "stack" => nil }
+      end
+    end
+  end
+end

data/lib/justanalytics/configuration.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Configuration object holding all SDK settings.
+  #
+  # @example
+  #   JustAnalytics.init(
+  #     site_id: "site_abc123",
+  #     api_key: "ja_sk_your_api_key_here",
+  #     service_name: "rails-api",
+  #     environment: "production",
+  #     release: "1.2.3"
+  #   )
+  class Configuration
+    # @return [String] Site ID from JustAnalytics dashboard (required).
+    attr_accessor :site_id
+
+    # @return [String] API key from JustAnalytics dashboard (required).
+    attr_accessor :api_key
+
+    # @return [String] Service name, e.g. "rails-api", "worker" (required).
+    attr_accessor :service_name
+
+    # @return [String, nil] Deployment environment, e.g. "production", "staging".
+    attr_accessor :environment
+
+    # @return [String, nil] Release/version string, e.g. "1.2.3", git SHA.
+    attr_accessor :release
+
+    # @return [String] Base URL of JustAnalytics server.
+    attr_accessor :server_url
+
+    # @return [Boolean] Enable debug logging to $stderr (default: false).
+    attr_accessor :debug
+
+    # @return [Float] Flush interval in seconds (default: 2.0).
+    attr_accessor :flush_interval
+
+    # @return [Integer] Maximum items per batch before immediate flush (default: 100).
+    attr_accessor :max_batch_size
+
+    # @return [Boolean] Enable/disable the SDK (default: true).
+    attr_accessor :enabled
+
+    # Default JustAnalytics server URL.
+    DEFAULT_SERVER_URL = "https://justanalytics.up.railway.app"
+
+    def initialize
+      @site_id = nil
+      @api_key = nil
+      @service_name = nil
+      @environment = nil
+      @release = nil
+      @server_url = ENV.fetch("JUSTANALYTICS_URL", DEFAULT_SERVER_URL)
+      @debug = false
+      @flush_interval = 2.0
+      @max_batch_size = 100
+      @enabled = true
+    end
+
+    # Validate that all required fields are present.
+    #
+    # @raise [ArgumentError] if any required field is missing
+    # @return [void]
+    def validate!
+      raise ArgumentError, "[JustAnalytics] init() requires :site_id. Get it from your JustAnalytics dashboard." if site_id.nil? || site_id.to_s.empty?
+      raise ArgumentError, "[JustAnalytics] init() requires :api_key. Create one in your JustAnalytics site settings." if api_key.nil? || api_key.to_s.empty?
+      raise ArgumentError, '[JustAnalytics] init() requires :service_name (e.g. "rails-api", "worker").' if service_name.nil? || service_name.to_s.empty?
+    end
+  end
+end

data/lib/justanalytics/context.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Thread-local context propagation for distributed tracing.
+  #
+  # Uses +Thread.current+ for fiber-safe storage. Context is automatically
+  # inherited when new fibers are created within a traced scope.
+  #
+  # @example
+  #   JustAnalytics::Context.current_span  #=> Span or nil
+  #   JustAnalytics::Context.current_trace_id #=> String or nil
+  module Context
+    THREAD_KEY = :justanalytics_context
+
+    # Internal context data structure.
+    ContextData = Struct.new(:active_span, :trace_id, :user, :tags, keyword_init: true) do
+      def initialize(active_span: nil, trace_id: nil, user: nil, tags: {})
+        super
+      end
+    end
+
+    class << self
+      # Get the current context from Thread.current.
+      #
+      # @return [ContextData, nil]
+      def current
+        Thread.current[THREAD_KEY]
+      end
+
+      # Set the current context on Thread.current.
+      #
+      # @param ctx [ContextData, nil]
+      # @return [void]
+      def current=(ctx)
+        Thread.current[THREAD_KEY] = ctx
+      end
+
+      # Get the currently active span.
+      #
+      # @return [Span, nil]
+      def current_span
+        current&.active_span
+      end
+
+      # Get the current trace ID.
+      #
+      # @return [String, nil]
+      def current_trace_id
+        current&.trace_id
+      end
+
+      # Get the current user context.
+      #
+      # @return [Hash, nil]
+      def current_user
+        current&.user
+      end
+
+      # Get the current tags.
+      #
+      # @return [Hash]
+      def current_tags
+        current&.tags || {}
+      end
+
+      # Set user context on the current scope.
+      #
+      # @param user [Hash] user context with :id, :email, :username keys
+      # @return [void]
+      def set_user(user)
+        ctx = current
+        return unless ctx
+
+        ctx.user = user
+      end
+
+      # Set a tag on the current scope.
+      #
+      # @param key [String] tag key
+      # @param value [String] tag value
+      # @return [void]
+      def set_tag(key, value)
+        ctx = current
+        return unless ctx
+
+        # Copy-on-write semantics
+        ctx.tags = ctx.tags.merge(key.to_s => value.to_s)
+      end
+
+      # Run a block within a new context scope.
+      #
+      # Saves the previous context, sets the new one, yields, and
+      # restores the previous context afterward (even on exception).
+      #
+      # @param ctx [ContextData] the context to activate
+      # @yield the block to run within the context
+      # @return the return value of the block
+      def with_context(ctx)
+        previous = current
+        self.current = ctx
+        yield
+      ensure
+        self.current = previous
+      end
+
+      # Create a child context inheriting from the current one.
+      #
+      # @param active_span [Span, nil] the span to set as active
+      # @param trace_id [String, nil] trace ID override
+      # @return [ContextData]
+      def create_child(active_span: nil, trace_id: nil)
+        parent = current || ContextData.new
+        ContextData.new(
+          active_span: active_span || parent.active_span,
+          trace_id: trace_id || parent.trace_id,
+          user: parent.user,
+          tags: parent.tags.dup
+        )
+      end
+    end
+  end
+end