langfuse-rb 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bf0fdf8f1b31f237397c90d8db3fc61c40bc8a69e20111a949aa0bdffc8dd3e
-  data.tar.gz: b6b83329218d23b3ebd53562a4eb5bb1cd01179f07fdbf5d90b2b1c97fc192ef
+  metadata.gz: ba92036fbe7b63b8355a113e44ff3f62cfcb11817ae3b3c1c444756af55ebf84
+  data.tar.gz: 44097d4d441ad6d2d8780a95cb836d0368ed0b772f16036e301ece7e018df0a1
 SHA512:
-  metadata.gz: a0bda13a371bcc93d37d4ae17548f04c65f1cc8fdf4982756eebac468d280f5b3a44d51ecb5ed5406e2ffee204a958988b3423860916471d8eb1a9e728fcf51c
-  data.tar.gz: a2bebff2e84e94c5fa30b6774c89c35f63ed4d2af214a76348a370ddbd9326ff0c8346fac9b3601e9bf9427bdb56f73a3f309f7eb71d439bd31b70426461ae3d
+  metadata.gz: 6e8880c58683dc7ff719f0c966515841e9a3e3df024f88175297090949a6befaddf23528b24a65d3825fa40e33118348087c0dbe5312543c16bfef65856eaf12
+  data.tar.gz: a82f8be469125e99355c5b6a1bd747a1f2e395dd6e0eb098f8319a0976419dfd60087c6252e26c2570db15994ed084d3156069019541c3b32acc7f1827c92792

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-04-24
+
+### Added
+- Probabilistic trace sampling with score parity (#60)
+- Dataset run lifecycle methods: `get_dataset_run`, `list_dataset_runs`, `delete_dataset_run` (#62)
+
+### Fixed
+- Tracing is now isolated-by-default with lazy setup and smart export filtering (#77)
+
+### Documentation
+- Align docs with implementation (#78)
+
 ## [0.7.0] - 2026-04-14
 
 ### Added
@@ -88,7 +100,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.4.0...v0.5.0

data/README.md

@@ -8,69 +8,49 @@
 
 > Ruby SDK for [Langfuse](https://langfuse.com) - Open-source LLM observability and prompt management.
 
-<br>
-
-### Features
-
-- 🎯 **Prompt Management** - Centralized prompt versioning with Mustache templating
-- 📊 **LLM Tracing** - Zero-boilerplate observability built on OpenTelemetry
-- ⚡ **Performance** - In-memory or Redis-backed caching with stampede protection, both supporting stale-while-revalidate cache strategy
-- 💬 **Chat & Text Prompts** - First-class support for both formats
-- 🔄 **Automatic Retries** - Built-in exponential backoff for resilient API calls
-- 🛡️ **Fallback Support** - Graceful degradation when API unavailable
-- 🚀 **Rails-Friendly** - Global configuration pattern, works with any Ruby project
-
-<br>
-
-### Installation
+## Installation
 
 ```ruby
-# Add to Gemfile & bundle install
-gem 'langfuse-rb'
+gem "langfuse-rb"
 ```
 
-<br>
-
-### Quick Start
-
-> Configure once at startup
+## Quick Start
 
 ```ruby
-# config/initializers/langfuse.rb (Rails)
-# Or at the top of your script
 Langfuse.configure do |config|
-  config.public_key = ENV['LANGFUSE_PUBLIC_KEY']
-  config.secret_key = ENV['LANGFUSE_SECRET_KEY']
-  # Optional: for self-hosted instances
-  config.base_url = ENV.fetch('LANGFUSE_BASE_URL', 'https://cloud.langfuse.com')
-
-  # Optional: Enable stale-while-revalidate for best performance
-  config.cache_backend = :rails  # or :memory
-  config.cache_stale_while_revalidate = true
+  config.public_key = ENV["LANGFUSE_PUBLIC_KEY"]
+  config.secret_key = ENV["LANGFUSE_SECRET_KEY"]
+  config.base_url = ENV.fetch("LANGFUSE_BASE_URL", "https://cloud.langfuse.com")
+
+  # Optional: sample traces and trace-linked scores deterministically
+  config.sample_rate = 1.0
 end
+
+message = Langfuse.client.compile_prompt(
+  "greeting",
+  variables: { name: "Alice" }
+)
 ```
 
-> Fetch and use a prompt
+Langfuse tracing is isolated by default. `Langfuse.configure` stores configuration only; it does not replace `OpenTelemetry.tracer_provider`.
 
-```ruby
-prompt = Langfuse.client.get_prompt("greeting")
-message = prompt.compile(name: "Alice")
-# => "Hello Alice!"
-```
+`sample_rate` is applied to traces and trace-linked scores. Rebuild the client with `Langfuse.reset!` before expecting runtime sampling changes to take effect.
 
-> Trace an LLM call
+## Trace an LLM Call
 
 ```ruby
 Langfuse.observe("chat-completion", as_type: :generation) do |gen|
+  gen.model = "gpt-4.1-mini"
+  gen.input = [{ role: "user", content: "Hello!" }]
+
   response = openai_client.chat(
     parameters: {
-      model: "gpt-4",
+      model: "gpt-4.1-mini",
       messages: [{ role: "user", content: "Hello!" }]
     }
   )
 
   gen.update(
-    model: "gpt-4",
     output: response.dig("choices", 0, "message", "content"),
     usage_details: {
       prompt_tokens: response.dig("usage", "prompt_tokens"),
@@ -80,39 +60,14 @@ Langfuse.observe("chat-completion", as_type: :generation) do |gen|
 end
 ```
 
-> [!IMPORTANT]
-> For complete reference see [docs](./docs/) section.
-
-<br>
-
-### Requirements
-
-- Ruby >= 3.2.0
-- No Rails dependency (works with any Ruby project)
-
-<br>
-
-### Contributing
-
-We welcome contributions! Please:
-
-1. Check existing [issues](https://github.com/simplepractice/langfuse-rb/issues)
-2. Open an issue to discuss your idea
-3. Fork the repo and create a feature branch
-4. Write tests (maintain >95% coverage)
-5. Ensure `bundle exec rspec` and `bundle exec rubocop` pass
-6. Submit a pull request
-
-> [!TIP]
-> See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-
-<br>
-
-### Support
+## Start Here
 
-- **[GitHub Issues](https://github.com/simplepractice/langfuse-rb/issues)** - Bug reports and feature requests
-- **[Langfuse Documentation](https://langfuse.com/docs)** - Platform documentation
-- **[API Reference](https://api.reference.langfuse.com)** - REST API reference
+- [Documentation Hub](docs/README.md)
+- [Getting Started](docs/GETTING_STARTED.md)
+- [Prompts](docs/PROMPTS.md)
+- [Tracing](docs/TRACING.md)
+- [Scoring](docs/SCORING.md)
+- [Rails Patterns](docs/RAILS.md)
 
 ## License
 

data/lib/langfuse/api_client.rb

@@ -260,6 +260,61 @@ module Langfuse
       end
     end
 
+    # Fetch a dataset run by dataset and run name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [Hash] The dataset run data
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def get_dataset_run(dataset_name:, run_name:)
+      with_faraday_error_handling do
+        response = connection.get(dataset_run_path(dataset_name: dataset_name, run_name: run_name))
+        handle_response(response)
+      end
+    end
+
+    # List dataset runs in a dataset
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @return [Array<Hash>] Array of dataset run hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def list_dataset_runs(dataset_name:, page: nil, limit: nil)
+      result = list_dataset_runs_paginated(dataset_name: dataset_name, page: page, limit: limit)
+      result["data"] || []
+    end
+
+    # Full paginated response including "meta" for internal pagination use
+    #
+    # @api private
+    # @return [Hash] Full response hash with "data" array and "meta" pagination info
+    def list_dataset_runs_paginated(dataset_name:, page: nil, limit: nil)
+      with_faraday_error_handling do
+        response = connection.get(dataset_runs_path(dataset_name), build_dataset_runs_params(page: page, limit: limit))
+        handle_response(response)
+      end
+    end
+
+    # Delete a dataset run by name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [Hash, nil] Response body, or nil for 204 responses
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    # @note 404 responses raise NotFoundError to preserve strict delete semantics
+    def delete_dataset_run(dataset_name:, run_name:)
+      with_faraday_error_handling do
+        response = connection.delete(dataset_run_path(dataset_name: dataset_name, run_name: run_name))
+        response.status == 204 ? nil : handle_response(response)
+      end
+    end
+
     # Fetch projects accessible with the current API keys
     #
     # @return [Hash] The parsed response body containing project data
@@ -604,6 +659,23 @@ module Langfuse
       }.compact
     end
 
+    # Build params for list_dataset_runs
+    def build_dataset_runs_params(page:, limit:)
+      { page: page, limit: limit }.compact
+    end
+
+    # Build endpoint path for dataset runs
+    def dataset_runs_path(dataset_name)
+      encoded_name = URI.encode_uri_component(dataset_name)
+      "/api/public/datasets/#{encoded_name}/runs"
+    end
+
+    # Build endpoint path for a specific dataset run
+    def dataset_run_path(dataset_name:, run_name:)
+      encoded_run_name = URI.encode_uri_component(run_name)
+      "#{dataset_runs_path(dataset_name)}/#{encoded_run_name}"
+    end
+
     # Build query params for list_traces, mapping snake_case to camelCase
     # rubocop:disable Metrics/ParameterLists
     def build_traces_params(page:, limit:, user_id:, name:, session_id:,

data/lib/langfuse/client.rb

@@ -588,6 +588,51 @@ module Langfuse
       )
     end
 
+    # Fetch a dataset run by dataset and run name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [Hash] The dataset run data, including linked run items
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def get_dataset_run(dataset_name:, run_name:)
+      api_client.get_dataset_run(dataset_name: dataset_name, run_name: run_name)
+    end
+
+    # List dataset runs for a dataset
+    #
+    # When page is nil (default), auto-paginates to fetch all runs.
+    # When page is provided, returns only that single page.
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @return [Array<Hash>] Array of dataset run hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def list_dataset_runs(dataset_name:, page: nil, limit: nil)
+      if page
+        fetch_dataset_runs_page(dataset_name: dataset_name, page: page, limit: limit)
+      else
+        fetch_all_dataset_runs(dataset_name: dataset_name, limit: limit)
+      end
+    end
+
+    # Delete a dataset run by name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [nil]
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    # @note 404 responses raise NotFoundError to preserve strict delete semantics
+    def delete_dataset_run(dataset_name:, run_name:)
+      api_client.delete_dataset_run(dataset_name: dataset_name, run_name: run_name)
+      nil
+    end
+
     # Run an experiment against local data or a named dataset
     #
     # @param name [String] Experiment/run name (required)
@@ -656,17 +701,35 @@ module Langfuse
     end
 
     def fetch_all_dataset_items(limit:, **filters)
-      per_page = limit || DATASET_ITEMS_PAGE_SIZE
-      first_result = api_client.list_dataset_items_paginated(page: 1, limit: per_page, **filters)
-      items = first_result["data"] || []
+      fetch_all_paginated_data(limit: limit) do |page:, per_page:|
+        api_client.list_dataset_items_paginated(page: page, limit: per_page, **filters)
+      end
+    end
+
+    def fetch_dataset_runs_page(dataset_name:, page:, limit:)
+      api_client.list_dataset_runs(dataset_name: dataset_name, page: page, limit: limit)
+    end
+
+    def fetch_all_dataset_runs(dataset_name:, limit:)
+      fetch_all_paginated_data(limit: limit) do |page:, per_page:|
+        api_client.list_dataset_runs_paginated(dataset_name: dataset_name, page: page, limit: per_page)
+      end
+    end
+
+    # Keep dataset collection pagination semantics in one place so edge cases
+    # like missing or zero totalPages stay consistent across APIs.
+    def fetch_all_paginated_data(limit:)
+      page_size = limit || DATASET_ITEMS_PAGE_SIZE
+      first_result = yield(page: 1, per_page: page_size)
+      records = first_result["data"] || []
       total_pages = first_result.dig("meta", "totalPages") || 1
 
-      (2..total_pages).each do |pg|
-        result = api_client.list_dataset_items_paginated(page: pg, limit: per_page, **filters)
-        items.concat(result["data"] || [])
+      (2..total_pages).each do |page|
+        result = yield(page: page, per_page: page_size)
+        records.concat(result["data"] || [])
       end
 
-      items
+      records
     end
 
     def resolve_experiment_items(data, dataset_name)

data/lib/langfuse/config.rb

@@ -18,6 +18,7 @@ module Langfuse
   #     c.secret_key = "sk_..."
   #   end
   #
+  # rubocop:disable Metrics/ClassLength
   class Config
     # @return [String, nil] Langfuse public API key
     attr_accessor :public_key
@@ -74,6 +75,12 @@ module Langfuse
     # @return [String, nil] Default release identifier applied to new traces/observations
     attr_accessor :release
 
+    # @return [Float] Trace sampling rate from 0.0 to 1.0
+    attr_reader :sample_rate
+
+    # @return [#call, nil] Callback that decides whether an ended span should export to Langfuse.
+    attr_accessor :should_export_span
+
     # @return [#call, nil] Mask callable applied to input, output, and metadata before serialization.
     #   Receives `data:` keyword argument. nil disables masking.
     attr_accessor :mask
@@ -114,6 +121,9 @@ module Langfuse
     # @return [Symbol] Default ActiveJob queue name
     DEFAULT_JOB_QUEUE = :default
 
+    # @return [Float] Default trace sampling rate (sample all traces)
+    DEFAULT_SAMPLE_RATE = 1.0
+
     # @return [Integer] Number of seconds representing indefinite cache duration (~1000 years)
     INDEFINITE_SECONDS = 1000 * 365 * 24 * 60 * 60
 
@@ -136,7 +146,6 @@ module Langfuse
     # @yield [config] Optional block for configuration
     # @yieldparam config [Config] The config instance
     # @return [Config] a new Config instance
-    # rubocop:disable Metrics/AbcSize
     def initialize
       @public_key = ENV.fetch("LANGFUSE_PUBLIC_KEY", nil)
       @secret_key = ENV.fetch("LANGFUSE_SECRET_KEY", nil)
@@ -153,14 +162,11 @@ module Langfuse
       @batch_size = DEFAULT_BATCH_SIZE
       @flush_interval = DEFAULT_FLUSH_INTERVAL
       @job_queue = DEFAULT_JOB_QUEUE
-      @environment = env_value("LANGFUSE_TRACING_ENVIRONMENT")
-      @release = env_value("LANGFUSE_RELEASE") || detect_release_from_ci_env
-      @mask = nil
+      initialize_tracing_defaults
       @logger = default_logger
 
       yield(self) if block_given?
     end
-    # rubocop:enable Metrics/AbcSize
 
     # Validate the configuration
     #
@@ -183,7 +189,8 @@ module Langfuse
       validate_swr_config!
 
       validate_cache_backend!
-
+      validate_sample_rate!
+      validate_should_export_span!
       validate_mask!
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -205,6 +212,15 @@ module Langfuse
       cache_stale_ttl == :indefinite ? INDEFINITE_SECONDS : cache_stale_ttl
     end
 
+    # Set trace sampling rate.
+    #
+    # @param value [Numeric, String] Sampling rate from 0.0 to 1.0
+    # @raise [ConfigurationError] if value is non-numeric or outside 0.0..1.0
+    # @return [Float]
+    def sample_rate=(value)
+      @sample_rate = coerce_sample_rate(value)
+    end
+
     private
 
     def default_logger
@@ -215,6 +231,14 @@ module Langfuse
       end
     end
 
+    def initialize_tracing_defaults
+      @environment = env_value("LANGFUSE_TRACING_ENVIRONMENT")
+      @release = env_value("LANGFUSE_RELEASE") || detect_release_from_ci_env
+      self.sample_rate = env_value("LANGFUSE_SAMPLE_RATE") || DEFAULT_SAMPLE_RATE
+      @should_export_span = nil
+      @mask = nil
+    end
+
     def validate_cache_backend!
       valid_backends = %i[memory rails]
       return if valid_backends.include?(cache_backend)
@@ -255,12 +279,24 @@ module Langfuse
       raise ConfigurationError, "cache_refresh_threads must be positive"
     end
 
+    def validate_sample_rate!
+      return if sample_rate.is_a?(Numeric) && sample_rate.between?(0.0, 1.0)
+
+      raise ConfigurationError, "sample_rate must be between 0.0 and 1.0"
+    end
+
     def validate_mask!
       return if mask.nil? || mask.respond_to?(:call)
 
       raise ConfigurationError, "mask must respond to #call"
     end
 
+    def validate_should_export_span!
+      return if should_export_span.nil? || should_export_span.respond_to?(:call)
+
+      raise ConfigurationError, "should_export_span must respond to #call"
+    end
+
     def detect_release_from_ci_env
       COMMON_RELEASE_ENV_KEYS.each do |key|
         value = env_value(key)
@@ -276,5 +312,22 @@ module Langfuse
 
       value
     end
+
+    def coerce_sample_rate(value)
+      numeric_value = if value.is_a?(Numeric)
+                        value.to_f
+                      elsif value.is_a?(String)
+                        Float(value)
+                      else
+                        raise ConfigurationError, "sample_rate must be numeric"
+                      end
+
+      return numeric_value if numeric_value.between?(0.0, 1.0)
+
+      raise ConfigurationError, "sample_rate must be between 0.0 and 1.0"
+    rescue ArgumentError, TypeError
+      raise ConfigurationError, "sample_rate must be numeric"
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/otel_setup.rb

@@ -2,104 +2,78 @@
 
 require "opentelemetry/sdk"
 require "opentelemetry/exporter/otlp"
-require "opentelemetry/trace/propagation/trace_context"
 require "base64"
 
 module Langfuse
-  # OpenTelemetry initialization and setup
-  #
-  # Handles configuration of the OTel SDK with Langfuse OTLP exporter
-  # when tracing is enabled.
-  #
+  # OpenTelemetry initialization and setup for Langfuse tracing.
+  # rubocop:disable Metrics/ModuleLength
   module OtelSetup
+    TRACING_CONFIG_FIELDS = %i[
+      public_key
+      secret_key
+      base_url
+      environment
+      release
+      sample_rate
+      should_export_span
+      tracing_async
+      batch_size
+      flush_interval
+    ].freeze
+    private_constant(:TRACING_CONFIG_FIELDS)
+
     class << self
-      # @return [OpenTelemetry::SDK::Trace::TracerProvider, nil] The configured tracer provider
+      # @return [OpenTelemetry::SDK::Trace::TracerProvider, nil] The configured internal tracer provider
       attr_reader :tracer_provider
 
-      # Initialize OpenTelemetry with Langfuse OTLP exporter
+      # Initialize Langfuse's internal tracer provider without mutating global OpenTelemetry state.
       #
       # @param config [Langfuse::Config] The Langfuse configuration
-      # @return [void]
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # @return [OpenTelemetry::SDK::Trace::TracerProvider]
       def setup(config)
-        # Create OTLP exporter configured for Langfuse
-        exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
-          endpoint: "#{config.base_url}/api/public/otel/v1/traces",
-          headers: build_headers(config.public_key, config.secret_key),
-          compression: "gzip"
-        )
-
-        # Create processor based on async configuration
-        # IMPORTANT: Always use BatchSpanProcessor (even in sync mode) to ensure spans
-        # are exported together, which allows proper parent-child relationship detection
-        processor = if config.tracing_async
-                      # Async: BatchSpanProcessor batches and sends in background
-                      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-                        exporter,
-                        max_queue_size: config.batch_size * 2, # Buffer more than batch_size
-                        schedule_delay: config.flush_interval * 1000, # Convert seconds to milliseconds
-                        max_export_batch_size: config.batch_size
-                      )
-                    else
-                      # Sync: BatchSpanProcessor with minimal delay (flushes on force_flush)
-                      # This collects spans from the same trace and exports them together,
-                      # which is critical for correct parent_observation_id calculation
-                      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-                        exporter,
-                        max_queue_size: config.batch_size * 2,
-                        schedule_delay: 60_000, # 60 seconds (relies on explicit force_flush)
-                        max_export_batch_size: config.batch_size
-                      )
-                    end
-
-        # Create TracerProvider with processor
-        @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
-        @tracer_provider.add_span_processor(processor)
-
-        # Add span processor for propagated attributes and env/release defaults
-        # This must be added AFTER the BatchSpanProcessor so it runs before export and can
-        # apply all attributes (propagated IDs, environment, release) to the spans being sent
-        span_processor = SpanProcessor.new(config: config)
-        @tracer_provider.add_span_processor(span_processor)
-
-        # Set as global tracer provider
-        OpenTelemetry.tracer_provider = @tracer_provider
-
-        # Configure W3C TraceContext propagator if not already set
-        if OpenTelemetry.propagation.is_a?(OpenTelemetry::Context::Propagation::NoopTextMapPropagator)
-          OpenTelemetry.propagation = OpenTelemetry::Trace::Propagation::TraceContext::TextMapPropagator.new
-          config.logger.debug("Langfuse: Configured W3C TraceContext propagator")
-        else
-          config.logger.debug("Langfuse: Using existing propagator: #{OpenTelemetry.propagation.class}")
+        validate_tracing_config!(config)
+        return existing_provider_for(config) if initialized?
+
+        candidate_provider = nil
+        provider = nil
+        created = false
+        candidate_provider = build_tracer_provider(config)
+        provider, created = publish_provider(candidate_provider, tracing_config_snapshot(config))
+        unless created
+          candidate_provider.shutdown(timeout: 30)
+          return existing_provider_for(config)
         end
 
-        mode = config.tracing_async ? "async" : "sync"
-        config.logger.info("Langfuse tracing initialized with OpenTelemetry (#{mode} mode)")
+        log_initialized(config)
+        provider
+      rescue StandardError
+        rollback_provider(provider) if created
+        raise
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
-      # Shutdown the tracer provider and flush any pending spans
+      # Shutdown the internal tracer provider and flush any pending spans.
       #
       # @param timeout [Integer] Timeout in seconds
       # @return [void]
       def shutdown(timeout: 30)
-        return unless @tracer_provider
-
-        @tracer_provider.shutdown(timeout: timeout)
-        @tracer_provider = nil
+        provider = nil
+        setup_mutex.synchronize do
+          provider = @tracer_provider
+          @tracer_provider = nil
+          @config_snapshot = nil
+        end
+        provider&.shutdown(timeout: timeout)
       end
 
-      # Force flush all pending spans
+      # Force flush all pending spans on the internal tracer provider.
       #
       # @param timeout [Integer] Timeout in seconds
       # @return [void]
       def force_flush(timeout: 30)
-        return unless @tracer_provider
-
-        @tracer_provider.force_flush(timeout: timeout)
+        @tracer_provider&.force_flush(timeout: timeout)
       end
 
-      # Check if OTel is initialized
+      # Check if Langfuse tracing has been initialized.
       #
       # @return [Boolean]
       def initialized?
@@ -108,18 +82,104 @@ module Langfuse
 
       private
 
-      # Build HTTP headers for Langfuse OTLP endpoint
-      #
-      # @param public_key [String] Langfuse public API key
-      # @param secret_key [String] Langfuse secret API key
-      # @return [Hash] HTTP headers with Basic Auth
+      def existing_provider_for(config)
+        snapshot = tracing_config_snapshot(config)
+        if @config_snapshot == snapshot
+          config.logger.debug("Langfuse tracing already initialized; reusing existing tracer provider")
+        else
+          config.logger.warn(
+            "Langfuse tracing is already initialized. Changes to #{TRACING_CONFIG_FIELDS.join(', ')} " \
+            "require Langfuse.reset! before they take effect."
+          )
+        end
+        @tracer_provider
+      end
+
+      def publish_provider(provider, snapshot)
+        created = false
+        current = nil
+
+        # This mutex only guards publication so setup never exposes a half-built provider.
+        setup_mutex.synchronize do
+          if @tracer_provider
+            current = @tracer_provider
+          else
+            @tracer_provider = provider
+            @config_snapshot = snapshot
+            current = provider
+            created = true
+          end
+        end
+
+        [current, created]
+      end
+
+      def rollback_provider(provider)
+        setup_mutex.synchronize do
+          return unless @tracer_provider.equal?(provider)
+
+          @tracer_provider = nil
+          @config_snapshot = nil
+        end
+        provider.shutdown(timeout: 1)
+      rescue StandardError
+        nil
+      end
+
+      def build_tracer_provider(config)
+        provider = OpenTelemetry::SDK::Trace::TracerProvider.new(
+          sampler: build_sampler(config.sample_rate)
+        )
+        provider.add_span_processor(
+          SpanProcessor.new(config: config, exporter: build_exporter(config))
+        )
+        provider
+      end
+
+      def build_exporter(config)
+        OpenTelemetry::Exporter::OTLP::Exporter.new(
+          endpoint: "#{config.base_url}/api/public/otel/v1/traces",
+          headers: build_headers(config.public_key, config.secret_key),
+          compression: "gzip"
+        )
+      end
+
+      def log_initialized(config)
+        mode = config.tracing_async ? "async" : "sync"
+        config.logger.info("Langfuse tracing initialized with OpenTelemetry (#{mode} mode)")
+      end
+
+      def validate_tracing_config!(config)
+        raise ConfigurationError, "public_key is required" if blank?(config.public_key)
+        raise ConfigurationError, "secret_key is required" if blank?(config.secret_key)
+        raise ConfigurationError, "base_url cannot be empty" if blank?(config.base_url)
+        return if config.should_export_span.nil? || config.should_export_span.respond_to?(:call)
+
+        raise ConfigurationError, "should_export_span must respond to #call"
+      end
+
+      def tracing_config_snapshot(config)
+        TRACING_CONFIG_FIELDS.to_h { |field| [field, config.public_send(field)] }.freeze
+      end
+
+      def setup_mutex
+        @setup_mutex ||= Mutex.new
+      end
+
+      def blank?(value)
+        value.nil? || value.empty?
+      end
+
       def build_headers(public_key, secret_key)
         credentials = "#{public_key}:#{secret_key}"
         encoded = Base64.strict_encode64(credentials)
-        {
-          "Authorization" => "Basic #{encoded}"
-        }
+        { "Authorization" => "Basic #{encoded}" }
+      end
+
+      def build_sampler(sample_rate)
+        Sampling.build_sampler(sample_rate) || OpenTelemetry::SDK::Trace::Samplers::ALWAYS_ON
       end
     end
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/langfuse/sampling.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Shared sampling helpers for trace and score emission.
+  #
+  # @api private
+  module Sampling
+    module_function
+
+    # Build the sampler used by both trace export and trace-linked score emission.
+    #
+    # @param sample_rate [Float] Sampling rate from 0.0 to 1.0
+    # @return [OpenTelemetry::SDK::Trace::Samplers::TraceIdRatioBased, nil]
+    def build_sampler(sample_rate)
+      return nil if sample_rate >= 1.0
+
+      OpenTelemetry::SDK::Trace::Samplers::TraceIdRatioBased.new(sample_rate)
+    end
+  end
+end

data/lib/langfuse/score_client.rb

@@ -31,6 +31,8 @@ module Langfuse
     # @return [Logger] Logger instance
     attr_reader :logger
 
+    HEX_TRACE_ID_PATTERN = /\A[0-9a-f]{32}\z/
+
     # Initialize a new ScoreClient
     #
     # @param api_client [ApiClient] The API client for sending batches
@@ -43,6 +45,9 @@ module Langfuse
       @mutex = Mutex.new
       @flush_thread = nil
       @shutdown = false
+      # Match the immutable tracing setup contract: once this client exists, later config
+      # mutations must not change score sampling without rebuilding the client.
+      @score_sampler = Sampling.build_sampler(config.sample_rate)
 
       start_flush_timer
     end
@@ -76,28 +81,19 @@ module Langfuse
     def create(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
                metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
       validate_name(name)
-      # Keep identifier policy server-side to preserve cross-SDK parity and avoid blocking valid future payloads.
       normalized_value = normalize_value(value, data_type)
       data_type_str = Types::SCORE_DATA_TYPES[data_type] || raise(ArgumentError, "Invalid data_type: #{data_type}")
 
+      return unless enqueue_trace_linked_score?(trace_id)
+
       event = build_score_event(
-        name: name,
-        value: normalized_value,
-        id: id,
-        trace_id: trace_id,
-        session_id: session_id,
-        observation_id: observation_id,
-        comment: comment,
-        metadata: metadata,
-        environment: environment,
-        data_type: data_type_str,
-        dataset_run_id: dataset_run_id,
-        config_id: config_id
+        name: name, value: normalized_value, id: id, trace_id: trace_id,
+        session_id: session_id, observation_id: observation_id, comment: comment,
+        metadata: metadata, environment: environment, data_type: data_type_str,
+        dataset_run_id: dataset_run_id, config_id: config_id
       )
 
       @queue << event
-
-      # Trigger flush if batch size reached
       flush if @queue.size >= config.batch_size
     rescue StandardError => e
       logger.error("Langfuse score creation failed: #{e.message}")
@@ -294,14 +290,43 @@ module Langfuse
     # @return [Hash] Hash with :trace_id and :observation_id (may be nil)
     def extract_ids_from_active_span
       span = OpenTelemetry::Trace.current_span
-      return { trace_id: nil, observation_id: nil } unless span&.recording?
+      span_context = span&.context
+      return { trace_id: nil, observation_id: nil } unless span_context&.valid?
 
       {
-        trace_id: span.context.trace_id.unpack1("H*"),
-        observation_id: span.context.span_id.unpack1("H*")
+        trace_id: span_context.trace_id.unpack1("H*"),
+        observation_id: span_context.span_id.unpack1("H*")
       }
     end
 
+    # Score sampling is decided purely by the configured sampler on the trace_id hash,
+    # matching langfuse-python. Non-hex trace ids and session/dataset-only scores bypass sampling.
+    def enqueue_trace_linked_score?(trace_id)
+      return true if trace_id.nil?
+      return true unless HEX_TRACE_ID_PATTERN.match?(trace_id)
+
+      sampler = score_sampler
+      return true if sampler.nil?
+      return true unless sampler.respond_to?(:should_sample?)
+
+      sample_result = sampler.should_sample?(
+        trace_id: [trace_id].pack("H*"),
+        parent_context: nil,
+        links: [],
+        name: "score",
+        kind: OpenTelemetry::Trace::SpanKind::INTERNAL,
+        attributes: {}
+      )
+      sample_result.sampled?
+    rescue StandardError => e
+      logger.warn("Langfuse score sampling fallback for trace_id=#{trace_id}: #{e.message}")
+      true
+    end
+
+    # Sampler is pinned at ScoreClient construction to match the "sample_rate requires reset!"
+    # contract and to keep each client's sampling scoped to its own config.
+    attr_reader :score_sampler
+
     # Send a batch of events to the API
     #
     # @param events [Array<Hash>] Array of event hashes

data/lib/langfuse/span_filter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Instrumentation scope name used by module-level Langfuse tracing.
+  LANGFUSE_TRACER_NAME = "langfuse-rb"
+
+  # Conservative allowlist of instrumentation scope prefixes that clearly belong to LLM workflows.
+  KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES = [
+    LANGFUSE_TRACER_NAME,
+    "agent_framework",
+    "ai",
+    "haystack",
+    "langsmith",
+    "litellm",
+    "openinference",
+    "opentelemetry.instrumentation.anthropic",
+    "strands-agents",
+    "vllm"
+  ].freeze
+
+  # Matched per span in the export path, so avoid allocating the dotted form each call.
+  KNOWN_LLM_INSTRUMENTATION_SCOPE_DOTTED_PREFIXES =
+    KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES.map { |prefix| "#{prefix}." }.freeze
+  private_constant :KNOWN_LLM_INSTRUMENTATION_SCOPE_DOTTED_PREFIXES
+
+  class << self
+    # Return whether the span was created by Langfuse's tracer.
+    #
+    # @param span [#instrumentation_scope] Span or span data to inspect
+    # @return [Boolean]
+    def langfuse_span?(span)
+      instrumentation_scope_name(span) == LANGFUSE_TRACER_NAME
+    end
+
+    # Return whether the span contains `gen_ai.*` attributes.
+    #
+    # @param span [#attributes] Span or span data to inspect
+    # @return [Boolean]
+    def genai_span?(span)
+      attributes = span.attributes
+      return false unless attributes
+
+      attributes.keys.any? { |key| key.is_a?(String) && key.start_with?("gen_ai.") }
+    end
+
+    # Return whether the span came from a known LLM instrumentation scope.
+    #
+    # @param span [#instrumentation_scope] Span or span data to inspect
+    # @return [Boolean]
+    def known_llm_instrumentor?(span)
+      scope_name = instrumentation_scope_name(span)
+      return false unless scope_name
+
+      return true if KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES.include?(scope_name)
+
+      KNOWN_LLM_INSTRUMENTATION_SCOPE_DOTTED_PREFIXES.any? do |dotted_prefix|
+        scope_name.start_with?(dotted_prefix)
+      end
+    end
+
+    # Return whether a span should be exported when no custom filter is configured.
+    #
+    # @param span [#instrumentation_scope, #attributes] Span or span data to inspect
+    # @return [Boolean]
+    def default_export_span?(span)
+      langfuse_span?(span) || genai_span?(span) || known_llm_instrumentor?(span)
+    end
+
+    # Cross-SDK parity keeps the `is_*` names public for compatibility.
+    alias is_langfuse_span langfuse_span?
+    alias is_genai_span genai_span?
+    alias is_known_llm_instrumentor known_llm_instrumentor?
+    alias is_default_export_span default_export_span?
+
+    private
+
+    def instrumentation_scope_name(span)
+      span.instrumentation_scope&.name
+    end
+  end
+end

data/lib/langfuse/span_processor.rb

@@ -3,22 +3,26 @@
 require "opentelemetry/sdk"
 
 module Langfuse
-  # Span processor that applies default and propagated trace attributes on new spans.
-  #
-  # On span start, this processor first applies configured trace defaults
-  # (environment/release), then overlays attributes propagated in OpenTelemetry
-  # context (user/session/metadata/tags/version). This ensures consistent
-  # trace dimensions while still honoring per-request propagation.
+  # Batch span processor that owns Langfuse's enrichment and export filtering.
   #
   # @api private
-  class SpanProcessor < OpenTelemetry::SDK::Trace::SpanProcessor
-    # @param config [Langfuse::Config, nil] SDK configuration used to build trace defaults
-    def initialize(config: Langfuse.configuration)
+  class SpanProcessor < OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor
+    # @param config [Langfuse::Config] SDK configuration used for defaults and filtering
+    # @param exporter [#export, #force_flush, #shutdown] Span exporter used by the batch processor
+    def initialize(config:, exporter:)
+      @logger = config.logger
       @default_trace_attributes = build_default_trace_attributes(config).freeze
-      super()
+      @should_export_span = config.should_export_span || Langfuse.method(:default_export_span?)
+
+      super(
+        exporter,
+        max_queue_size: config.batch_size * 2,
+        schedule_delay: schedule_delay_for(config),
+        max_export_batch_size: config.batch_size
+      )
     end
 
-    # Called when a span starts
+    # Apply Langfuse trace defaults and propagated attributes before a span records work.
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that started
     # @param parent_context [OpenTelemetry::Context] The parent context
@@ -30,41 +34,28 @@ module Langfuse
       apply_attributes(span, propagated_attributes(parent_context))
     end
 
-    # Called when a span ends
+    # Drop spans when the export filter rejects them or raises.
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that ended
     # @return [void]
     def on_finish(span)
-      # No-op - we don't need to do anything when spans finish
-    end
+      return unless should_export_span?(span)
 
-    # Shutdown the processor
-    #
-    # @param timeout [Integer, nil] Timeout in seconds (unused for this processor)
-    # @return [Integer] Always returns 0 (no timeout needed for no-op)
-    def shutdown(timeout: nil)
-      # No-op - nothing to clean up
-      # Return 0 to match OpenTelemetry SDK expectation (it finds max timeout from processors)
-      _ = timeout # Suppress unused argument warning
-      0
-    end
-
-    # Force flush (no-op for this processor)
-    #
-    # @param timeout [Integer, nil] Timeout in seconds (unused for this processor)
-    # @return [Integer] Always returns 0 (no timeout needed for no-op)
-    def force_flush(timeout: nil)
-      # No-op - nothing to flush
-      # Return 0 to match OpenTelemetry SDK expectation (it finds max timeout from processors)
-      _ = timeout # Suppress unused argument warning
-      0
+      super
     end
 
     private
 
-    def build_default_trace_attributes(config)
-      return {} unless config
+    # Sync mode relies on explicit `force_flush` calls, so keep the background flush
+    # interval long enough that it rarely fires on its own.
+    SYNC_SCHEDULE_DELAY_MS = 60_000
+    private_constant :SYNC_SCHEDULE_DELAY_MS
+
+    def schedule_delay_for(config)
+      config.tracing_async ? config.flush_interval * 1000 : SYNC_SCHEDULE_DELAY_MS
+    end
 
+    def build_default_trace_attributes(config)
       OtelAttributes.create_trace_attributes(
         { environment: config.environment, release: config.release }
       )
@@ -79,5 +70,15 @@ module Langfuse
     def apply_attributes(span, attributes)
       attributes.each { |key, value| span.set_attribute(key, value) }
     end
+
+    def should_export_span?(span)
+      @should_export_span.call(span)
+    rescue StandardError => e
+      @logger.error(
+        "Langfuse tracing dropped span '#{span.name}' because should_export_span raised: " \
+        "#{e.class}: #{e.message}"
+      )
+      false
+    end
   end
 end

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/langfuse.rb

@@ -44,6 +44,8 @@ require_relative "langfuse/prompt_cache"
 require_relative "langfuse/rails_cache_adapter"
 require_relative "langfuse/cache_warmer"
 require_relative "langfuse/api_client"
+require_relative "langfuse/span_filter"
+require_relative "langfuse/sampling"
 require_relative "langfuse/otel_setup"
 require_relative "langfuse/masking"
 require_relative "langfuse/otel_attributes"
@@ -91,10 +93,6 @@ module Langfuse
     #   end
     def configure
       yield(configuration)
-
-      # Auto-initialize OpenTelemetry
-      OtelSetup.setup(configuration)
-
       configuration
     end
 
@@ -105,6 +103,28 @@ module Langfuse
       @client ||= Client.new(configuration)
     end
 
+    # Return Langfuse's internal tracer provider for explicit global OpenTelemetry installation.
+    #
+    # @return [OpenTelemetry::SDK::Trace::TracerProvider]
+    # @raise [ConfigurationError] if tracing is not fully configured
+    #
+    # @example
+    #   Langfuse.configure do |config|
+    #     config.public_key = ENV["LANGFUSE_PUBLIC_KEY"]
+    #     config.secret_key = ENV["LANGFUSE_SECRET_KEY"]
+    #   end
+    #
+    #   OpenTelemetry.tracer_provider = Langfuse.tracer_provider
+    def tracer_provider
+      unless tracing_config_ready?
+        raise ConfigurationError,
+              "Langfuse tracing is disabled until public_key, secret_key, and base_url are configured."
+      end
+
+      OtelSetup.setup(configuration) unless OtelSetup.initialized?
+      OtelSetup.tracer_provider
+    end
+
     # Shutdown Langfuse and flush any pending traces and scores
     #
     # Call this when shutting down your application to ensure
@@ -323,10 +343,14 @@ module Langfuse
       OtelSetup.shutdown(timeout: 5) if OtelSetup.initialized?
       @configuration = nil
       @client = nil
+      @noop_tracer = nil
+      @tracing_disabled_warning_emitted = false
     rescue StandardError
       # Ignore shutdown errors during reset (e.g., in tests)
       @configuration = nil
       @client = nil
+      @noop_tracer = nil
+      @tracing_disabled_warning_emitted = false
     end
 
     # Creates a new observation (root or child)
@@ -478,7 +502,10 @@ module Langfuse
     #
     # @return [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
     def otel_tracer
-      OpenTelemetry.tracer_provider.tracer("langfuse-rb", Langfuse::VERSION)
+      return tracer_provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION) if setup_tracing_if_ready
+
+      warn_tracing_disabled_once
+      noop_tracer
     end
 
     # Creates an OpenTelemetry span (root or child)
@@ -514,6 +541,47 @@ module Langfuse
       observation_class = OBSERVATION_TYPE_REGISTRY[type_str] || Span
       observation_class.new(otel_span, otel_tracer, attributes: attributes)
     end
+
+    # rubocop:disable Naming/PredicateMethod
+    def setup_tracing_if_ready
+      return true if OtelSetup.initialized?
+      return false unless tracing_config_ready?
+
+      OtelSetup.setup(configuration)
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    def tracing_config_ready?
+      configured?(configuration.public_key) &&
+        configured?(configuration.secret_key) &&
+        configured?(configuration.base_url)
+    end
+
+    def configured?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def warn_tracing_disabled_once
+      return if @tracing_disabled_warning_emitted
+
+      tracing_warning_mutex.synchronize do
+        return if @tracing_disabled_warning_emitted
+
+        configuration.logger.warn(
+          "Langfuse tracing is disabled until public_key, secret_key, and base_url are configured."
+        )
+        @tracing_disabled_warning_emitted = true
+      end
+    end
+
+    def tracing_warning_mutex
+      @tracing_warning_mutex ||= Mutex.new
+    end
+
+    def noop_tracer
+      @noop_tracer ||= OpenTelemetry::Trace::TracerProvider.new.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION)
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - SimplePractice
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -179,7 +179,9 @@ files:
 - lib/langfuse/prompt_cache.rb
 - lib/langfuse/propagation.rb
 - lib/langfuse/rails_cache_adapter.rb
+- lib/langfuse/sampling.rb
 - lib/langfuse/score_client.rb
+- lib/langfuse/span_filter.rb
 - lib/langfuse/span_processor.rb
 - lib/langfuse/stale_while_revalidate.rb
 - lib/langfuse/text_prompt_client.rb