Class: Langfuse::Config

Inherits:

Object

Object
Langfuse::Config

show all

Defined in:: lib/langfuse/config.rb

Overview

Configuration object for Langfuse client

rubocop:disable Metrics/ClassLength

Examples:

Global configuration

Langfuse.configure do |config|
  config.public_key = ENV['LANGFUSE_PUBLIC_KEY']
  config.secret_key = ENV['LANGFUSE_SECRET_KEY']
  config.cache_ttl = 120
end

Per-client configuration

config = Langfuse::Config.new do |c|
  c.public_key = "pk_..."
  c.secret_key = "sk_..."
end

Constant Summary collapse

DEFAULT_BASE_URL = Returns Default Langfuse API base URL. Returns: (String) — Default Langfuse API base URL

"https://cloud.langfuse.com"

DEFAULT_TIMEOUT = Returns Default HTTP request timeout in seconds. Returns: (Integer) — Default HTTP request timeout in seconds

DEFAULT_CACHE_TTL = Returns Default cache TTL in seconds. Returns: (Integer) — Default cache TTL in seconds

DEFAULT_CACHE_MAX_SIZE = Returns Default maximum number of cached items. Returns: (Integer) — Default maximum number of cached items

DEFAULT_CACHE_BACKEND = Returns Default cache backend. Returns: (Symbol) — Default cache backend

:memory

DEFAULT_CACHE_LOCK_TIMEOUT = Returns Default lock timeout in seconds for cache stampede protection. Returns: (Integer) — Default lock timeout in seconds for cache stampede protection

DEFAULT_CACHE_STALE_WHILE_REVALIDATE = Returns Default stale-while-revalidate setting. Returns: (Boolean) — Default stale-while-revalidate setting

false

DEFAULT_CACHE_REFRESH_THREADS = Returns Default number of background threads for cache refresh. Returns: (Integer) — Default number of background threads for cache refresh

DEFAULT_TRACING_ASYNC = Returns Default async processing setting. Returns: (Boolean) — Default async processing setting

true

DEFAULT_BATCH_SIZE = Returns Default number of events to batch before sending. Returns: (Integer) — Default number of events to batch before sending

DEFAULT_FLUSH_INTERVAL = Returns Default flush interval in seconds. Returns: (Integer) — Default flush interval in seconds

DEFAULT_JOB_QUEUE = Returns Default ActiveJob queue name. Returns: (Symbol) — Default ActiveJob queue name

:default

DEFAULT_SAMPLE_RATE = Returns Default trace sampling rate (sample all traces). Returns: (Float) — Default trace sampling rate (sample all traces)

1.0

INDEFINITE_SECONDS = Returns Number of seconds representing indefinite cache duration (~1000 years). Returns: (Integer) — Number of seconds representing indefinite cache duration (~1000 years)

1000 * 365 * 24 * 60 * 60

COMMON_RELEASE_ENV_KEYS = Returns Common CI environment variables that contain a release SHA. Returns: (Array<String>) — Common CI environment variables that contain a release SHA

%w[
  RENDER_GIT_COMMIT
  CI_COMMIT_SHA
  CIRCLE_SHA1
  SOURCE_VERSION
  TRAVIS_COMMIT
  GIT_COMMIT
  GITHUB_SHA
  BITBUCKET_COMMIT
  BUILD_SOURCEVERSION
  DRONE_COMMIT_SHA
].freeze

Instance Attribute Summary collapse

#base_url ⇒ String

Base URL for Langfuse API.
#batch_size ⇒ Integer

Number of events to batch before sending.
#cache_backend ⇒ Symbol

Cache backend (:memory or :rails).
#cache_lock_timeout ⇒ Integer

Lock timeout in seconds for distributed cache stampede protection.
#cache_max_size ⇒ Integer

Maximum number of cached items.
#cache_refresh_threads ⇒ Integer

Number of background threads for cache refresh.
#cache_stale_ttl ⇒ Integer, Symbol

Stale TTL in seconds (grace period for serving stale data, default: 0) Accepts :indefinite which is automatically normalized to 1000 years (31,536,000,000 seconds) for practical “never expire” behavior.
#cache_stale_while_revalidate ⇒ Boolean

Enable stale-while-revalidate caching (requires cache_stale_ttl > 0 to activate).
#cache_ttl ⇒ Integer

Cache TTL in seconds.
#environment ⇒ String^?

Default tracing environment applied to new traces/observations.
#flush_interval ⇒ Integer

Interval in seconds to flush buffered events.
#job_queue ⇒ Symbol

ActiveJob queue name for async processing.
#logger ⇒ Logger

Logger instance for debugging.
#mask ⇒ #call^?

Mask callable applied to input, output, and metadata before serialization.
#public_key ⇒ String^?

Langfuse public API key.
#release ⇒ String^?

Default release identifier applied to new traces/observations.
#sample_rate ⇒ Float

Trace sampling rate from 0.0 to 1.0.
#secret_key ⇒ String^?

Langfuse secret API key.
#should_export_span ⇒ #call^?

Callback that decides whether an ended span should export to Langfuse.
#timeout ⇒ Integer

HTTP request timeout in seconds.
#tracing_async ⇒ Boolean

Use async processing for traces (requires ActiveJob).

Instance Method Summary collapse

#initialize {|config| ... } ⇒ Config constructor

Initialize a new Config object.
#normalized_stale_ttl ⇒ Integer

Normalize stale_ttl value.
#validate! ⇒ void

Validate the configuration.

Constructor Details

#initialize {|config| ... } ⇒ `Config`

Initialize a new Config object

Yields:

(config) —

Optional block for configuration

Yield Parameters:

config (Config) —

The config instance

# File 'lib/langfuse/config.rb', line 149

def initialize
  @public_key = ENV.fetch("LANGFUSE_PUBLIC_KEY", nil)
  @secret_key = ENV.fetch("LANGFUSE_SECRET_KEY", nil)
  @base_url = ENV.fetch("LANGFUSE_BASE_URL", DEFAULT_BASE_URL)
  @timeout = DEFAULT_TIMEOUT
  @cache_ttl = DEFAULT_CACHE_TTL
  @cache_max_size = DEFAULT_CACHE_MAX_SIZE
  @cache_backend = DEFAULT_CACHE_BACKEND
  @cache_lock_timeout = DEFAULT_CACHE_LOCK_TIMEOUT
  @cache_stale_while_revalidate = DEFAULT_CACHE_STALE_WHILE_REVALIDATE
  @cache_stale_ttl = 0 # Default to 0 (SWR disabled, entries expire immediately after TTL)
  @cache_refresh_threads = DEFAULT_CACHE_REFRESH_THREADS
  @tracing_async = DEFAULT_TRACING_ASYNC
  @batch_size = DEFAULT_BATCH_SIZE
  @flush_interval = DEFAULT_FLUSH_INTERVAL
  @job_queue = DEFAULT_JOB_QUEUE
  initialize_tracing_defaults
  @logger = default_logger

  yield(self) if block_given?
end

Instance Attribute Details

#base_url ⇒ `String`

Returns Base URL for Langfuse API.

Returns:

(String) —

Base URL for Langfuse API



30
31
32

# File 'lib/langfuse/config.rb', line 30

def base_url
  @base_url
end

#batch_size ⇒ `Integer`

Returns Number of events to batch before sending.

Returns:

(Integer) —

Number of events to batch before sending



64
65
66

# File 'lib/langfuse/config.rb', line 64

def batch_size
  @batch_size
end

#cache_backend ⇒ `Symbol`

Returns Cache backend (:memory or :rails).

Returns:

(Symbol) —

Cache backend (:memory or :rails)



45
46
47

# File 'lib/langfuse/config.rb', line 45

def cache_backend
  @cache_backend
end

#cache_lock_timeout ⇒ `Integer`

Returns Lock timeout in seconds for distributed cache stampede protection.

Returns:

(Integer) —

Lock timeout in seconds for distributed cache stampede protection



48
49
50

# File 'lib/langfuse/config.rb', line 48

def cache_lock_timeout
  @cache_lock_timeout
end

#cache_max_size ⇒ `Integer`

Returns Maximum number of cached items.

Returns:

(Integer) —

Maximum number of cached items



42
43
44

# File 'lib/langfuse/config.rb', line 42

def cache_max_size
  @cache_max_size
end

#cache_refresh_threads ⇒ `Integer`

Returns Number of background threads for cache refresh.

Returns:

(Integer) —

Number of background threads for cache refresh



58
59
60

# File 'lib/langfuse/config.rb', line 58

def cache_refresh_threads
  @cache_refresh_threads
end

#cache_stale_ttl ⇒ `Integer`, `Symbol`

Returns Stale TTL in seconds (grace period for serving stale data, default: 0) Accepts :indefinite which is automatically normalized to 1000 years (31,536,000,000 seconds) for practical “never expire” behavior.

Returns:

(Integer, Symbol) —

Stale TTL in seconds (grace period for serving stale data, default: 0) Accepts :indefinite which is automatically normalized to 1000 years (31,536,000,000 seconds) for practical “never expire” behavior.



55
56
57

# File 'lib/langfuse/config.rb', line 55

def cache_stale_ttl
  @cache_stale_ttl
end

#cache_stale_while_revalidate ⇒ `Boolean`

Returns Enable stale-while-revalidate caching (requires cache_stale_ttl > 0 to activate).

Returns:

(Boolean) —

Enable stale-while-revalidate caching (requires cache_stale_ttl > 0 to activate)



51
52
53

# File 'lib/langfuse/config.rb', line 51

def cache_stale_while_revalidate
  @cache_stale_while_revalidate
end

#cache_ttl ⇒ `Integer`

Returns Cache TTL in seconds.

Returns:

(Integer) —

Cache TTL in seconds



39
40
41

# File 'lib/langfuse/config.rb', line 39

def cache_ttl
  @cache_ttl
end

#environment ⇒ `String`^?

Returns Default tracing environment applied to new traces/observations.

Returns:

(String, nil) —

Default tracing environment applied to new traces/observations



73
74
75

# File 'lib/langfuse/config.rb', line 73

def environment
  @environment
end

#flush_interval ⇒ `Integer`

Returns Interval in seconds to flush buffered events.

Returns:

(Integer) —

Interval in seconds to flush buffered events



67
68
69

# File 'lib/langfuse/config.rb', line 67

def flush_interval
  @flush_interval
end

#job_queue ⇒ `Symbol`

Returns ActiveJob queue name for async processing.

Returns:

(Symbol) —

ActiveJob queue name for async processing



70
71
72

# File 'lib/langfuse/config.rb', line 70

def job_queue
  @job_queue
end

#logger ⇒ `Logger`

Returns Logger instance for debugging.

Returns:

(Logger) —

Logger instance for debugging



36
37
38

# File 'lib/langfuse/config.rb', line 36

def logger
  @logger
end

#mask ⇒ `#call`^?

Returns Mask callable applied to input, output, and metadata before serialization. Receives ‘data:` keyword argument. nil disables masking.

Returns:

(#call, nil) —

Mask callable applied to input, output, and metadata before serialization. Receives ‘data:` keyword argument. nil disables masking.



86
87
88

# File 'lib/langfuse/config.rb', line 86

def mask
  @mask
end

#public_key ⇒ `String`^?

Returns Langfuse public API key.

Returns:

(String, nil) —

Langfuse public API key



24
25
26

# File 'lib/langfuse/config.rb', line 24

def public_key
  @public_key
end

#release ⇒ `String`^?

Returns Default release identifier applied to new traces/observations.

Returns:

(String, nil) —

Default release identifier applied to new traces/observations



76
77
78

# File 'lib/langfuse/config.rb', line 76

def release
  @release
end

#sample_rate ⇒ `Float`

Returns Trace sampling rate from 0.0 to 1.0.

Returns:

(Float) —

Trace sampling rate from 0.0 to 1.0



79
80
81

# File 'lib/langfuse/config.rb', line 79

def sample_rate
  @sample_rate
end

#secret_key ⇒ `String`^?

Returns Langfuse secret API key.

Returns:

(String, nil) —

Langfuse secret API key



27
28
29

# File 'lib/langfuse/config.rb', line 27

def secret_key
  @secret_key
end

#should_export_span ⇒ `#call`^?

Returns Callback that decides whether an ended span should export to Langfuse.

Returns:

(#call, nil) —

Callback that decides whether an ended span should export to Langfuse.



82
83
84

# File 'lib/langfuse/config.rb', line 82

def should_export_span
  @should_export_span
end

#timeout ⇒ `Integer`

Returns HTTP request timeout in seconds.

Returns:

(Integer) —

HTTP request timeout in seconds



33
34
35

# File 'lib/langfuse/config.rb', line 33

def timeout
  @timeout
end

#tracing_async ⇒ `Boolean`

Returns Use async processing for traces (requires ActiveJob).

Returns:

(Boolean) —

Use async processing for traces (requires ActiveJob)



61
62
63

# File 'lib/langfuse/config.rb', line 61

def tracing_async
  @tracing_async
end

Instance Method Details

#normalized_stale_ttl ⇒ `Integer`

Normalize stale_ttl value

Converts :indefinite to 1000 years in seconds for practical “never expire” behavior while keeping the value finite for calculations.

Examples:

config.cache_stale_ttl = 300
config.normalized_stale_ttl # => 300

config.cache_stale_ttl = :indefinite
config.normalized_stale_ttl # => 31536000000

Returns:

(Integer) —

Normalized stale TTL in seconds



211
212
213

# File 'lib/langfuse/config.rb', line 211

def normalized_stale_ttl
  cache_stale_ttl == :indefinite ? INDEFINITE_SECONDS : cache_stale_ttl
end

#validate! ⇒ `void`

This method returns an undefined value.

Validate the configuration

rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

Raises:

(ConfigurationError) —

if configuration is invalid

# File 'lib/langfuse/config.rb', line 176

def validate!
  raise ConfigurationError, "public_key is required" if public_key.nil? || public_key.empty?
  raise ConfigurationError, "secret_key is required" if secret_key.nil? || secret_key.empty?
  raise ConfigurationError, "base_url cannot be empty" if base_url.nil? || base_url.empty?
  raise ConfigurationError, "timeout must be positive" if timeout.nil? || timeout <= 0
  raise ConfigurationError, "cache_ttl must be non-negative" if cache_ttl.nil? || cache_ttl.negative?
  raise ConfigurationError, "cache_max_size must be positive" if cache_max_size.nil? || cache_max_size <= 0

  if cache_lock_timeout.nil? || cache_lock_timeout <= 0
    raise ConfigurationError,
          "cache_lock_timeout must be positive"
  end

  validate_swr_config!

  validate_cache_backend!
  validate_sample_rate!
  validate_should_export_span!
  validate_mask!
end

Class: Langfuse::Config

Overview

Examples:

Global configuration

Per-client configuration

Constant Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize {|config| ... } ⇒ Config

Instance Attribute Details

#base_url ⇒ String

#batch_size ⇒ Integer

#cache_backend ⇒ Symbol

#cache_lock_timeout ⇒ Integer

#cache_max_size ⇒ Integer

#cache_refresh_threads ⇒ Integer

#cache_stale_ttl ⇒ Integer, Symbol

#cache_stale_while_revalidate ⇒ Boolean

#cache_ttl ⇒ Integer

#environment ⇒ String?

#flush_interval ⇒ Integer

#job_queue ⇒ Symbol

#logger ⇒ Logger

#mask ⇒ #call?

#public_key ⇒ String?

#release ⇒ String?

#sample_rate ⇒ Float

#secret_key ⇒ String?

#should_export_span ⇒ #call?

#timeout ⇒ Integer

#tracing_async ⇒ Boolean

Instance Method Details

#normalized_stale_ttl ⇒ Integer

Examples:

#validate! ⇒ void

#initialize {|config| ... } ⇒ `Config`

#base_url ⇒ `String`

#batch_size ⇒ `Integer`

#cache_backend ⇒ `Symbol`

#cache_lock_timeout ⇒ `Integer`

#cache_max_size ⇒ `Integer`

#cache_refresh_threads ⇒ `Integer`

#cache_stale_ttl ⇒ `Integer`, `Symbol`

#cache_stale_while_revalidate ⇒ `Boolean`

#cache_ttl ⇒ `Integer`

#environment ⇒ `String`^?

#flush_interval ⇒ `Integer`

#job_queue ⇒ `Symbol`

#logger ⇒ `Logger`

#mask ⇒ `#call`^?

#public_key ⇒ `String`^?

#release ⇒ `String`^?

#sample_rate ⇒ `Float`

#secret_key ⇒ `String`^?

#should_export_span ⇒ `#call`^?

#timeout ⇒ `Integer`

#tracing_async ⇒ `Boolean`

#normalized_stale_ttl ⇒ `Integer`

#validate! ⇒ `void`