langfuse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e165c60bb44cb4d93fa3bfcda49f4948078714bc80e50a37fb90501093915b3b
+  data.tar.gz: 5e930ae7b06502dce3c805b4b820cb1de7826b5bfc4d690f82fb1ba1b53e2053
+SHA512:
+  metadata.gz: e0dd66aa77a3389cff7eff1ac9ce9a7be987821179f61cf0f2635136ead05c486100675905971be8f8f4b0d33bf999718a09ee0b0ccb67a90e94426cdb44f0b6
+  data.tar.gz: 02b1a9ae14210d8216fa180b9dda79477502fdb117ef6a023b05e0b1d183b9823d38ff56e107b19edc1b6db3f0a5cb5fe77f96ee78523275cc818488a76fd7fc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Langfuse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -0,0 +1,201 @@
+# Langfuse Ruby SDK
+
+A Ruby client for the [Langfuse](https://langfuse.com) observability platform.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'langfuse'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install langfuse
+```
+
+## Configuration
+
+You need to configure the SDK with your Langfuse credentials:
+
+```ruby
+Langfuse.configure do |config|
+  config.public_key = ENV['LANGFUSE_PUBLIC_KEY']  # e.g., 'pk-lf-...'
+  config.secret_key = ENV['LANGFUSE_SECRET_KEY']  # e.g., 'sk-lf-...'
+  config.host = ENV.fetch('LANGFUSE_HOST', 'https://us.cloud.langfuse.com')
+  config.debug = true # Enable debug logging
+end
+```
+
+### Configuration Options
+
+- `public_key`: Your Langfuse public key (required)
+- `secret_key`: Your Langfuse secret key (required)
+- `host`: Langfuse API host (default: 'https://us.cloud.langfuse.com')
+- `batch_size`: Number of events to buffer before sending (default: 10)
+- `flush_interval`: Seconds between automatic flushes (default: 60)
+- `debug`: Enable debug logging (default: false)
+- `disable_at_exit_hook`: Disable automatic flush on program exit (default: false)
+- `shutdown_timeout`: Seconds to wait for flush thread to finish on shutdown (default: 5)
+
+## Usage
+
+### Creating a Trace
+
+A trace represents a complete user interaction:
+
+```ruby
+trace = Langfuse.trace(
+  name: "user-query",
+  user_id: "user-123",
+  metadata: { source: "web-app" }
+)
+```
+
+### Creating a Span
+
+Spans represent operations within a trace:
+
+```ruby
+span = Langfuse.span(
+  name: "process-query",
+  trace_id: trace.id,
+  input: { query: "What is the weather today?" }
+)
+
+# Later, update and close the span
+span.output = { processed_result: "..." }
+span.end_time = Time.now.utc
+Langfuse.update_span(span)
+```
+
+### Creating a Generation
+
+Generations track LLM invocations:
+
+```ruby
+generation = Langfuse.generation(
+  name: "llm-response",
+  trace_id: trace.id,
+  parent_observation_id: span.id, # Optional: link to parent span
+  model: "gpt-3.5-turbo",
+  model_parameters: {
+    temperature: 0.7,
+    max_tokens: 150
+  },
+  input: [
+    { role: "system", content: "You are a helpful assistant" },
+    { role: "user", content: "What is the weather today?" }
+  ]
+)
+
+# Later, update with the response
+generation.output = "I don't have access to real-time weather data..."
+generation.usage = Langfuse::Models::Usage.new(
+  prompt_tokens: 25,
+  completion_tokens: 35, 
+  total_tokens: 60
+)
+Langfuse.update_generation(generation)
+```
+
+### Creating Events
+
+Events capture point-in-time occurrences:
+
+```ruby
+Langfuse.event(
+  name: "user-feedback",
+  trace_id: trace.id,
+  input: { feedback_type: "thumbs_up" }
+)
+```
+
+### Adding Scores
+
+Scores help evaluate quality:
+
+```ruby
+Langfuse.score(
+  trace_id: trace.id,
+  name: "relevance",
+  value: 0.9,
+  comment: "Response was highly relevant"
+)
+```
+
+### Manual Flushing
+
+Events are automatically sent when:
+- The batch size is reached
+- The flush interval timer triggers
+- The application exits
+
+You can also manually flush events:
+
+```ruby
+Langfuse.flush
+```
+
+## Rails Integration
+
+### Initializer
+
+Create a file at `config/initializers/langfuse.rb`:
+
+```ruby
+require 'langfuse'
+
+Langfuse.configure do |config|
+  config.public_key = ENV['LANGFUSE_PUBLIC_KEY']
+  config.secret_key = ENV['LANGFUSE_SECRET_KEY']
+  config.batch_size = 20
+  config.flush_interval = 30 # seconds
+  config.debug = Rails.env.development?
+end
+```
+
+### ActiveSupport::Notifications Integration
+
+You can integrate with Rails' notification system:
+
+```ruby
+# config/initializers/langfuse.rb
+ActiveSupport::Notifications.subscribe(/langfuse/) do |name, start, finish, id, payload|
+  case name
+  when 'langfuse.trace'
+    Langfuse.trace(payload)
+  when 'langfuse.span'
+    Langfuse.span(payload)
+  # etc.
+  end
+end
+
+# In your application code
+ActiveSupport::Notifications.instrument('langfuse.trace', {
+  name: 'user-login',
+  metadata: { user_id: current_user.id }
+})
+```
+
+## Background Processing with Sidekiq
+
+If Sidekiq is available in your application, the SDK will automatically use it for processing events in the background. This improves performance and reliability.
+
+To enable Sidekiq integration, simply add Sidekiq to your application and it will be detected automatically.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). 

data/bin/console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'langfuse'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# Configure Langfuse
+Langfuse.configure do |config|
+  config.public_key = ENV['LANGFUSE_PUBLIC_KEY'] || 'test_public_key'
+  config.secret_key = ENV['LANGFUSE_SECRET_KEY'] || 'test_secret_key'
+  config.debug = true
+end
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other setup tasks here 

data/lib/langfuse/api_client.rb

@@ -0,0 +1,80 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'base64'
+
+module Langfuse
+  class ApiClient
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def ingest(events)
+      uri = URI.parse("#{@config.host}/api/public/ingestion")
+
+      # Build the request
+      request = Net::HTTP::Post.new(uri.path)
+      request.content_type = 'application/json'
+
+      # Set authorization header using base64 encoded credentials
+      auth = Base64.strict_encode64("#{@config.public_key}:#{@config.secret_key}")
+      # Log the encoded auth header for debugging
+      if @config.debug
+        log("Using auth header: Basic #{auth} (public_key: #{@config.public_key}, secret_key: #{@config.secret_key})")
+      end
+      request['Authorization'] = "Basic #{auth}"
+
+      # Set the payload
+      request.body = {
+        batch: events
+      }.to_json
+
+      # Send the request
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = 10 # 10 seconds
+
+      if @config.debug
+        log("Sending #{events.size} events to Langfuse API at #{@config.host}")
+        log("Events: #{events.inspect}")
+        # log("Using auth header: Basic #{auth.gsub(/.(?=.{4})/, '*')}") # Mask most of the auth token
+        log("Using auth header: Basic #{auth}") # Mask most of the auth token
+        log("Request url: #{uri}")
+      end
+
+      response = http.request(request)
+
+      if response.code.to_i == 207 # Partial success
+        log('Received 207 partial success response') if @config.debug
+        JSON.parse(response.body)
+      elsif response.code.to_i >= 200 && response.code.to_i < 300
+        log("Received successful response: #{response.code}") if @config.debug
+        JSON.parse(response.body)
+      else
+        error_msg = "API error: #{response.code} #{response.message}"
+        if @config.debug
+          log("Response body: #{response.body}", :error)
+          log("Request URL: #{uri}", :error)
+        end
+        log(error_msg, :error)
+        raise error_msg
+      end
+
+      log('---')
+    rescue StandardError => e
+      log("Error during API request: #{e.message}", :error)
+      raise
+    end
+
+    private
+
+    def log(message, level = :debug)
+      return unless @config.debug
+
+      logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      logger.send(level, "[Langfuse] #{message}")
+    end
+  end
+end

data/lib/langfuse/batch_worker.rb

@@ -0,0 +1,80 @@
+module Langfuse
+  class BatchWorker
+    # This is a placeholder class that will be defined with Sidekiq::Worker
+    # when Sidekiq is available.
+    #
+    # If Sidekiq is available, this will be replaced with a real worker class
+    # that includes Sidekiq::Worker
+
+    def self.perform_async(events)
+      # When Sidekiq is not available, process synchronously
+      new.perform(events)
+    end
+
+    def perform(events)
+      Langfuse::ApiClient.new(Langfuse.configuration).ingest(events)
+    end
+  end
+
+  # Define the real Sidekiq worker if Sidekiq is available
+  if defined?(Sidekiq)
+    class BatchWorker
+      include Sidekiq::Worker
+
+      sidekiq_options queue: 'langfuse', retry: 5, backtrace: true
+
+      # Custom retry delay logic (exponential backoff)
+      sidekiq_retry_in do |count|
+        10 * (count + 1) # 10s, 20s, 30s, 40s, 50s
+      end
+
+      def perform(event_hashes)
+        api_client = ApiClient.new(Langfuse.configuration)
+
+        begin
+          response = api_client.ingest(event_hashes)
+
+          # Check for partial failures
+          if response && response['errors']&.any?
+            response['errors'].each do |error|
+              logger.error("Langfuse API error for event #{error['id']}: #{error['message']}")
+
+              # Store permanently failed events if needed
+              if non_retryable_error?(error['status'])
+                store_failed_event(event_hashes.find { |e| e[:id] == error['id'] }, error['message'])
+              end
+            end
+          end
+        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+          # Network errors - Sidekiq will retry
+          logger.error("Langfuse network error: #{e.message}")
+          raise
+        rescue StandardError => e
+          # Other errors
+          logger.error("Langfuse API error: #{e.message}")
+
+          # Let Sidekiq retry
+          raise
+        end
+      end
+
+      private
+
+      def non_retryable_error?(status)
+        # 4xx errors except 429 (rate limit) are not retryable
+        status.to_i >= 400 && status.to_i < 500 && status.to_i != 429
+      end
+
+      def store_failed_event(event, error)
+        # Store in Redis for later inspection/retry
+        Sidekiq.redis do |redis|
+          redis.rpush('langfuse:failed_events', {
+            event: event,
+            error: error,
+            timestamp: Time.now.utc.iso8601
+          }.to_json)
+        end
+      end
+    end
+  end
+end

data/lib/langfuse/client.rb

@@ -0,0 +1,176 @@
+require 'singleton'
+require 'concurrent'
+require 'logger'
+
+module Langfuse
+  class Client
+    include Singleton
+
+    def initialize
+      @config = Langfuse.configuration
+      @events = Concurrent::Array.new # Thread-safe array
+      @mutex = Mutex.new # For operations that need additional thread safety
+
+      # Start periodic flusher only in server context
+      schedule_periodic_flush if defined?(Rails) && Rails.server?
+
+      # Register shutdown hook
+      return if @config.disable_at_exit_hook
+
+      at_exit { shutdown }
+    end
+
+    # Creates a new trace
+    def trace(attributes = {})
+      trace = Models::Trace.new(attributes)
+      event = Models::IngestionEvent.new(
+        type: 'trace-create',
+        body: trace
+      )
+      enqueue_event(event)
+      trace
+    end
+
+    # Creates a new span within a trace
+    def span(attributes = {})
+      raise ArgumentError, 'trace_id is required for creating a span' unless attributes[:trace_id]
+
+      span = Models::Span.new(attributes)
+      event = Models::IngestionEvent.new(
+        type: 'span-create',
+        body: span
+      )
+      enqueue_event(event)
+      span
+    end
+
+    # Updates an existing span
+    def update_span(span)
+      raise ArgumentError, 'span.id and span.trace_id are required for updating a span' unless span.id && span.trace_id
+
+      event = Models::IngestionEvent.new(
+        type: 'span-update',
+        body: span
+      )
+      enqueue_event(event)
+      span
+    end
+
+    # Creates a new generation within a trace
+    def generation(attributes = {})
+      raise ArgumentError, 'trace_id is required for creating a generation' unless attributes[:trace_id]
+
+      generation = Models::Generation.new(attributes)
+      event = Models::IngestionEvent.new(
+        type: 'generation-create',
+        body: generation
+      )
+      enqueue_event(event)
+      generation
+    end
+
+    # Updates an existing generation
+    def update_generation(generation)
+      unless generation.id && generation.trace_id
+        raise ArgumentError, 'generation.id and generation.trace_id are required for updating a generation'
+      end
+
+      event = Models::IngestionEvent.new(
+        type: 'generation-update',
+        body: generation
+      )
+      enqueue_event(event)
+      generation
+    end
+
+    # Creates a new event within a trace
+    def event(attributes = {})
+      raise ArgumentError, 'trace_id is required for creating an event' unless attributes[:trace_id]
+
+      event_obj = Models::Event.new(attributes)
+      event = Models::IngestionEvent.new(
+        type: 'event-create',
+        body: event_obj
+      )
+      enqueue_event(event)
+      event_obj
+    end
+
+    # Creates a new score
+    def score(attributes = {})
+      raise ArgumentError, 'trace_id is required for creating a score' unless attributes[:trace_id]
+
+      score = Models::Score.new(attributes)
+      event = Models::IngestionEvent.new(
+        type: 'score-create',
+        body: score
+      )
+      enqueue_event(event)
+      score
+    end
+
+    # Flushes all pending events to the API
+    def flush
+      events_to_process = nil
+
+      # Atomically swap the events array to avoid race conditions
+      @mutex.synchronize do
+        events_to_process = @events.dup
+        @events.clear
+      end
+
+      return if events_to_process.empty?
+
+      # Convert objects to hashes for serialization
+      event_hashes = events_to_process.map(&:to_h)
+
+      log("Flushing #{event_hashes.size} events")
+
+      # Send to background worker
+      BatchWorker.perform_async(event_hashes)
+    end
+
+    # Gracefully shuts down the client, ensuring all events are flushed
+    def shutdown
+      log('Shutting down Langfuse client...')
+
+      # Cancel the flush timer if it's running
+      @flush_thread&.exit
+
+      # Flush any remaining events
+      flush
+
+      log('Langfuse client shut down.')
+    end
+
+    private
+
+    def enqueue_event(event)
+      @events << event
+
+      # Trigger immediate flush if batch size reached
+      flush if @events.size >= @config.batch_size
+    end
+
+    def schedule_periodic_flush
+      log("Starting periodic flush thread (interval: #{@config.flush_interval}s)")
+
+      @flush_thread = Thread.new do
+        loop do
+          sleep @config.flush_interval
+          flush
+        rescue StandardError => e
+          log("Error in Langfuse flush thread: #{e.message}", :error)
+          sleep 1 # Avoid tight loop on persistent errors
+        end
+      end
+    end
+
+    def log(message, level = :debug)
+      return unless @config.debug
+
+      logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      logger.send(level, "[Langfuse] #{message}")
+    end
+  end
+end

data/lib/langfuse/configuration.rb

@@ -0,0 +1,20 @@
+module Langfuse
+  class Configuration
+    attr_accessor :public_key, :secret_key, :host,
+                  :batch_size, :flush_interval, :debug,
+                  :disable_at_exit_hook, :shutdown_timeout, :logger
+
+    def initialize
+      # Default configuration with environment variable fallbacks
+      @public_key = ENV['LANGFUSE_PUBLIC_KEY']
+      @secret_key = ENV['LANGFUSE_SECRET_KEY']
+      @host = ENV.fetch('LANGFUSE_HOST', 'https://us.cloud.langfuse.com')
+      @batch_size = ENV.fetch('LANGFUSE_BATCH_SIZE', '10').to_i
+      @flush_interval = ENV.fetch('LANGFUSE_FLUSH_INTERVAL', '60').to_i
+      @debug = ENV.fetch('LANGFUSE_DEBUG', 'false') == 'true'
+      @disable_at_exit_hook = false
+      @shutdown_timeout = ENV.fetch('LANGFUSE_SHUTDOWN_TIMEOUT', '5').to_i
+      @logger = Logger.new(STDOUT)
+    end
+  end
+end

data/lib/langfuse/models/event.rb

@@ -0,0 +1,36 @@
+require 'securerandom'
+
+module Langfuse
+  module Models
+    class Event
+      attr_accessor :id, :trace_id, :name, :start_time,
+                    :metadata, :input, :output, :level, :status_message,
+                    :parent_observation_id, :version, :environment
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          send("#{key}=", value) if respond_to?("#{key}=")
+        end
+        @id ||= SecureRandom.uuid
+        @start_time ||= Time.now.utc
+      end
+
+      def to_h
+        {
+          id: @id,
+          traceId: @trace_id,
+          name: @name,
+          startTime: @start_time&.iso8601(3),
+          metadata: @metadata,
+          input: @input,
+          output: @output,
+          level: @level,
+          statusMessage: @status_message,
+          parentObservationId: @parent_observation_id,
+          version: @version,
+          environment: @environment
+        }.compact
+      end
+    end
+  end
+end

data/lib/langfuse/models/generation.rb

@@ -0,0 +1,45 @@
+require 'securerandom'
+
+module Langfuse
+  module Models
+    class Generation
+      attr_accessor :id, :trace_id, :name, :start_time, :end_time,
+                    :metadata, :input, :output, :level, :status_message,
+                    :parent_observation_id, :version, :environment,
+                    :completion_start_time, :model, :model_parameters,
+                    :usage, :prompt_name, :prompt_version
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          send("#{key}=", value) if respond_to?("#{key}=")
+        end
+        @id ||= SecureRandom.uuid
+        @start_time ||= Time.now.utc
+      end
+
+      def to_h
+        {
+          id: @id,
+          traceId: @trace_id,
+          name: @name,
+          startTime: @start_time&.iso8601(3),
+          endTime: @end_time&.iso8601(3),
+          metadata: @metadata,
+          input: @input,
+          output: @output,
+          level: @level,
+          statusMessage: @status_message,
+          parentObservationId: @parent_observation_id,
+          version: @version,
+          environment: @environment,
+          completionStartTime: @completion_start_time&.iso8601(3),
+          model: @model,
+          modelParameters: @model_parameters,
+          usage: @usage.respond_to?(:to_h) ? @usage.to_h : @usage,
+          promptName: @prompt_name,
+          promptVersion: @prompt_version
+        }.compact
+      end
+    end
+  end
+end