bitfab 0.23.7 → 0.23.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb51dda5edc6e1c4cf5cc439c766b52dad303f3838e5aae80b03cd521fa34d80
-  data.tar.gz: a1b21474b8d32f22ed6a17e2ef65d865549fb23d7a25de9cbdfd03e64eb385a5
+  metadata.gz: 342b5de3b40edd60f060465123f21d1c5338063340b34ac7bb7067c7baedfe55
+  data.tar.gz: 2f73bec442f3570efe78253d28733942e00b46c03a26ce2731a72e778cd6d79f
 SHA512:
-  metadata.gz: 9dfb2cb3e7eb9f845453f58e807c6150e8136c43fdc5e3aedfb65d89b61027772831775f0a7854559a89be4ddeae7084b6c26195ac165365083309429834057c
-  data.tar.gz: '0785322f709aa5dbe67454f7ca743e5def622d9ed6981d4f62b5c222e1e730270bfc727805f7198a4a139d54ea966dc80df194107f1e90b575638f90e7f7a02e'
+  metadata.gz: c76023257bcdd959cb49d6881faf05e85013b2d30c02826fd57a2a2aa8a72d72d7f8f10716f9f4b2d850a84dfb4a6ef7151077b88f43e2e1e7bd5b4c81ed23ff
+  data.tar.gz: 37fb2e1215527c780253dd35e10e4ff01d735336d068d5d8ac16a75d4fcc17e1749f7718cf8ffc550e965a27a9f0ee8fb49b2b847724c10a1ae031f0f1470574

data/lib/bitfab/client.rb

@@ -13,6 +13,7 @@ require_relative "warn_once"
 module Bitfab
   class Client
     SPAN_TYPES = %w[llm agent function guardrail handoff custom].freeze
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
 
     # Sentinel returned by check_mock_replay when this span should run real
     # code (no mock active, wrong strategy, or no matching historical entry).
@@ -115,6 +116,26 @@ module Bitfab
       BitfabFunction.new(self, trace_function_key)
     end
 
+    # Fetch one persisted span without loading the full trace.
+    # Exactly one of id or name is required. Name lookups return the last
+    # matching span by default; occurrence also accepts "first" or a zero-based
+    # Integer index.
+    def get_trace_span(trace_id, id: nil, name: nil, occurrence: "last")
+      validate_trace_id(trace_id)
+      raise ArgumentError, "Provide exactly one of id or name" if id.nil? == name.nil?
+      validate_span_id(id) unless id.nil?
+      if !name.nil? && (!name.is_a?(String) || name.empty?)
+        raise ArgumentError, "name must be a non-empty string"
+      end
+
+      valid_occurrence = %w[first last].include?(occurrence) || (occurrence.is_a?(Integer) && occurrence >= 0)
+      unless valid_occurrence
+        raise ArgumentError, 'occurrence must be "first", "last", or a non-negative integer'
+      end
+
+      @http_client.get_trace_span(trace_id, id:, name:, occurrence:)
+    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:,
@@ -343,6 +364,14 @@ module Bitfab
 
     private
 
+    def validate_trace_id(trace_id)
+      raise ArgumentError, "trace_id must be a valid Bitfab trace ID" unless trace_id.is_a?(String) && UUID_PATTERN.match?(trace_id)
+    end
+
+    def validate_span_id(id)
+      raise ArgumentError, "id must be a valid Bitfab span ID" unless id.is_a?(String) && UUID_PATTERN.match?(id)
+    end
+
     # Resolve the API key lazily, the first time a span actually needs it.
     #
     # The key is intentionally NOT read at construction: a client built when a
@@ -462,6 +491,7 @@ module Bitfab
       end
 
       payload = {
+        "id" => trace_id,
         "type" => "sdk-function",
         "source" => "ruby-sdk-function",
         "traceFunctionKey" => trace_function_key,
@@ -540,6 +570,8 @@ module Bitfab
       raw_span["input_source_span_id"] = input_source_span_id if input_source_span_id
 
       payload = {
+        "id" => span_id,
+        "traceId" => trace_id,
         "type" => "sdk-function",
         "source" => "ruby-sdk-function",
         "sourceTraceId" => trace_id,

data/lib/bitfab/http_client.rb

@@ -80,7 +80,7 @@ module Bitfab
       http.open_timeout = request_timeout
       http.read_timeout = request_timeout
 
-      req = Net::HTTP::Get.new(uri.path, headers)
+      req = Net::HTTP::Get.new(uri.request_uri, headers)
       response = http.request(req)
 
       unless response.is_a?(Net::HTTPSuccess)
@@ -140,6 +140,19 @@ module Bitfab
       get("/api/sdk/externalSpans/#{span_id}", timeout: 30)
     end
 
+    def get_trace_span(trace_id, id: nil, name: nil, occurrence: "last")
+      query = if id
+        {id:}
+      else
+        {name:, occurrence: occurrence.to_s}
+      end
+      encoded_trace_id = URI.encode_www_form_component(trace_id)
+      get(
+        "/api/sdk/traces/#{encoded_trace_id}/span?#{URI.encode_www_form(query)}",
+        timeout: 30
+      )["span"]
+    end
+
     # Fetch the span tree rooted at an external span. Blocking GET request.
     # Used by replay when a mock strategy is active so child spans can be
     # matched against their historical outputs.

data/lib/bitfab/span_context.rb

@@ -7,6 +7,11 @@ module Bitfab
       @span_state = span_state
     end
 
+    # The Bitfab ID for the current span.
+    def id
+      @span_state[:span_id]
+    end
+
     # The trace ID for the current span.
     def trace_id
       @span_state[:trace_id]

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.23.7"
+  VERSION = "0.23.8"
 end

data/lib/bitfab.rb

@@ -18,6 +18,10 @@ module Bitfab
   # No-op span handle returned when outside a span context.
   # All methods do nothing, preventing crashes when called outside traced code.
   class NoOpCurrentSpan
+    def id
+      ""
+    end
+
     def trace_id
       ""
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.23.7
+  version: 0.23.8
 platform: ruby
 authors:
 - Harvest Team