bloop-sdk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5596c4ce2d5c135c37489bc42e8f5198e08747db4d2f042b4b0d92c4da922505
-  data.tar.gz: 83611d60a780e9b16d67b43199998984a5673174ea08b79d29b20962a29d7859
+  metadata.gz: 1764f66fe2c239ea3e9d45a71ac8f8102a9156d15c3059c166bac8a21e94c1cf
+  data.tar.gz: 69f5b714a508254bf6e63523edbdfb639f0bf771bb983b3ab11015f9f96729b8
 SHA512:
-  metadata.gz: f16a1f358c7fd2406156c4a771b252fa186eb65cedfbf4dc5184aed896f7923805c119c5f317a914d9a0ca45d9b2f1cd1510a478bf08ef54f70132e03db1ebad
-  data.tar.gz: 933331f141544fa8f041e883094624cae9d9dbdbfcde3f1efbeb29d5e3e9056330e33f9bb4c8b31fe5a43dcc20c18b6fd64a4e14c45dc7c063451b0ee4fe4658
+  metadata.gz: 7d94fbd7aa25b6d80b40d6b9caa611af131c82343482d7d2cab19293537a29482863b6bdb2a0c9c6ed4930570d7e599b5e1fe7ac381a544b783af1753b353647
+  data.tar.gz: e3937e140ffd35c5d7522728a29c7850663c65dcdac91084dcc54f074a4883ed73aa3533567d72df2fb6553a6d97ee1b1388f04be5cb3d8a8a99e6a6b1ed5889

data/lib/bloop/tracing.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Bloop
+  class Span
+    attr_reader :id, :parent_span_id, :span_type, :name, :model, :provider,
+                :started_at, :input, :metadata
+    attr_accessor :input_tokens, :output_tokens, :cost, :latency_ms,
+                  :time_to_first_token_ms, :status, :error_message, :output
+
+    def initialize(span_type:, name: "", model: "", provider: "", input: nil,
+                   metadata: nil, parent_span_id: nil)
+      @id = SecureRandom.uuid
+      @parent_span_id = parent_span_id
+      @span_type = span_type.to_s
+      @name = name
+      @model = model
+      @provider = provider
+      @input = input
+      @metadata = metadata
+      @started_at = (Time.now.to_f * 1000).to_i
+    end
+
+    def finish(status: :ok, input_tokens: nil, output_tokens: nil, cost: nil,
+               error_message: nil, output: nil, time_to_first_token_ms: nil)
+      @latency_ms = (Time.now.to_f * 1000).to_i - @started_at
+      @status = status.to_s
+      @input_tokens = input_tokens if input_tokens
+      @output_tokens = output_tokens if output_tokens
+      @cost = cost if cost
+      @error_message = error_message if error_message
+      @output = output if output
+      @time_to_first_token_ms = time_to_first_token_ms if time_to_first_token_ms
+      self
+    end
+
+    def set_usage(input_tokens: nil, output_tokens: nil, cost: nil)
+      @input_tokens = input_tokens if input_tokens
+      @output_tokens = output_tokens if output_tokens
+      @cost = cost if cost
+    end
+
+    def to_h
+      h = {
+        id: @id, span_type: @span_type, name: @name,
+        started_at: @started_at, status: @status || "ok",
+      }
+      h[:parent_span_id] = @parent_span_id if @parent_span_id
+      h[:model] = @model unless @model.empty?
+      h[:provider] = @provider unless @provider.empty?
+      h[:input_tokens] = @input_tokens if @input_tokens
+      h[:output_tokens] = @output_tokens if @output_tokens
+      h[:cost] = @cost if @cost
+      h[:latency_ms] = @latency_ms if @latency_ms
+      h[:time_to_first_token_ms] = @time_to_first_token_ms if @time_to_first_token_ms
+      h[:error_message] = @error_message if @error_message
+      h[:input] = @input if @input
+      h[:output] = @output if @output
+      h[:metadata] = @metadata if @metadata
+      h
+    end
+  end
+
+  class Trace
+    attr_reader :id, :name, :session_id, :user_id, :started_at, :input, :metadata,
+                :prompt_name, :prompt_version, :spans
+    attr_accessor :status, :output, :ended_at
+
+    def initialize(client:, name:, session_id: nil, user_id: nil, input: nil,
+                   metadata: nil, prompt_name: nil, prompt_version: nil)
+      @id = SecureRandom.uuid
+      @client = client
+      @name = name
+      @session_id = session_id
+      @user_id = user_id
+      @status = "running"
+      @input = input
+      @metadata = metadata
+      @prompt_name = prompt_name
+      @prompt_version = prompt_version
+      @started_at = (Time.now.to_f * 1000).to_i
+      @spans = []
+    end
+
+    def start_span(span_type: :custom, name: "", model: "", provider: "",
+                   input: nil, metadata: nil, parent_span_id: nil)
+      span = Span.new(span_type: span_type, name: name, model: model,
+                      provider: provider, input: input, metadata: metadata,
+                      parent_span_id: parent_span_id)
+      @spans << span
+      span
+    end
+
+    def with_generation(model: "", provider: "", name: "", input: nil, metadata: nil)
+      span = start_span(span_type: :generation, name: name, model: model,
+                        provider: provider, input: input, metadata: metadata)
+      yield span
+      span.finish(status: :ok) unless span.status
+      span
+    rescue Exception => e
+      span.finish(status: :error, error_message: e.message) unless span.status
+      raise
+    end
+
+    def finish(status: :completed, output: nil)
+      @ended_at = (Time.now.to_f * 1000).to_i
+      @status = status.to_s
+      @output = output if output
+      @client.send(:enqueue_trace, self)
+    end
+
+    def to_h
+      h = {
+        id: @id, name: @name, status: @status, started_at: @started_at,
+        spans: @spans.map(&:to_h),
+      }
+      h[:session_id] = @session_id if @session_id
+      h[:user_id] = @user_id if @user_id
+      h[:input] = @input if @input
+      h[:output] = @output if @output
+      h[:metadata] = @metadata if @metadata
+      h[:prompt_name] = @prompt_name if @prompt_name
+      h[:prompt_version] = @prompt_version if @prompt_version
+      h[:ended_at] = @ended_at if @ended_at
+      h
+    end
+  end
+end

data/lib/bloop.rb

@@ -4,9 +4,11 @@ require "openssl"
 require "net/http"
 require "json"
 require "uri"
+require "securerandom"
+require_relative "bloop/tracing"
 
 module Bloop
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 
   class Client
     attr_reader :endpoint, :project_key
@@ -26,6 +28,7 @@ module Bloop
       @max_buffer_size = max_buffer_size
 
       @buffer = []
+      @trace_buffer = []
       @mutex = Mutex.new
       @closed = false
 
@@ -78,6 +81,18 @@ module Bloop
       )
     end
 
+    # Wrap a block and capture any raised exception, then re-raise.
+    #
+    # @param kwargs [Hash] Extra context passed to capture_exception (e.g. route_or_procedure:, metadata:)
+    # @yield The block to execute
+    # @return The block's return value
+    def with_error_capture(**kwargs, &block)
+      block.call
+    rescue Exception => e
+      capture_exception(e, **kwargs)
+      raise
+    end
+
     # Flush buffered events immediately.
     def flush
       @mutex.synchronize { flush_locked }
@@ -90,15 +105,49 @@ module Bloop
       @flush_thread&.kill
     end
 
+    # Start a new LLM trace for observability.
+    #
+    # @param name [String] Trace name (e.g. "chat-completion")
+    # @param session_id [String] Optional session identifier
+    # @param user_id [String] Optional user identifier
+    # @param input [Object] Optional input data
+    # @param metadata [Hash] Optional metadata
+    # @param prompt_name [String] Optional prompt template name
+    # @param prompt_version [String] Optional prompt version
+    # @return [Bloop::Trace]
+    def start_trace(name:, session_id: nil, user_id: nil, input: nil, metadata: nil,
+                    prompt_name: nil, prompt_version: nil)
+      Bloop::Trace.new(client: self, name: name, session_id: session_id,
+                       user_id: user_id, input: input, metadata: metadata,
+                       prompt_name: prompt_name, prompt_version: prompt_version)
+    end
+
+    # Wrap a block in a trace. Auto-finishes on success or error.
+    #
+    # @param name [String] Trace name
+    # @param kwargs [Hash] Extra args passed to start_trace
+    # @yield [Bloop::Trace] The trace object
+    # @return [Bloop::Trace]
+    def with_trace(name, **kwargs)
+      trace = start_trace(name: name, **kwargs)
+      yield trace
+      trace.finish(status: :completed) if trace.status == "running"
+      trace
+    rescue Exception => e
+      trace.finish(status: :error, output: e.message) if trace.status == "running"
+      raise
+    end
+
     private
 
     def flush_locked
-      return if @buffer.empty?
-
-      events = @buffer.dup
-      @buffer.clear
+      unless @buffer.empty?
+        events = @buffer.dup
+        @buffer.clear
+        Thread.new { send_events(events) }
+      end
 
-      Thread.new { send_events(events) }
+      flush_traces_locked
     end
 
     def send_events(events)
@@ -129,6 +178,41 @@ module Bloop
       # Fire and forget — don't crash the host app
     end
 
+    def enqueue_trace(trace)
+      @mutex.synchronize do
+        @trace_buffer << trace.to_h
+        flush_traces_locked if @trace_buffer.size >= @max_buffer_size
+      end
+    end
+
+    def flush_traces_locked
+      return if @trace_buffer.empty?
+
+      traces = @trace_buffer.dup
+      @trace_buffer.clear
+      Thread.new { send_traces(traces) }
+    end
+
+    def send_traces(traces)
+      traces.each_slice(50) do |batch|
+        body = JSON.generate({ traces: batch })
+        signature = OpenSSL::HMAC.hexdigest("SHA256", @project_key, body)
+        uri = URI("#{@endpoint}/v1/traces/batch")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 5
+        http.read_timeout = 10
+        req = Net::HTTP::Post.new(uri.path)
+        req["Content-Type"] = "application/json"
+        req["X-Signature"] = signature
+        req["X-Project-Key"] = @project_key
+        req.body = body
+        http.request(req)
+      end
+    rescue StandardError
+      # Fire and forget
+    end
+
     def start_flush_thread
       @flush_thread = Thread.new do
         loop do
@@ -146,4 +230,37 @@ module Bloop
       at_exit { client.close }
     end
   end
+
+  # Rack middleware that captures unhandled exceptions and reports them to bloop.
+  #
+  # Works with Rails, Sinatra, Grape, and any Rack-compatible framework.
+  #
+  # @example Rails
+  #   # config/application.rb
+  #   config.middleware.use Bloop::RackMiddleware, client: Bloop::Client.new(...)
+  #
+  # @example Sinatra
+  #   use Bloop::RackMiddleware, client: Bloop::Client.new(...)
+  class RackMiddleware
+    # @param app [#call] The Rack application
+    # @param client [Bloop::Client] A configured bloop client instance
+    def initialize(app, client:)
+      @app = app
+      @client = client
+    end
+
+    def call(env)
+      @app.call(env)
+    rescue Exception => e
+      @client.capture_exception(e,
+        route_or_procedure: env["PATH_INFO"],
+        metadata: {
+          method: env["REQUEST_METHOD"],
+          query: env["QUERY_STRING"],
+          remote_ip: env["REMOTE_ADDR"],
+        }
+      )
+      raise
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bloop-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - bloop
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-13 00:00:00.000000000 Z
+date: 2026-02-14 00:00:00.000000000 Z
 dependencies: []
 description: Capture and send error events to a bloop server. Zero external dependencies.
 email:
@@ -17,6 +17,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/bloop.rb
+- lib/bloop/tracing.rb
 homepage: https://github.com/your-org/bloop
 licenses:
 - MIT