agentbill-sdk 5.0.1 → 9.4.0

data/lib/agentbill/signals.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'net/http'
+require 'digest'
+require 'json'
+require 'uri'
+require 'time'
+
+require_relative 'distributed'
+
+module AgentBill
+  # Signal module for tracking business events and linking revenue to AI traces.
+  module Signals
+    BASE_URL = 'https://api.agentbill.io'
+    VERSION = '9.4.0'
+
+    @config = {}
+
+    class << self
+      attr_accessor :config
+
+      def set_config(options)
+        @config = options
+      end
+
+      def get_config
+        @config
+      end
+    end
+  end
+
+  class << self
+    # Emit a business signal/event and link it to AI traces.
+    #
+    # @param event_name [String] Name of the business event
+    # @param options [Hash] Signal options
+    # @option options [Float] :revenue Revenue amount
+    # @option options [Hash] :metadata Additional metadata
+    # @option options [String] :customer_id Customer ID
+    # @option options [String] :session_id Session ID
+    # @option options [String] :trace_id Trace ID to link to
+    # @option options [String] :span_id Span ID to link to
+    # @option options [String] :parent_span_id Parent span ID
+    # @option options [String] :currency Currency (default: USD)
+    # @option options [String] :event_type Event type
+    # @option options [Float] :event_value Event value
+    # @option options [String] :order_id Order ID to link to (v7.8.0)
+    # @option options [String] :order_external_id External order ID (v7.8.0)
+    # @option options [Hash] :group_by Business grouping keys (v9.2.0) — session_id, workflow_id, batch_id, correlation_id
+    # @option options [String] :idempotency_key Dedup key (v9.2.0) — auto-generated if not provided
+    # @option options [Hash] :cost_data Manual cost/usage data (v9.2.0 Phase 3)
+    #
+    # @return [Hash] Result with success status
+    #
+    # @example
+    #   AgentBill.signal('purchase', revenue: 99.99, metadata: { product_id: 'prod-123' })
+    def signal(event_name, **options)
+      config = Signals.get_config
+
+      api_key = config[:api_key]
+      raise ArgumentError, 'AgentBill not initialized. Call AgentBill.init() first or use AgentBill.tracing context.' unless api_key
+
+      effective_customer_id = options[:customer_id] || config[:customer_id]
+
+      # Auto-detect trace context if not provided
+      ctx = Distributed.get_trace_context
+      trace_id = options[:trace_id]
+      parent_span_id = options[:parent_span_id]
+
+      if ctx
+        trace_id ||= ctx[:trace_id]
+        parent_span_id ||= ctx[:span_id] unless parent_span_id
+      end
+
+      generated_span_id = options[:span_id] || SecureRandom.hex(8)
+      generated_trace_id = trace_id || SecureRandom.hex(16)
+      now_ns = (Time.now.to_f * 1_000_000_000).to_i
+      timestamp_s = Time.now.to_i
+
+      # Auto-generate idempotency key
+      idempotency_key = options[:idempotency_key] || Digest::SHA256.hexdigest("#{generated_trace_id}:#{event_name}:#{timestamp_s}")[0, 32]
+
+      # Build OTEL-compliant span attributes
+      attributes = [
+        { key: 'agentbill.event_name', value: { stringValue: event_name } },
+        { key: 'agentbill.is_business_event', value: { boolValue: true } }
+      ]
+
+      attributes << { key: 'agentbill.customer_id', value: { stringValue: effective_customer_id } } if effective_customer_id
+      attributes << { key: 'agentbill.agent_id', value: { stringValue: config[:agent_id] } } if config[:agent_id]
+
+      if options[:revenue]
+        attributes << { key: 'agentbill.revenue', value: { doubleValue: options[:revenue] } }
+        attributes << { key: 'agentbill.currency', value: { stringValue: options[:currency] || 'USD' } }
+      end
+
+      attributes << { key: 'agentbill.event_value', value: { doubleValue: options[:event_value] } } if options[:event_value]
+      attributes << { key: 'agentbill.event_type', value: { stringValue: options[:event_type] } } if options[:event_type]
+      attributes << { key: 'agentbill.session_id', value: { stringValue: options[:session_id] } } if options[:session_id]
+      attributes << { key: 'agentbill.parent_span_id', value: { stringValue: parent_span_id } } if parent_span_id
+      # v7.8.0: Order linking
+      attributes << { key: 'agentbill.order_id', value: { stringValue: options[:order_id] } } if options[:order_id]
+      attributes << { key: 'agentbill.order_external_id', value: { stringValue: options[:order_external_id] } } if options[:order_external_id]
+      attributes << { key: 'agentbill.metadata', value: { stringValue: JSON.generate(options[:metadata]) } } if options[:metadata]
+
+      # v9.2.0: Idempotency key
+      attributes << { key: 'agentbill.idempotency_key', value: { stringValue: idempotency_key } }
+
+      # v9.2.0: Business grouping (whitelisted keys only)
+      grouping_keys = %w[session_id workflow_id batch_id correlation_id].freeze
+      if options[:group_by].is_a?(Hash)
+        options[:group_by].each do |key, value|
+          attributes << { key: "agentbill.#{key}", value: { stringValue: value.to_s } } if grouping_keys.include?(key.to_s)
+        end
+      end
+
+      # v9.4.0: enable_cost_tracing flag
+      if config[:enable_cost_tracing]
+        attributes << { key: 'agentbill.cost_tracing.enabled', value: { boolValue: true } }
+      end
+
+      # v9.2.0: Manual cost (Phase 3 – two-variant model)
+      if options[:cost_data].is_a?(Hash)
+        cd = options[:cost_data]
+        attributes << { key: 'agentbill.cost.provider', value: { stringValue: cd[:vendor] } } if cd[:vendor]
+        if cd[:cost].is_a?(Hash)
+          attributes << { key: 'agentbill.cost.provided', value: { boolValue: true } }
+          attributes << { key: 'agentbill.cost.amount', value: { doubleValue: cd[:cost][:amount] } }
+          attributes << { key: 'agentbill.cost.currency', value: { stringValue: cd[:cost][:currency] || 'USD' } }
+        end
+        if cd[:attributes].is_a?(Hash)
+          attributes << { key: 'gen_ai.request.model', value: { stringValue: cd[:attributes][:model] } } if cd[:attributes][:model]
+          attributes << { key: 'gen_ai.usage.prompt_tokens', value: { intValue: cd[:attributes][:input_tokens] } } if cd[:attributes][:input_tokens]
+          attributes << { key: 'gen_ai.usage.completion_tokens', value: { intValue: cd[:attributes][:output_tokens] } } if cd[:attributes][:output_tokens]
+        end
+      end
+      # Build OTEL payload
+      payload = {
+        resourceSpans: [{
+          resource: {
+            attributes: [
+              { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
+              { key: 'agentbill.customer_id', value: { stringValue: effective_customer_id || '' } },
+              { key: 'agentbill.agent_id', value: { stringValue: config[:agent_id] || '' } }
+            ]
+          },
+          scopeSpans: [{
+            scope: { name: 'agentbill.signals', version: Signals::VERSION },
+            spans: [{
+              traceId: generated_trace_id,
+              spanId: generated_span_id,
+              parentSpanId: parent_span_id || '',
+              name: 'agentbill.trace.signal',
+              kind: 1,
+              startTimeUnixNano: now_ns.to_s,
+              endTimeUnixNano: now_ns.to_s,
+              attributes: attributes,
+              status: { code: 1 }
+            }]
+          }]
+        }]
+      }
+
+      base_url = config[:base_url] || Signals::BASE_URL
+      debug = config[:debug] || false
+
+      begin
+        url = URI("#{base_url}/functions/v1/otel-collector")
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = true
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(url)
+        request['x-api-key'] = api_key
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+
+        response_data = {}
+        body_success = true
+        begin
+          response_data = JSON.parse(response.body)
+          body_success = response_data['success'] != false
+        rescue StandardError
+          # If can't parse JSON, fall back to HTTP status check
+        end
+
+        is_success = response.code.to_i == 200 && body_success
+
+        if debug
+          if is_success
+            puts "[AgentBill] ✓ Signal '#{event_name}' tracked via OTEL"
+            puts "[AgentBill]   Revenue: $#{'%.2f' % options[:revenue]} #{options[:currency] || 'USD'}" if options[:revenue]
+            puts "[AgentBill]   Trace ID: #{generated_trace_id}"
+          else
+            puts "[AgentBill] ⚠️ Signal tracking failed: #{response_data['error'] || response.message}"
+            response_data['errors']&.each { |err| puts "[AgentBill]   - #{err}" }
+          end
+        end
+
+        {
+          success: is_success,
+          status_code: response.code.to_i,
+          trace_id: generated_trace_id,
+          span_id: generated_span_id,
+          error: is_success ? nil : response_data['error'],
+          errors: is_success ? nil : response_data['errors']
+        }
+      rescue StandardError => e
+        puts "[AgentBill] ⚠️ Signal tracking error: #{e.message}" if debug
+        {
+          success: false,
+          error: e.message,
+          trace_id: generated_trace_id
+        }
+      end
+    end
+
+    # Track a conversion event for revenue attribution.
+    #
+    # @param event_type [String] Type of conversion
+    # @param event_value [Float] Value of the conversion
+    # @param options [Hash] Additional options
+    #
+    # @return [Hash] Result with status
+    def track_conversion(event_type, event_value, **options)
+      signal(
+        "conversion_#{event_type}",
+        revenue: event_value,
+        event_type: event_type,
+        event_value: event_value,
+        **options
+      )
+    end
+
+    # Create a signal explicitly linked to an AI trace for cost attribution.
+    #
+    # This is the recommended way to link business events to AI costs.
+    # Requires trace_id from the AI call you want to attribute costs to.
+    # Sets enable_cost_tracing=true automatically.
+    #
+    # v9.4.0: Added as part of P2 Architecture Alignment (Python parity).
+    #
+    # @param event_name [String] Name of the business event
+    # @param trace_id [String] Trace ID from the AI call
+    # @param revenue [Float] Revenue amount
+    # @param options [Hash] Additional signal options
+    # @return [Hash] Result with status
+    #
+    # @example
+    #   AgentBill.cost_attributed_signal('purchase', 'abc123', 99.99, metadata: { product_id: 'prod-123' })
+    def cost_attributed_signal(event_name, trace_id:, revenue:, **options)
+      config = Signals.get_config
+      prev_config = config.dup
+      Signals.set_config(config.merge(enable_cost_tracing: true))
+
+      begin
+        signal(
+          event_name,
+          trace_id: trace_id,
+          revenue: revenue,
+          **options
+        )
+      ensure
+        Signals.set_config(prev_config)
+      end
+    end
+  end
+end

data/lib/agentbill/tracer.rb

@@ -1,15 +1,17 @@
 require 'net/http'
 require 'json'
 require 'securerandom'
+require_relative 'distributed'
 
 module AgentBill
   class Span
-    attr_accessor :name, :trace_id, :span_id, :attributes, :start_time, :end_time, :status
+    attr_accessor :name, :trace_id, :span_id, :parent_span_id, :attributes, :start_time, :end_time, :status
 
-    def initialize(name, trace_id, span_id, attributes)
+    def initialize(name, trace_id, span_id, parent_span_id, attributes)
       @name = name
       @trace_id = trace_id
       @span_id = span_id
+      @parent_span_id = parent_span_id
       @attributes = attributes
       @start_time = (Time.now.to_f * 1_000_000_000).to_i
       @end_time = nil
@@ -30,9 +32,21 @@ module AgentBill
   end
 
   class Tracer
+    # OpenTelemetry tracer for AgentBill
+    #
+    # IMPORTANT: This tracer integrates with Distributed module for trace context.
+    # - If a trace context exists (via Distributed.get_trace_context), it reuses the trace_id
+    # - Always generates a new span_id for each span
+    # - Updates the global trace context so get_trace_context returns correct values
+    #
+    # This ensures that:
+    # 1. get_trace_context always returns the trace_id that matches what's sent to the portal
+    # 2. Distributed tracing works correctly across services
+    # 3. Parent-child span relationships are properly maintained
+
     def initialize(config)
       @config = config
-      @base_url = config[:base_url] || 'https://uenhjwdtnxtchlmqarjo.supabase.co'
+      @base_url = config[:base_url] || 'https://api.agentbill.io'
       @api_key = config[:api_key]
       @customer_id = config[:customer_id]
       @debug = config[:debug] || false
@@ -40,14 +54,37 @@ module AgentBill
     end
 
     def start_span(name, attributes)
-      trace_id = SecureRandom.hex(16)
+      # Check for existing trace context from Distributed module
+      ctx = Distributed.get_trace_context
+      parent_span_id = nil
+
+      if ctx
+        # Reuse existing trace_id for correlation
+        trace_id = ctx[:trace_id]
+        parent_span_id = ctx[:span_id]
+        puts "[AgentBill Tracer] Using existing trace context: trace_id=#{trace_id[0..7]}..." if @debug
+      else
+        # Generate new trace_id for new trace
+        trace_id = SecureRandom.hex(16)
+        puts "[AgentBill Tracer] Creating new trace: trace_id=#{trace_id[0..7]}..." if @debug
+      end
+
+      # Always generate new span_id for this span
       span_id = SecureRandom.hex(8)
 
+      # Update global trace context so get_trace_context returns correct values
+      Distributed.set_trace_context(trace_id, span_id)
+
       attributes['service.name'] = 'agentbill-ruby-sdk'
       attributes['customer.id'] = @customer_id if @customer_id
 
-      span = Span.new(name, trace_id, span_id, attributes)
+      span = Span.new(name, trace_id, span_id, parent_span_id, attributes)
       @spans << span
+
+      if @debug
+        puts "[AgentBill Tracer] Started span: #{name}, trace_id=#{trace_id[0..7]}..., span_id=#{span_id[0..7]}..."
+      end
+
       span
     end
 
@@ -77,16 +114,31 @@ module AgentBill
     private
 
     def build_otlp_payload
+      # Build resource attributes - agent_id and customer_id must be sent here
+      # for the otel-collector to extract them correctly
+      resource_attrs = [
+        { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
+        { key: 'service.version', value: { stringValue: '6.8.8' } }
+      ]
+      
+      # Add customer_id as resource attribute if configured
+      if @customer_id
+        resource_attrs << { key: 'customer.id', value: { stringValue: @customer_id } }
+      end
+      
+      # Add agent_id as resource attribute if configured
+      agent_id = @config[:agent_id]
+      if agent_id
+        resource_attrs << { key: 'agent.id', value: { stringValue: agent_id } }
+      end
+      
       {
         resourceSpans: [{
           resource: {
-            attributes: [
-              { key: 'service.name', value: { stringValue: 'agentbill-ruby-sdk' } },
-              { key: 'service.version', value: { stringValue: '1.0.0' } }
-            ]
+            attributes: resource_attrs
           },
           scopeSpans: [{
-            scope: { name: 'agentbill', version: '1.0.0' },
+            scope: { name: 'agentbill', version: '6.8.8' },
             spans: @spans.map { |span| span_to_otlp(span) }
           }]
         }]
@@ -94,7 +146,7 @@ module AgentBill
     end
 
     def span_to_otlp(span)
-      {
+      otlp_span = {
         traceId: span.trace_id,
         spanId: span.span_id,
         name: span.name,
@@ -104,6 +156,11 @@ module AgentBill
         attributes: span.attributes.map { |k, v| { key: k, value: value_to_otlp(v) } },
         status: span.status
       }
+
+      # Add parent span ID if this is a child span
+      otlp_span[:parentSpanId] = span.parent_span_id if span.parent_span_id
+
+      otlp_span
     end
 
     def value_to_otlp(value)