Class: Langfuse::Config

Inherits:

Object

Object
Langfuse::Config

show all

Defined in:: lib/langfuse/config.rb

Overview

Configuration object for Langfuse client

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

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.
#secret_key ⇒ String^?

Langfuse secret API key.
#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

rubocop:disable Metrics/AbcSize

Yields:

(config) —

Optional block for configuration

Yield Parameters:

config (Config) —

The config instance

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

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
  @environment = env_value("LANGFUSE_TRACING_ENVIRONMENT")
  @release = env_value("LANGFUSE_RELEASE") || detect_release_from_ci_env
  @mask = nil
  @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



29
30
31

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

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



63
64
65

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

def batch_size
  @batch_size
end

#cache_backend ⇒ `Symbol`

Returns Cache backend (:memory or :rails).

Returns:

(Symbol) —

Cache backend (:memory or :rails)



44
45
46

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

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



47
48
49

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

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



41
42
43

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

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



57
58
59

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

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.



54
55
56

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

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)



50
51
52

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

def cache_stale_while_revalidate
  @cache_stale_while_revalidate
end

#cache_ttl ⇒ `Integer`

Returns Cache TTL in seconds.

Returns:

(Integer) —

Cache TTL in seconds



38
39
40

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

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



72
73
74

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

def environment
  @environment
end

#flush_interval ⇒ `Integer`

Returns Interval in seconds to flush buffered events.

Returns:

(Integer) —

Interval in seconds to flush buffered events



66
67
68

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

def flush_interval
  @flush_interval
end

#job_queue ⇒ `Symbol`

Returns ActiveJob queue name for async processing.

Returns:

(Symbol) —

ActiveJob queue name for async processing



69
70
71

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

def job_queue
  @job_queue
end

#logger ⇒ `Logger`

Returns Logger instance for debugging.

Returns:

(Logger) —

Logger instance for debugging



35
36
37

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

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.



79
80
81

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

def mask
  @mask
end

#public_key ⇒ `String`^?

Returns Langfuse public API key.

Returns:

(String, nil) —

Langfuse public API key



23
24
25

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

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



75
76
77

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

def release
  @release
end

#secret_key ⇒ `String`^?

Returns Langfuse secret API key.

Returns:

(String, nil) —

Langfuse secret API key



26
27
28

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

def secret_key
  @secret_key
end

#timeout ⇒ `Integer`

Returns HTTP request timeout in seconds.

Returns:

(Integer) —

HTTP request timeout in seconds



32
33
34

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

def timeout
  @timeout
end

#tracing_async ⇒ `Boolean`

Returns Use async processing for traces (requires ActiveJob).

Returns:

(Boolean) —

Use async processing for traces (requires ActiveJob)



60
61
62

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

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



204
205
206

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

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 170

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_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?

#secret_key ⇒ String?

#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`^?

#secret_key ⇒ `String`^?

#timeout ⇒ `Integer`

#tracing_async ⇒ `Boolean`

#normalized_stale_ttl ⇒ `Integer`

#validate! ⇒ `void`