justanalytics 0.1.0

data/lib/justanalytics/trace_context.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module JustAnalytics
+  # W3C Trace Context traceparent header parsing and serialization.
+  #
+  # Format: "00-{traceId}-{spanId}-{flags}"
+  # - version: "00" (only supported version)
+  # - traceId: 32-char lowercase hex (128-bit, must not be all zeros)
+  # - spanId: 16-char lowercase hex (64-bit, must not be all zeros)
+  # - flags: 2-char hex ("01" = sampled, "00" = not sampled)
+  #
+  # @see https://www.w3.org/TR/trace-context/
+  module TraceContext
+    TRACE_ID_REGEX = /\A[0-9a-f]{32}\z/
+    SPAN_ID_REGEX  = /\A[0-9a-f]{16}\z/
+    FLAGS_REGEX    = /\A[0-9a-f]{2}\z/
+    ZERO_TRACE_ID  = "0" * 32
+    ZERO_SPAN_ID   = "0" * 16
+
+    # Parsed traceparent data.
+    TraceparentData = Struct.new(:version, :trace_id, :parent_span_id, :trace_flags, keyword_init: true)
+
+    class << self
+      # Generate a 32-character lowercase hex trace ID (128-bit).
+      #
+      # @return [String] 32-character hex string
+      def generate_trace_id
+        SecureRandom.hex(16)
+      end
+
+      # Generate a 16-character lowercase hex span ID (64-bit).
+      #
+      # @return [String] 16-character hex string
+      def generate_span_id
+        SecureRandom.hex(8)
+      end
+
+      # Parse a W3C traceparent header string.
+      #
+      # @param header [String] the traceparent header value
+      # @return [TraceparentData, nil] parsed data or nil if invalid
+      #
+      # @example
+      #   data = TraceContext.parse_traceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
+      #   data.trace_id #=> "4bf92f3577b34da6a3ce929d0e0e4736"
+      def parse_traceparent(header)
+        return nil unless header.is_a?(String)
+
+        parts = header.split("-")
+        return nil unless parts.length == 4
+
+        version, trace_id, parent_span_id, trace_flags = parts
+
+        return nil unless version == "00"
+        return nil unless TRACE_ID_REGEX.match?(trace_id) && trace_id != ZERO_TRACE_ID
+        return nil unless SPAN_ID_REGEX.match?(parent_span_id) && parent_span_id != ZERO_SPAN_ID
+        return nil unless FLAGS_REGEX.match?(trace_flags)
+
+        TraceparentData.new(
+          version: version,
+          trace_id: trace_id,
+          parent_span_id: parent_span_id,
+          trace_flags: trace_flags
+        )
+      end
+
+      # Serialize a W3C traceparent header string.
+      #
+      # @param trace_id [String] 32-character hex trace ID
+      # @param span_id [String] 16-character hex span ID
+      # @param sampled [Boolean] whether the trace is sampled (default: true)
+      # @return [String] formatted traceparent header
+      #
+      # @example
+      #   TraceContext.serialize_traceparent("4bf92f...", "00f067...", true)
+      #   #=> "00-4bf92f...-00f067...-01"
+      def serialize_traceparent(trace_id, span_id, sampled: true)
+        flags = sampled ? "01" : "00"
+        "00-#{trace_id}-#{span_id}-#{flags}"
+      end
+    end
+  end
+end

data/lib/justanalytics/transport.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module JustAnalytics
+  # Threaded batch transport for sending data to JustAnalytics ingestion endpoints.
+  #
+  # Collects spans, errors, logs, and metrics in separate thread-safe queues.
+  # A background thread periodically flushes each queue to its respective endpoint:
+  # - Spans:   +POST /api/ingest/spans+   (batched array)
+  # - Errors:  +POST /api/ingest/errors+  (batched array)
+  # - Logs:    +POST /api/ingest/logs+    (batched array)
+  # - Metrics: +POST /api/ingest/metrics+ (batched array)
+  #
+  # Uses Ruby's +Thread::Queue+ for thread-safe buffering and +at_exit+ for
+  # graceful shutdown.
+  class Transport
+    # @return [Integer] number of spans pending flush
+    attr_reader :pending_span_count
+
+    # @param server_url [String] base URL of JustAnalytics server
+    # @param api_key [String] API key for Authorization header
+    # @param site_id [String] site ID for X-Site-ID header
+    # @param flush_interval [Float] flush interval in seconds
+    # @param max_batch_size [Integer] max items per batch
+    # @param debug [Boolean] enable debug logging
+    def initialize(server_url:, api_key:, site_id:, flush_interval: 2.0, max_batch_size: 100, debug: false)
+      @server_url = server_url
+      @api_key = api_key
+      @site_id = site_id
+      @flush_interval = flush_interval
+      @max_batch_size = max_batch_size
+      @debug = debug
+
+      @span_queue = Thread::Queue.new
+      @error_queue = Thread::Queue.new
+      @log_queue = Thread::Queue.new
+      @metric_queue = Thread::Queue.new
+
+      @pending_span_count = 0
+      @mutex = Mutex.new
+      @running = false
+      @worker_thread = nil
+    end
+
+    # Start the background flush worker thread.
+    #
+    # @return [void]
+    def start
+      return if @running
+
+      @running = true
+      @worker_thread = Thread.new { flush_loop }
+      @worker_thread.abort_on_exception = false
+
+      # Register at_exit hook for graceful shutdown
+      at_exit { shutdown }
+    end
+
+    # Stop the background worker and flush remaining data.
+    #
+    # @return [void]
+    def shutdown
+      return unless @running
+
+      @running = false
+      @worker_thread&.wakeup rescue nil
+      @worker_thread&.join(5)
+      flush_all
+    end
+
+    # Enqueue a span payload for batched sending.
+    #
+    # @param span_hash [Hash] serialized span data
+    # @return [void]
+    def enqueue_span(span_hash)
+      @span_queue << span_hash
+      @mutex.synchronize { @pending_span_count += 1 }
+    end
+
+    # Enqueue an error payload for batched sending.
+    #
+    # @param error_hash [Hash] serialized error data
+    # @return [void]
+    def enqueue_error(error_hash)
+      @error_queue << error_hash
+    end
+
+    # Enqueue a log entry for batched sending.
+    #
+    # @param log_hash [Hash] serialized log entry data
+    # @return [void]
+    def enqueue_log(log_hash)
+      @log_queue << log_hash
+    end
+
+    # Enqueue a metric data point for batched sending.
+    #
+    # @param metric_hash [Hash] serialized metric data
+    # @return [void]
+    def enqueue_metric(metric_hash)
+      @metric_queue << metric_hash
+    end
+
+    # Flush all pending data to the server immediately.
+    #
+    # @return [void]
+    def flush
+      flush_all
+    end
+
+    private
+
+    # Background loop that periodically flushes all queues.
+    def flush_loop
+      while @running
+        sleep(@flush_interval)
+        flush_all
+      end
+    rescue => e
+      debug_log("Flush loop error: #{e.message}")
+    end
+
+    # Drain all queues and send batched requests.
+    def flush_all
+      flush_queue(@span_queue, "/api/ingest/spans", "spans") do |batch|
+        @mutex.synchronize { @pending_span_count -= batch.size }
+        { "spans" => batch }
+      end
+
+      flush_queue(@error_queue, "/api/ingest/errors", "errors") do |batch|
+        { "errors" => batch }
+      end
+
+      flush_queue(@log_queue, "/api/ingest/logs", "logs") do |batch|
+        { "logs" => batch }
+      end
+
+      flush_queue(@metric_queue, "/api/ingest/metrics", "metrics") do |batch|
+        { "metrics" => batch }
+      end
+    end
+
+    # Drain items from a queue and send in batches.
+    #
+    # @param queue [Thread::Queue] the queue to drain
+    # @param path [String] API endpoint path
+    # @param label [String] human-readable label for debug logs
+    # @yield [Array<Hash>] batch of items to wrap in request body
+    def flush_queue(queue, path, label)
+      return if queue.empty?
+
+      batch = []
+      batch << queue.pop(true) until queue.empty? || batch.size >= @max_batch_size rescue nil
+
+      return if batch.empty?
+
+      body = yield(batch)
+      send_request(path, body, label, batch.size)
+    end
+
+    # Send an HTTP POST request to the given endpoint.
+    #
+    # @param path [String] API path (e.g. "/api/ingest/spans")
+    # @param body [Hash] request body to JSON-encode
+    # @param label [String] label for debug messages
+    # @param count [Integer] number of items in the batch
+    def send_request(path, body, label, count)
+      uri = URI.join(@server_url, path)
+      json_body = JSON.generate(body)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 5
+      http.read_timeout = 10
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["X-Site-ID"] = @site_id
+      request["User-Agent"] = "justanalytics-ruby/#{JustAnalytics::VERSION}"
+      request.body = json_body
+
+      response = http.request(request)
+
+      case response.code.to_i
+      when 200..299
+        debug_log("Flushed #{count} #{label} successfully")
+      when 429
+        debug_log("Rate limited (429). Dropped #{count} #{label}.")
+      else
+        debug_log("Flush failed with HTTP #{response.code}. Dropped #{count} #{label}. Response: #{response.body}")
+      end
+    rescue => e
+      debug_log("Network error flushing #{label}: #{e.message}. Dropped #{count} #{label}.")
+    end
+
+    def debug_log(message)
+      $stderr.puts "[JustAnalytics] #{message}" if @debug
+    end
+  end
+end

data/lib/justanalytics/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JustAnalytics
+  # Current gem version.
+  VERSION = "0.1.0"
+end

data/lib/justanalytics.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+# JustAnalytics Ruby SDK
+#
+# End-to-end observability for Ruby applications. Provides distributed tracing,
+# error tracking, structured logging, and infrastructure metrics reporting
+# to the JustAnalytics platform.
+#
+# @example Quick start
+#   require "justanalytics"
+#
+#   JustAnalytics.init(
+#     site_id: "site_abc123",
+#     api_key: "ja_sk_your_key_here",
+#     service_name: "rails-api",
+#     environment: "production"
+#   )
+#
+#   JustAnalytics.start_span("process-order") do |span|
+#     span.set_attribute("order.id", "12345")
+#     # ... your code ...
+#   end
+#
+# @see https://justanalytics.app/docs/ruby-sdk
+module JustAnalytics
+  class Error < StandardError; end
+
+  autoload :VERSION,        "justanalytics/version"
+  autoload :Configuration,  "justanalytics/configuration"
+  autoload :Context,        "justanalytics/context"
+  autoload :TraceContext,   "justanalytics/trace_context"
+  autoload :Span,           "justanalytics/span"
+  autoload :Transport,      "justanalytics/transport"
+  autoload :Logger,         "justanalytics/logger"
+  autoload :Client,         "justanalytics/client"
+
+  # Integrations
+  autoload :RailsMiddleware,         "justanalytics/integrations/rails"
+  autoload :Railtie,                 "justanalytics/integrations/rails"
+  autoload :SidekiqServerMiddleware, "justanalytics/integrations/sidekiq"
+  autoload :SidekiqClientMiddleware, "justanalytics/integrations/sidekiq"
+  autoload :NetHttpPatch,            "justanalytics/integrations/net_http"
+
+  class << self
+    # Get the singleton client instance.
+    #
+    # @return [Client]
+    def client
+      @client ||= Client.new
+    end
+
+    # Initialize the JustAnalytics SDK.
+    #
+    # Must be called before any other SDK method. Can only be called once;
+    # subsequent calls log a warning and are ignored.
+    #
+    # @param site_id [String] site ID from JustAnalytics dashboard (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 (default: false)
+    # @param flush_interval [Float] flush interval in seconds (default: 2.0)
+    # @param max_batch_size [Integer] max batch size (default: 100)
+    # @param enabled [Boolean] enable/disable SDK (default: true)
+    # @return [void]
+    #
+    # @example
+    #   JustAnalytics.init(
+    #     site_id: "site_abc123",
+    #     api_key: "ja_sk_your_key_here",
+    #     service_name: "rails-api",
+    #     environment: "production",
+    #     release: "1.2.3"
+    #   )
+    def init(site_id:, api_key:, service_name:, **options)
+      client.init(site_id: site_id, api_key: api_key, service_name: service_name, **options)
+    end
+
+    # Whether the SDK has been initialized.
+    #
+    # @return [Boolean]
+    def initialized?
+      client.initialized?
+    end
+
+    # Create and execute a span.
+    #
+    # @param name [String] operation name
+    # @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("fetch-user", op: "db") do |span|
+    #     span.set_attribute("user.id", user_id)
+    #     User.find(user_id)
+    #   end
+    def start_span(name, op: "internal", attributes: {}, &block)
+      client.start_span(name, op: op, attributes: attributes, &block)
+    end
+
+    # Capture an exception and send it to JustAnalytics.
+    #
+    # @param error [Exception, String] the error to capture
+    # @param tags [Hash] additional tags
+    # @param extra [Hash] arbitrary extra data
+    # @param user [Hash, nil] user context override
+    # @return [String] unique event ID
+    #
+    # @example
+    #   begin
+    #     risky_operation
+    #   rescue => e
+    #     JustAnalytics.capture_exception(e, tags: { module: "payments" })
+    #   end
+    def capture_exception(error, **options)
+      client.capture_exception(error, **options)
+    end
+
+    # Capture a message and send it to JustAnalytics.
+    #
+    # @param message [String] the message
+    # @param level [String] severity level (default: "info")
+    # @param tags [Hash] additional tags
+    # @return [String] unique event ID
+    #
+    # @example
+    #   JustAnalytics.capture_message("Rate limit exceeded", level: "warning")
+    def capture_message(message, **options)
+      client.capture_message(message, **options)
+    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]
+    #
+    # @example
+    #   JustAnalytics.set_user(id: "user-123", email: "alice@example.com")
+    def set_user(id: nil, email: nil, username: nil)
+      client.set_user(id: id, email: email, username: username)
+    end
+
+    # Set a tag on the current thread scope.
+    #
+    # @param key [String] tag key
+    # @param value [String] tag value
+    # @return [void]
+    #
+    # @example
+    #   JustAnalytics.set_tag("feature", "checkout")
+    def set_tag(key, value)
+      client.set_tag(key, value)
+    end
+
+    # Get the structured logger instance.
+    #
+    # @return [Logger] the logger (no-op logger if SDK not initialized)
+    def logger
+      client.logger || Logger.new(
+        service_name: "unknown",
+        transport: nil,
+        enabled: false
+      )
+    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: {})
+      client.record_metric(metric_name, value, tags: tags)
+    end
+
+    # Flush all pending data to the server.
+    #
+    # @return [void]
+    def flush
+      client.flush
+    end
+
+    # Shut down the SDK.
+    #
+    # @return [void]
+    def close
+      client.close
+    end
+
+    # Reset the singleton client (primarily for testing).
+    #
+    # @return [void]
+    # @api private
+    def reset!
+      client.close if client.initialized?
+      @client = nil
+    end
+  end
+end
+
+# Auto-load Railtie if Rails is present
+require "justanalytics/integrations/rails" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: justanalytics
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Velocity Digital Labs
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Distributed tracing, error tracking, structured logging, and infrastructure
+  metrics for Ruby applications. Ships data to the JustAnalytics platform via batched
+  HTTP transport with automatic trace context propagation.
+email:
+- support@velocitydigitallabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/justanalytics.rb
+- lib/justanalytics/client.rb
+- lib/justanalytics/configuration.rb
+- lib/justanalytics/context.rb
+- lib/justanalytics/integrations/net_http.rb
+- lib/justanalytics/integrations/rails.rb
+- lib/justanalytics/integrations/sidekiq.rb
+- lib/justanalytics/logger.rb
+- lib/justanalytics/span.rb
+- lib/justanalytics/trace_context.rb
+- lib/justanalytics/transport.rb
+- lib/justanalytics/version.rb
+homepage: https://justanalytics.app
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://justanalytics.app
+  source_code_uri: https://github.com/velocitydigitallabs/justanalytics-ruby
+  changelog_uri: https://github.com/velocitydigitallabs/justanalytics-ruby/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: JustAnalytics Ruby SDK - End-to-end observability for Ruby applications
+test_files: []