brainzlab 0.1.0

data/lib/brainzlab/pulse/propagation.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Pulse
+    # Distributed tracing context propagation using W3C Trace Context format
+    # https://www.w3.org/TR/trace-context/
+    module Propagation
+      # W3C Trace Context header names
+      TRACEPARENT_HEADER = "traceparent"
+      TRACESTATE_HEADER = "tracestate"
+
+      # HTTP header versions (with HTTP_ prefix for Rack env)
+      HTTP_TRACEPARENT = "HTTP_TRACEPARENT"
+      HTTP_TRACESTATE = "HTTP_TRACESTATE"
+
+      # Also support B3 format for compatibility
+      B3_TRACE_ID = "X-B3-TraceId"
+      B3_SPAN_ID = "X-B3-SpanId"
+      B3_SAMPLED = "X-B3-Sampled"
+      B3_PARENT_SPAN_ID = "X-B3-ParentSpanId"
+
+      class Context
+        attr_accessor :trace_id, :span_id, :parent_span_id, :sampled, :tracestate
+
+        def initialize(trace_id: nil, span_id: nil, parent_span_id: nil, sampled: true, tracestate: nil)
+          @trace_id = trace_id || generate_trace_id
+          @span_id = span_id || generate_span_id
+          @parent_span_id = parent_span_id
+          @sampled = sampled
+          @tracestate = tracestate
+        end
+
+        def valid?
+          @trace_id && @span_id
+        end
+
+        def to_h
+          {
+            trace_id: @trace_id,
+            span_id: @span_id,
+            parent_span_id: @parent_span_id,
+            sampled: @sampled,
+            tracestate: @tracestate
+          }.compact
+        end
+
+        private
+
+        def generate_trace_id
+          SecureRandom.hex(16) # 32 hex chars = 128 bits
+        end
+
+        def generate_span_id
+          SecureRandom.hex(8) # 16 hex chars = 64 bits
+        end
+      end
+
+      class << self
+        # Get current propagation context from thread local
+        def current
+          Thread.current[:brainzlab_propagation_context]
+        end
+
+        # Set current propagation context
+        def current=(context)
+          Thread.current[:brainzlab_propagation_context] = context
+        end
+
+        # Create new context and set as current
+        def start(trace_id: nil, parent_span_id: nil)
+          self.current = Context.new(
+            trace_id: trace_id,
+            parent_span_id: parent_span_id
+          )
+        end
+
+        # Clear current context
+        def clear!
+          Thread.current[:brainzlab_propagation_context] = nil
+        end
+
+        # Inject trace context into outgoing HTTP headers
+        # @param headers [Hash] the headers hash to inject into
+        # @param context [Context] optional context (defaults to current)
+        # @param format [Symbol] :w3c (default), :b3, or :all
+        def inject(headers, context: nil, format: :w3c)
+          ctx = context || current
+          return headers unless ctx&.valid?
+
+          case format
+          when :w3c
+            inject_w3c(headers, ctx)
+          when :b3
+            inject_b3(headers, ctx)
+          when :all
+            inject_w3c(headers, ctx)
+            inject_b3(headers, ctx)
+          end
+
+          headers
+        end
+
+        # Extract trace context from incoming HTTP headers (Rack env or plain headers)
+        # @param headers [Hash] the headers to extract from
+        # @return [Context, nil] the extracted context or nil
+        def extract(headers)
+          # Try W3C format first
+          ctx = extract_w3c(headers)
+          return ctx if ctx
+
+          # Fall back to B3 format
+          extract_b3(headers)
+        end
+
+        # Extract and set as current context
+        # Returns the context for chaining
+        def extract!(headers)
+          self.current = extract(headers)
+        end
+
+        # Create a child context for a new span
+        def child_context(parent: nil)
+          parent ||= current
+          return Context.new unless parent&.valid?
+
+          Context.new(
+            trace_id: parent.trace_id,
+            parent_span_id: parent.span_id,
+            sampled: parent.sampled,
+            tracestate: parent.tracestate
+          )
+        end
+
+        private
+
+        # W3C Trace Context format injection
+        # traceparent: version-traceid-spanid-flags
+        # Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+        def inject_w3c(headers, ctx)
+          version = "00"
+          flags = ctx.sampled ? "01" : "00"
+          trace_id = normalize_trace_id(ctx.trace_id, 32)
+          span_id = normalize_trace_id(ctx.span_id, 16)
+
+          headers[TRACEPARENT_HEADER] = "#{version}-#{trace_id}-#{span_id}-#{flags}"
+          headers[TRACESTATE_HEADER] = ctx.tracestate if ctx.tracestate
+
+          headers
+        end
+
+        # W3C Trace Context format extraction
+        def extract_w3c(headers)
+          traceparent = headers[TRACEPARENT_HEADER] ||
+                        headers[HTTP_TRACEPARENT] ||
+                        headers["Traceparent"]
+          return nil unless traceparent
+
+          # Parse: version-traceid-spanid-flags
+          parts = traceparent.to_s.split("-")
+          return nil if parts.length < 4
+
+          version, trace_id, span_id, flags = parts
+
+          # Validate version
+          return nil unless version == "00"
+
+          # Validate trace_id (32 hex chars, not all zeros)
+          return nil unless trace_id&.match?(/\A[a-f0-9]{32}\z/i)
+          return nil if trace_id == "0" * 32
+
+          # Validate span_id (16 hex chars, not all zeros)
+          return nil unless span_id&.match?(/\A[a-f0-9]{16}\z/i)
+          return nil if span_id == "0" * 16
+
+          sampled = flags.to_i(16) & 0x01 == 1
+
+          tracestate = headers[TRACESTATE_HEADER] ||
+                       headers[HTTP_TRACESTATE] ||
+                       headers["Tracestate"]
+
+          Context.new(
+            trace_id: trace_id,
+            span_id: span_id,
+            sampled: sampled,
+            tracestate: tracestate
+          )
+        rescue StandardError
+          nil
+        end
+
+        # B3 format injection (Zipkin compatibility)
+        def inject_b3(headers, ctx)
+          headers[B3_TRACE_ID] = normalize_trace_id(ctx.trace_id, 32)
+          headers[B3_SPAN_ID] = normalize_trace_id(ctx.span_id, 16)
+          headers[B3_SAMPLED] = ctx.sampled ? "1" : "0"
+          headers[B3_PARENT_SPAN_ID] = ctx.parent_span_id if ctx.parent_span_id
+
+          headers
+        end
+
+        # B3 format extraction
+        def extract_b3(headers)
+          trace_id = headers[B3_TRACE_ID] ||
+                     headers["HTTP_X_B3_TRACEID"] ||
+                     headers["x-b3-traceid"]
+          return nil unless trace_id
+
+          span_id = headers[B3_SPAN_ID] ||
+                    headers["HTTP_X_B3_SPANID"] ||
+                    headers["x-b3-spanid"]
+          return nil unless span_id
+
+          sampled_header = headers[B3_SAMPLED] ||
+                           headers["HTTP_X_B3_SAMPLED"] ||
+                           headers["x-b3-sampled"]
+          sampled = sampled_header != "0"
+
+          parent_span_id = headers[B3_PARENT_SPAN_ID] ||
+                           headers["HTTP_X_B3_PARENTSPANID"] ||
+                           headers["x-b3-parentspanid"]
+
+          Context.new(
+            trace_id: trace_id,
+            span_id: span_id,
+            parent_span_id: parent_span_id,
+            sampled: sampled
+          )
+        rescue StandardError
+          nil
+        end
+
+        def normalize_trace_id(id, length)
+          return nil unless id
+
+          hex = id.to_s.gsub("-", "").downcase
+          hex.rjust(length, "0").slice(0, length)
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/pulse/provisioner.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "fileutils"
+
+module BrainzLab
+  module Pulse
+    class Provisioner
+      CACHE_DIR = ENV.fetch("BRAINZLAB_CACHE_DIR") { File.join(Dir.home, ".brainzlab") }
+
+      def initialize(config)
+        @config = config
+      end
+
+      def ensure_project!
+        return unless should_provision?
+
+        # Try cached credentials first
+        if (cached = load_cached_credentials)
+          apply_credentials(cached)
+          return cached
+        end
+
+        # Provision new project
+        project = provision_project
+        return unless project
+
+        # Cache and apply credentials
+        cache_credentials(project)
+        apply_credentials(project)
+
+        project
+      end
+
+      private
+
+      def should_provision?
+        return false unless @config.pulse_auto_provision
+        return false unless @config.app_name.to_s.strip.length > 0
+        # Only skip if pulse_api_key is already set
+        return false if @config.pulse_api_key.to_s.strip.length > 0
+        return false unless @config.pulse_master_key.to_s.strip.length > 0
+
+        true
+      end
+
+      def provision_project
+        uri = URI.parse("#{@config.pulse_url}/api/v1/projects/provision")
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["X-Master-Key"] = @config.pulse_master_key
+        request["User-Agent"] = "brainzlab-sdk-ruby/#{BrainzLab::VERSION}"
+        request.body = JSON.generate({ name: @config.app_name })
+
+        response = execute(uri, request)
+        return nil unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body, symbolize_names: true)
+      rescue StandardError => e
+        log_error("Failed to provision Pulse project: #{e.message}")
+        nil
+      end
+
+      def load_cached_credentials
+        path = cache_file_path
+        return nil unless File.exist?(path)
+
+        data = JSON.parse(File.read(path), symbolize_names: true)
+
+        # Validate cached data has required keys
+        return nil unless data[:api_key]
+
+        data
+      rescue StandardError => e
+        log_error("Failed to load cached Pulse credentials: #{e.message}")
+        nil
+      end
+
+      def cache_credentials(project)
+        FileUtils.mkdir_p(CACHE_DIR)
+        File.write(cache_file_path, JSON.generate(project))
+      rescue StandardError => e
+        log_error("Failed to cache Pulse credentials: #{e.message}")
+      end
+
+      def cache_file_path
+        File.join(CACHE_DIR, "#{@config.app_name}.pulse.json")
+      end
+
+      def apply_credentials(project)
+        @config.pulse_api_key = project[:api_key]
+
+        # Also set service name from app_name if not already set
+        @config.service ||= @config.app_name
+      end
+
+      def execute(uri, request)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        http.request(request)
+      end
+
+      def log_error(message)
+        return unless @config.logger
+
+        @config.logger.error("[BrainzLab::Pulse] #{message}")
+      end
+    end
+  end
+end

data/lib/brainzlab/pulse/tracer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Pulse
+    class Tracer
+      def initialize(config, client)
+        @config = config
+        @client = client
+      end
+
+      def current_trace
+        Thread.current[:brainzlab_pulse_trace]
+      end
+
+      def current_spans
+        Thread.current[:brainzlab_pulse_spans] ||= []
+      end
+
+      def start_trace(name, kind: "custom", **attributes)
+        trace = {
+          trace_id: SecureRandom.uuid,
+          name: name,
+          kind: kind,
+          started_at: Time.now.utc,
+          environment: @config.environment,
+          commit: @config.commit,
+          host: @config.host,
+          **attributes
+        }
+
+        Thread.current[:brainzlab_pulse_trace] = trace
+        Thread.current[:brainzlab_pulse_spans] = []
+
+        trace
+      end
+
+      def finish_trace(error: false, error_class: nil, error_message: nil)
+        trace = current_trace
+        return unless trace
+
+        ended_at = Time.now.utc
+        duration_ms = ((ended_at - trace[:started_at]) * 1000).round(2)
+
+        payload = trace.merge(
+          ended_at: ended_at.iso8601(3),
+          started_at: trace[:started_at].utc.iso8601(3),
+          duration_ms: duration_ms,
+          error: error,
+          error_class: error_class,
+          error_message: error_message,
+          spans: current_spans.map { |s| format_span(s, trace[:started_at]) }
+        ).compact
+
+        # Add request context if available
+        ctx = Context.current
+        payload[:request_id] ||= ctx.request_id
+        payload[:user_id] ||= ctx.user&.dig(:id)&.to_s
+
+        @client.send_trace(payload)
+
+        Thread.current[:brainzlab_pulse_trace] = nil
+        Thread.current[:brainzlab_pulse_spans] = nil
+
+        payload
+      end
+
+      def span(name, kind: "custom", **data)
+        span_data = {
+          span_id: SecureRandom.uuid,
+          name: name,
+          kind: kind,
+          started_at: Time.now.utc,
+          data: data
+        }
+
+        begin
+          result = yield
+          span_data[:error] = false
+          result
+        rescue StandardError => e
+          span_data[:error] = true
+          span_data[:error_class] = e.class.name
+          span_data[:error_message] = e.message
+          raise
+        ensure
+          span_data[:ended_at] = Time.now.utc
+          span_data[:duration_ms] = ((span_data[:ended_at] - span_data[:started_at]) * 1000).round(2)
+          current_spans << span_data
+        end
+      end
+
+      private
+
+      def format_span(span, trace_started_at)
+        {
+          span_id: span[:span_id],
+          parent_span_id: span[:parent_span_id],
+          name: span[:name],
+          kind: span[:kind],
+          started_at: span[:started_at].utc.iso8601(3),
+          ended_at: span[:ended_at].utc.iso8601(3),
+          duration_ms: span[:duration_ms],
+          error: span[:error],
+          error_class: span[:error_class],
+          error_message: span[:error_message],
+          data: span[:data]
+        }.compact
+      end
+    end
+  end
+end

data/lib/brainzlab/pulse.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require_relative "pulse/client"
+require_relative "pulse/provisioner"
+require_relative "pulse/tracer"
+require_relative "pulse/instrumentation"
+require_relative "pulse/propagation"
+
+module BrainzLab
+  module Pulse
+    class << self
+      # Start a new trace
+      # @param name [String] the trace name
+      # @param kind [String] trace kind (request, job, custom)
+      # @param parent_context [Propagation::Context] optional parent context for distributed tracing
+      def start_trace(name, kind: "custom", parent_context: nil, **attributes)
+        return nil unless enabled?
+
+        ensure_provisioned!
+        return nil unless BrainzLab.configuration.pulse_valid?
+
+        # Use parent context trace_id if provided (distributed tracing)
+        if parent_context&.valid?
+          attributes[:parent_trace_id] = parent_context.trace_id
+          attributes[:parent_span_id] = parent_context.span_id
+        end
+
+        tracer.start_trace(name, kind: kind, **attributes)
+      end
+
+      # Finish current trace
+      def finish_trace(error: false, error_class: nil, error_message: nil)
+        return unless enabled?
+
+        tracer.finish_trace(error: error, error_class: error_class, error_message: error_message)
+      end
+
+      # Add a span to the current trace
+      def span(name, kind: "custom", **data)
+        return yield unless enabled?
+        return yield unless tracer.current_trace
+
+        tracer.span(name, kind: kind, **data) { yield }
+      end
+
+      # Record a complete trace (for when you have all data upfront)
+      def record_trace(name, kind: "request", started_at:, ended_at:, **attributes)
+        return unless enabled?
+
+        ensure_provisioned!
+        return unless BrainzLab.configuration.pulse_valid?
+
+        payload = build_trace_payload(name, kind, started_at, ended_at, attributes)
+        client.send_trace(payload)
+      end
+
+      # Record a custom metric
+      def record_metric(name, value:, kind: "gauge", tags: {})
+        return unless enabled?
+
+        ensure_provisioned!
+        return unless BrainzLab.configuration.pulse_valid?
+
+        payload = {
+          name: name,
+          value: value,
+          kind: kind,
+          timestamp: Time.now.utc.iso8601(3),
+          tags: tags
+        }
+
+        client.send_metric(payload)
+      end
+
+      # Convenience methods for metrics
+      def gauge(name, value, tags: {})
+        record_metric(name, value: value, kind: "gauge", tags: tags)
+      end
+
+      def counter(name, value = 1, tags: {})
+        record_metric(name, value: value, kind: "counter", tags: tags)
+      end
+
+      def histogram(name, value, tags: {})
+        record_metric(name, value: value, kind: "histogram", tags: tags)
+      end
+
+      def ensure_provisioned!
+        return if @provisioned
+
+        @provisioned = true
+        provisioner.ensure_project!
+      end
+
+      def provisioner
+        @provisioner ||= Provisioner.new(BrainzLab.configuration)
+      end
+
+      def tracer
+        @tracer ||= Tracer.new(BrainzLab.configuration, client)
+      end
+
+      def client
+        @client ||= Client.new(BrainzLab.configuration)
+      end
+
+      def reset!
+        @client = nil
+        @tracer = nil
+        @provisioner = nil
+        @provisioned = false
+        Propagation.clear!
+      end
+
+      # Distributed tracing: inject trace context into outgoing headers
+      # @param headers [Hash] the headers hash to inject into
+      # @param format [Symbol] :w3c (default), :b3, or :all
+      # @return [Hash] the headers with trace context added
+      def inject(headers, format: :w3c)
+        ctx = Propagation.current || create_propagation_context
+        Propagation.inject(headers, context: ctx, format: format)
+      end
+
+      # Distributed tracing: extract trace context from incoming headers
+      # @param headers [Hash] incoming headers (Rack env or plain headers)
+      # @return [Propagation::Context, nil] extracted context
+      def extract(headers)
+        Propagation.extract(headers)
+      end
+
+      # Distributed tracing: extract and set as current context
+      # @param headers [Hash] incoming headers
+      # @return [Propagation::Context, nil] extracted context
+      def extract!(headers)
+        Propagation.extract!(headers)
+      end
+
+      # Get current propagation context
+      def propagation_context
+        Propagation.current
+      end
+
+      # Create a child propagation context for a new span
+      def child_context
+        Propagation.child_context
+      end
+
+      private
+
+      def create_propagation_context
+        trace = tracer.current_trace
+        if trace
+          Propagation::Context.new(
+            trace_id: trace[:trace_id],
+            span_id: SecureRandom.hex(8)
+          )
+        else
+          Propagation::Context.new
+        end
+      end
+
+      def enabled?
+        BrainzLab.configuration.pulse_enabled
+      end
+
+      def build_trace_payload(name, kind, started_at, ended_at, attributes)
+        config = BrainzLab.configuration
+        ctx = Context.current
+
+        duration_ms = ((ended_at - started_at) * 1000).round(2)
+
+        {
+          trace_id: attributes[:trace_id] || SecureRandom.uuid,
+          name: name,
+          kind: kind,
+          started_at: started_at.utc.iso8601(3),
+          ended_at: ended_at.utc.iso8601(3),
+          duration_ms: duration_ms,
+
+          # Distributed tracing - parent trace info
+          parent_trace_id: attributes[:parent_trace_id],
+          parent_span_id: attributes[:parent_span_id],
+
+          # Environment
+          environment: config.environment,
+          commit: config.commit,
+          host: config.host,
+
+          # Request context
+          request_id: ctx.request_id || attributes[:request_id],
+          request_method: attributes[:request_method],
+          request_path: attributes[:request_path],
+          controller: attributes[:controller],
+          action: attributes[:action],
+          status: attributes[:status],
+
+          # Timing breakdown
+          view_ms: attributes[:view_ms],
+          db_ms: attributes[:db_ms],
+          external_ms: attributes[:external_ms],
+          cache_ms: attributes[:cache_ms],
+
+          # Job context
+          job_class: attributes[:job_class],
+          job_id: attributes[:job_id],
+          queue: attributes[:queue],
+          queue_wait_ms: attributes[:queue_wait_ms],
+          executions: attributes[:executions],
+
+          # User
+          user_id: ctx.user&.dig(:id)&.to_s || attributes[:user_id],
+
+          # Error info
+          error: attributes[:error] || false,
+          error_class: attributes[:error_class],
+          error_message: attributes[:error_message],
+
+          # Spans
+          spans: attributes[:spans] || []
+        }.compact
+      end
+    end
+  end
+end