fluyenta-ruby 0.1.14

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.positive?
+        # Only skip if pulse_api_key is already set
+        return false if @config.pulse_api_key.to_s.strip.length.positive?
+        return false unless @config.pulse_master_key.to_s.strip.length.positive?
+
+        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 = BrainzLab::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,294 @@
+# 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, &)
+      end
+
+      # Record a complete trace (for when you have all data upfront)
+      def record_trace(name, started_at:, ended_at:, kind: 'request', **attributes)
+        return unless enabled?
+
+        payload = build_trace_payload(name, kind, started_at, ended_at, attributes)
+
+        # In development mode, log locally instead of sending to server
+        if BrainzLab.configuration.development_mode?
+          Development.record(service: :pulse, event_type: 'trace', payload: payload)
+          return
+        end
+
+        ensure_provisioned!
+        return unless BrainzLab.configuration.pulse_valid?
+
+        client.send_trace(payload)
+      end
+
+      # Record a custom metric
+      def record_metric(name, value:, kind: 'gauge', tags: {})
+        return unless enabled?
+
+        payload = {
+          name: name,
+          value: value,
+          kind: kind,
+          timestamp: Time.now.utc.iso8601(3),
+          tags: tags
+        }
+
+        # In development mode, log locally instead of sending to server
+        if BrainzLab.configuration.development_mode?
+          Development.record(service: :pulse, event_type: 'metric', payload: payload)
+          return
+        end
+
+        ensure_provisioned!
+        return unless BrainzLab.configuration.pulse_valid?
+
+        if BrainzLab.instrumenting?
+          # During instrumentation, send in background thread to avoid
+          # blocking the host app with synchronous HTTP
+          Thread.new { client.send_metric(payload) }
+        else
+          client.send_metric(payload)
+        end
+      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
+
+      # Record a standalone span (used by brainzlab-rails for Rails instrumentation)
+      # @param name [String] span name (e.g., "sql.SELECT", "cache.read")
+      # @param duration_ms [Float] span duration in milliseconds
+      # @param category [String] span category (e.g., "db.sql", "cache.read", "http.request")
+      # @param attributes [Hash] additional span attributes
+      # @param timestamp [String] ISO8601 timestamp
+      def record_span(name:, duration_ms:, category:, attributes: {}, timestamp: nil)
+        return unless enabled?
+
+        ensure_provisioned!
+        return unless BrainzLab.configuration.pulse_valid?
+
+        # Parse timestamp or use current time
+        started_at = if timestamp
+                       Time.parse(timestamp) rescue Time.now.utc
+                     else
+                       Time.now.utc
+                     end
+
+        span_data = {
+          span_id: SecureRandom.uuid,
+          name: name,
+          kind: category,
+          started_at: started_at,
+          ended_at: started_at, # Same as started_at since we only have duration
+          duration_ms: duration_ms,
+          error: false,
+          data: attributes
+        }
+
+        # If there's an active trace, add the span to it (will be sent with finish_trace)
+        # Otherwise, send it directly to the API as a standalone span
+        if tracer.current_trace
+          tracer.current_spans << span_data
+        else
+          # Send as standalone span (backward compatibility)
+          api_span_data = {
+            name: name,
+            category: category,
+            duration_ms: duration_ms,
+            timestamp: timestamp || Time.now.utc.iso8601(3),
+            attributes: attributes,
+            environment: BrainzLab.configuration.environment,
+            service: BrainzLab.configuration.service,
+            host: BrainzLab.configuration.host,
+            request_id: Context.current.request_id
+          }.compact
+          client.send_span(api_span_data)
+        end
+      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_effectively_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