bitfab 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78b34044dcc028414fb2f6fbe020f98bf0ce1a953507c8939bc12d8c15630b09
+  data.tar.gz: 174aa2eb61c2aca0a11078f2361b4392d7612f2a582e3dd4046608cbbb539a27
+SHA512:
+  metadata.gz: d2eeec89057ecdee5f7f5eae5342ad9218aa190fc472aa01d3dbf0323262b33165faed2d61d6ae0be9bf7da3af9a7e88902e0fa426344b53751b78d0c1f5cf18
+  data.tar.gz: 9726da71f354723007ff6b9bf38466544e93a1ae21f0b02e2b258827697d4996caea781d1c062c7386dd5508eddad097fbc85f4382798e07cd11a0535a6e1a7a

data/README.md

@@ -0,0 +1,342 @@
+# Bitfab Ruby SDK
+
+Ruby client library for [Bitfab](https://bitfab.ai) - trace and monitor your Ruby application's function execution with nested span support.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'bitfab'
+```
+
+Or install directly:
+
+```bash
+gem install bitfab
+```
+
+## Requirements
+
+- Ruby >= 3.4
+- No external runtime dependencies (uses stdlib only)
+
+## Quick Start
+
+```ruby
+require 'bitfab'
+
+# Configure once at application startup
+Bitfab.configure(
+  api_key: ENV.fetch('BITFAB_API_KEY')
+)
+
+# Add tracing to your classes
+class OrderService
+  include Bitfab::Traceable
+  bitfab_function "order-processing"
+
+  bitfab_span :process_order, type: "function"
+  def process_order(order_id)
+    # Your code here
+    { status: "completed" }
+  end
+end
+
+# Use your code normally - spans are sent automatically
+service = OrderService.new
+service.process_order("order-123")
+
+# Flush traces before exit (automatic via at_exit hook)
+Bitfab.flush_traces
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+Bitfab.configure(
+  api_key: "your-api-key"
+)
+```
+
+### Custom Service URL
+
+```ruby
+Bitfab.configure(
+  api_key: "your-api-key",
+  service_url: "https://custom.example.com"
+)
+```
+
+### Disabling Span Sending
+
+The `enabled` option controls whether spans are sent to Bitfab. When disabled, your code executes normally but no spans are created or sent.
+
+```ruby
+# Disable tracing (useful for development/test environments)
+Bitfab.configure(
+  api_key: ENV.fetch('BITFAB_API_KEY', 'dummy-key'),
+  enabled: false
+)
+```
+
+**Common patterns:**
+
+```ruby
+# Rails: Enable only in production
+Bitfab.configure(
+  api_key: ENV.fetch('BITFAB_API_KEY', 'dummy-key'),
+  enabled: Rails.env.production?
+)
+
+# Environment variable control
+Bitfab.configure(
+  api_key: ENV.fetch('BITFAB_API_KEY', 'dummy-key'),
+  enabled: ENV.fetch('BITFAB_ENABLED', 'false') == 'true'
+)
+
+# Multi-environment control
+Bitfab.configure(
+  api_key: ENV.fetch('BITFAB_API_KEY', 'dummy-key'),
+  enabled: ['production', 'staging'].include?(ENV['RACK_ENV'])
+)
+```
+
+When `enabled: false`:
+- ✅ Code executes normally with no performance impact
+- ✅ Return values and errors work as expected
+- ✅ Nested spans are properly skipped
+- ❌ No HTTP requests are made
+- ❌ No span data is collected or sent
+
+## Usage
+
+### Class-Level Trace Function Key
+
+All spans in the class share the same trace function key:
+
+```ruby
+class PaymentService
+  include Bitfab::Traceable
+  bitfab_function "payment-processing"
+
+  bitfab_span :charge_card, type: "function"
+  def charge_card(amount)
+    # Traced automatically
+  end
+
+  bitfab_span :refund, type: "function"
+  def refund(transaction_id)
+    # Also uses "payment-processing" key
+  end
+end
+```
+
+### Per-Span Trace Function Key
+
+Each span can declare its own key:
+
+```ruby
+class NotificationService
+  include Bitfab::Traceable
+
+  bitfab_span :send_email, trace_function_key: "email-notifications", type: "function"
+  def send_email(to, subject)
+    # Uses "email-notifications" key
+  end
+
+  bitfab_span :send_sms, trace_function_key: "sms-notifications", type: "function"
+  def send_sms(to, message)
+    # Uses "sms-notifications" key
+  end
+end
+```
+
+### Span Types
+
+Bitfab supports the following span types:
+
+- `"llm"` - LLM API calls
+- `"agent"` - Agent decision loops
+- `"function"` - Business logic functions
+- `"guardrail"` - Validation and safety checks
+- `"handoff"` - Human-in-the-loop interactions
+- `"custom"` - Custom span types (default)
+
+```ruby
+bitfab_span :validate_input, type: "guardrail"
+bitfab_span :call_openai, type: "llm"
+bitfab_span :agent_loop, type: "agent"
+```
+
+### Custom Span Names
+
+By default, the method name is used as the span name. Override it:
+
+```ruby
+bitfab_span :process_order, name: "ProcessOrderV2", type: "function"
+def process_order(order_id)
+  # Span will be named "ProcessOrderV2"
+end
+```
+
+### Nested Spans
+
+Spans automatically track parent-child relationships:
+
+```ruby
+class OrderPipeline
+  include Bitfab::Traceable
+  bitfab_function "order-pipeline"
+
+  bitfab_span :process, type: "function"
+  def process(order_id)
+    validate(order_id)
+    # More processing
+  end
+
+  bitfab_span :validate, type: "guardrail"
+  def validate(order_id)
+    check_fraud(order_id)
+    # More validation
+  end
+
+  bitfab_span :check_fraud, type: "guardrail"
+  def check_fraud(order_id)
+    # Fraud checking logic
+  end
+end
+
+# Creates 3 nested spans:
+# process (parent)
+#   └─ validate (child)
+#       └─ check_fraud (grandchild)
+```
+
+### Input/Output Capture
+
+Positional and keyword arguments are automatically captured:
+
+```ruby
+bitfab_span :process_order, type: "function"
+def process_order(order_id, priority: :normal)
+  # Input captured: { "order_id" => "123", "priority" => "normal" }
+  { status: "completed" }
+  # Output captured: { "status" => "completed" }
+end
+```
+
+### Metadata
+
+Add custom metadata to spans:
+
+```ruby
+# Definition-time metadata
+bitfab_span :process_order,
+  type: "function",
+  metadata: { "region" => "us-east", "version" => "v2" }
+def process_order(order_id)
+  # ...
+end
+
+# Runtime metadata (inside a span)
+bitfab_span :process_order, type: "function"
+def process_order(order_id)
+  Bitfab.current_span.add_metadata(
+    "user_id" => current_user.id,
+    "request_id" => request.id
+  )
+  # Runtime metadata merges with definition-time metadata
+end
+```
+
+### Wrapping External Code
+
+Wrap third-party library methods without modifying them:
+
+```ruby
+class ExternalHttpClient
+  def get(url)
+    # Third-party code
+  end
+end
+
+# Add tracing via wrap
+Bitfab::Traceable.wrap(
+  ExternalHttpClient,
+  :get,
+  trace_function_key: "http-client",
+  type: "function"
+)
+
+# Now traced automatically
+client = ExternalHttpClient.new
+client.get("https://api.example.com")
+```
+
+### Error Handling
+
+Errors are automatically captured and re-raised:
+
+```ruby
+bitfab_span :risky_operation, type: "function"
+def risky_operation
+  raise StandardError, "Something went wrong"
+end
+
+begin
+  service.risky_operation
+rescue StandardError => e
+  # Error is captured in span and re-raised
+  puts "Caught: #{e.message}"
+end
+```
+
+## Lifecycle
+
+### Automatic Flush
+
+Spans are sent in background threads and automatically flushed on exit via `at_exit` hook.
+
+### Manual Flush
+
+Wait for all pending spans to be sent:
+
+```ruby
+Bitfab.flush_traces
+# Blocks until all background threads complete
+```
+
+### Reset Client
+
+Clear the global client (useful for testing):
+
+```ruby
+Bitfab.reset!
+```
+
+## Thread Safety
+
+- Each thread has its own span context stack (using `Thread.current`)
+- Nested spans only work within the same thread
+- Background span sending is thread-safe
+
+## Examples
+
+See [bitfab-ruby-example/](../bitfab-ruby-example/) for complete working examples:
+
+- [test_span.rb](../bitfab-ruby-example/scripts/test_span.rb) - Basic span creation
+- [test_nested_spans.rb](../bitfab-ruby-example/scripts/test_nested_spans.rb) - Nested span hierarchies
+- [test_wrap.rb](../bitfab-ruby-example/scripts/test_wrap.rb) - Wrapping external code
+- [test_enabled.rb](../bitfab-ruby-example/scripts/test_enabled.rb) - Using the enabled flag
+- [test_metadata.rb](../bitfab-ruby-example/scripts/test_metadata.rb) - Custom metadata
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup, testing, and publishing instructions.
+
+## License
+
+MIT

data/lib/bitfab/client.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+require_relative "constants"
+require_relative "http_client"
+require_relative "replay"
+require_relative "span_context"
+require_relative "serialize"
+
+module Bitfab
+  class Client
+    SPAN_TYPES = %w[llm agent function guardrail handoff custom].freeze
+
+    attr_reader :api_key, :service_url, :enabled
+
+    def initialize(api_key:, service_url: nil, enabled: true)
+      @api_key = api_key
+      @service_url = service_url || DEFAULT_SERVICE_URL
+      @enabled = enabled
+      if @enabled && (@api_key.nil? || @api_key.to_s.strip.empty?)
+        warn "Bitfab: api_key is empty — tracing is disabled. Provide a valid API key to enable tracing."
+        @enabled = false
+      end
+      @http_client = HttpClient.new(api_key:, service_url: @service_url)
+      @pending_span_threads = {}
+      @pending_span_mutex = Mutex.new
+    end
+
+    # Replay historical traces through a method and create a test run.
+    #
+    # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
+    # @param method_name [Symbol] the method to replay
+    # @param trace_function_key [String] the trace function key for this method
+    # @param limit [Integer] maximum number of traces to replay (default: 5)
+    # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
+    # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
+    # @return [Hash] with :items, :test_run_id, :test_run_url
+    def replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10)
+      Replay.run(self, receiver, method_name, trace_function_key:, limit:, trace_ids:, max_concurrency:)
+    end
+
+    # Execute a block inside a span context, sending trace data on completion.
+    # Called by Traceable — not intended for direct use.
+    def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:)
+      return yield unless @enabled
+
+      parent = SpanContext.current
+      trace_id = parent ? parent[:trace_id] : SecureRandom.uuid
+      span_id = SecureRandom.uuid
+      parent_span_id = parent&.dig(:span_id)
+      is_root_span = parent_span_id.nil?
+      started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+
+      # Register trace state for root spans
+      if is_root_span && !TraceState.get(trace_id)
+        TraceState.create(trace_id)
+      end
+
+      if is_root_span
+        @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
+      end
+
+      result = nil
+      error = nil
+      span_contexts = nil
+      span_prompt = nil
+
+      begin
+        SpanContext.with_span(trace_id:, span_id:) do
+          result = yield
+        ensure
+          # Capture contexts before the span context is popped
+          span_contexts = SpanContext.current&.dig(:contexts)
+          span_prompt = SpanContext.current&.dig(:prompt)
+        end
+      rescue => e
+        error = e.message
+        raise
+      ensure
+        # Never crash the host app due to span building/sending
+        begin
+          ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+
+          replay_ctx = ReplayContext.current
+          resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+          resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
+
+          span_thread = send_span(
+            trace_function_key:,
+            trace_id:,
+            span_id:,
+            parent_span_id:,
+            span_name:,
+            span_type:,
+            function_name:,
+            contexts: span_contexts,
+            prompt: span_prompt,
+            args:,
+            kwargs:,
+            result:,
+            error:,
+            started_at:,
+            ended_at:,
+            test_run_id: resolved_test_run_id,
+            input_source_span_id: resolved_input_source_span_id
+          )
+
+          if is_root_span
+            pending = @pending_span_mutex.synchronize { @pending_span_threads.delete(trace_id) || [] }
+            pending << span_thread if span_thread
+            pending.each { |t| t.join(5) }
+
+            send_trace_completion(
+              trace_function_key:,
+              trace_id:,
+              started_at:,
+              ended_at:
+            )
+          else
+            @pending_span_mutex.synchronize do
+              @pending_span_threads[trace_id] << span_thread if span_thread && @pending_span_threads.key?(trace_id)
+            end
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          # Silently ignore — user's result/exception takes priority
+          # Catches Exception (not just StandardError) to handle SystemStackError
+          # from deeply nested serialization
+        end
+      end
+
+      result
+    end
+
+    private
+
+    def validate_span_type!(type)
+      return if SPAN_TYPES.include?(type.to_s)
+
+      raise ArgumentError, "Invalid span type '#{type}'. Must be one of: #{SPAN_TYPES.join(", ")}"
+    end
+
+    def send_trace_completion(trace_function_key:, trace_id:, started_at:, ended_at:)
+      trace_state = TraceState.get(trace_id)
+      trace_started_at = trace_state&.dig(:started_at) || started_at
+
+      raw_trace = {
+        "id" => trace_id,
+        "started_at" => trace_started_at,
+        "ended_at" => ended_at
+      }
+
+      if trace_state&.dig(:metadata)
+        raw_trace["metadata"] = trace_state[:metadata]
+      end
+      if trace_state&.dig(:contexts)
+        raw_trace["contexts"] = trace_state[:contexts]
+      end
+
+      payload = {
+        "type" => "sdk-function",
+        "source" => "ruby-sdk-function",
+        "traceFunctionKey" => trace_function_key,
+        "externalTrace" => raw_trace,
+        "completed" => true
+      }
+
+      if trace_state&.dig(:session_id)
+        payload["sessionId"] = trace_state[:session_id]
+      end
+
+      @http_client.send_external_trace(payload)
+
+      # Clean up trace state
+      TraceState.delete(trace_id)
+    end
+
+    def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
+      span_name:, span_type:, function_name:, contexts:, prompt:, args:, kwargs:, result:, error:,
+      started_at:, ended_at:, test_run_id: nil, input_source_span_id: nil)
+      # Human-readable JSON (input/output fields)
+      human_inputs = Serialize.serialize_inputs(args, kwargs)
+      human_output = Serialize.serialize_value(result)
+
+      # Marshal + Base64 for full Ruby-to-Ruby object reconstruction
+      raw_input = (args.length == 1 && kwargs.empty?) ? args[0] : {args:, kwargs:}
+      marshalled_input = Serialize.marshal_value(raw_input)
+      marshalled_output = Serialize.marshal_value(result)
+
+      span_data = {
+        "name" => span_name,
+        "type" => span_type,
+        "input" => human_inputs,
+        "output" => human_output,
+        "function_name" => function_name
+      }
+      span_data["input_serialized"] = marshalled_input if marshalled_input
+      span_data["output_serialized"] = marshalled_output if marshalled_output
+      span_data["error"] = error if error
+      span_data["contexts"] = contexts if contexts&.any?
+      span_data["prompt"] = prompt if prompt
+
+      raw_span = {
+        "id" => span_id,
+        "trace_id" => trace_id,
+        "started_at" => started_at,
+        "ended_at" => ended_at,
+        "span_data" => span_data
+      }
+      raw_span["parent_id"] = parent_span_id if parent_span_id
+      raw_span["input_source_span_id"] = input_source_span_id if input_source_span_id
+
+      payload = {
+        "type" => "sdk-function",
+        "source" => "ruby-sdk-function",
+        "sourceTraceId" => trace_id,
+        "traceFunctionKey" => trace_function_key,
+        "rawSpan" => raw_span
+      }
+      payload["testRunId"] = test_run_id if test_run_id
+
+      @http_client.send_external_span(payload) # Returns the background thread
+    end
+  end
+end

data/lib/bitfab/constants.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Bitfab
+  DEFAULT_SERVICE_URL = "https://bitfab.ai"
+  REPLAY_CONTEXT_KEY = :__bitfab_replay_context
+end