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_TRACING_ENABLED = Returns Default telemetry setting. Returns: (Boolean) — Default telemetry 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_SCORE_QUEUE_CAPACITY = Returns Default maximum number of queued asynchronous scores. Returns: (Integer) — Default maximum number of queued asynchronous scores

100_000

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

LOGGER_METHODS = Returns Methods required from a custom logger. Returns: (Array<Symbol>) — Methods required from a custom logger

%i[debug info warn error].freeze

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, :rails, or :auto).
#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 environment applied to traces, observations, and scores.
#flush_interval ⇒ Integer
Interval in seconds to flush buffered events.
#job_queue ⇒ Symbol
Reserved no-op queue name for future async job integration.
#logger ⇒ Logger
Logger instance for debugging.
#mask ⇒ #call^?
Mask callable applied to input, output, and metadata before serialization.
#mask_otel_spans ⇒ #call^?
Export-stage masking hook for spans exported to Langfuse.
#metrics_reporter ⇒ #add_to_counter, ...
Reporter for OpenTelemetry batch span processor metrics.
#prompt_cache_observer ⇒ #call^?
Observer called for prompt cache events.
#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.
#score_queue_capacity ⇒ Integer
Maximum number of asynchronous scores held in memory.
#secret_key ⇒ String^?
Langfuse secret API key.
#should_export_span ⇒ #call^?
Callback that decides whether a span should export to Langfuse.
#span_exporter ⇒ #export, ...
Span exporter used by Langfuse's internal tracer provider.
#timeout ⇒ Integer
HTTP request timeout in seconds.
#tracing_async ⇒ Boolean
Use OpenTelemetry batch scheduling for trace export.
#tracing_enabled ⇒ Boolean
Enable Langfuse tracing and scoring.

Instance Method Summary collapse

#initialize {|config| ... } ⇒ Config constructor
Initialize a new Config object.
#normalized_stale_ttl ⇒ Integer
Normalize stale_ttl value.
#telemetry_enabled? ⇒ Boolean
Check whether Langfuse tracing and scoring are enabled.
#trace_export_enabled? ⇒ Boolean
Check whether OpenTelemetry trace export is enabled.
#valid? ⇒ Boolean
Check whether the configuration can construct a client.
#validate! ⇒ void
Validate the configuration.
#validate_telemetry_disabled! ⇒ void private
Validate settings needed while telemetry is disabled.
#validate_tracing! ⇒ void private
Validate only settings consumed by tracing setup and export.

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 203

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)
  initialize_client_defaults
  initialize_tracing_defaults
  initialize_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



31
32
33

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

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



71
72
73

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

def batch_size
  @batch_size
end

#cache_backend ⇒ `Symbol`

Returns Cache backend (:memory, :rails, or :auto).

Returns:

(Symbol) —
Cache backend (:memory, :rails, or :auto)



46
47
48

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

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



49
50
51

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

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



43
44
45

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

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



59
60
61

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

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.



56
57
58

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

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)



52
53
54

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

def cache_stale_while_revalidate
  @cache_stale_while_revalidate
end

#cache_ttl ⇒ `Integer`

Returns Cache TTL in seconds.

Returns:

(Integer) —
Cache TTL in seconds



40
41
42

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

def cache_ttl
  @cache_ttl
end

#environment ⇒ `String`^?

Returns Default environment applied to traces, observations, and scores.

Returns:

(String, nil) —
Default environment applied to traces, observations, and scores



83
84
85

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

def environment
  @environment
end

#flush_interval ⇒ `Integer`

Returns Interval in seconds to flush buffered events.

Returns:

(Integer) —
Interval in seconds to flush buffered events



74
75
76

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

def flush_interval
  @flush_interval
end

#job_queue ⇒ `Symbol`

Returns Reserved no-op queue name for future async job integration.

Returns:

(Symbol) —
Reserved no-op queue name for future async job integration



80
81
82

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

def job_queue
  @job_queue
end

#logger ⇒ `Logger`

Returns Logger instance for debugging.

Returns:

(Logger) —
Logger instance for debugging



37
38
39

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

def logger
  @logger
end

#mask ⇒ `#call`^?

Returns Mask callable applied to input, output, and metadata before serialization. Receives data: keyword argument. nil disables masking. This is a creation-time hook for Langfuse-owned attributes; it never sees raw third-party span attributes. See #mask_otel_spans for those.

Returns:

(#call, nil) —
Mask callable applied to input, output, and metadata before serialization. Receives data: keyword argument. nil disables masking. This is a creation-time hook for Langfuse-owned attributes; it never sees raw third-party span attributes. See #mask_otel_spans for those.



99
100
101

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

def mask
  @mask
end

#mask_otel_spans ⇒ `#call`^?

Returns Export-stage masking hook for spans exported to Langfuse. Receives a params: keyword argument containing MaskOtelSpansParams. Its frozen spans Hash maps OtelSpanIdentifier keys to OtelSpanData snapshots for one export batch, including third-party spans. Returns nil to export the batch unchanged or MaskOtelSpansResult with sparse OtelSpanPatch values. Deletes run before sets. Only the copy exported to Langfuse is transformed — any other OpenTelemetry exporter receives the original, unmasked spans, so Langfuse masking does not protect other telemetry backends. The hook is synchronous and must not rely on request context, the current span, async work, or network calls. Exceptions and invalid results fail closed by dropping the Langfuse export batch.

Returns:

(#call, nil) —
Export-stage masking hook for spans exported to Langfuse. Receives a params: keyword argument containing MaskOtelSpansParams. Its frozen spans Hash maps OtelSpanIdentifier keys to OtelSpanData snapshots for one export batch, including third-party spans. Returns nil to export the batch unchanged or MaskOtelSpansResult with sparse OtelSpanPatch values. Deletes run before sets. Only the copy exported to Langfuse is transformed — any other OpenTelemetry exporter receives the original, unmasked spans, so Langfuse masking does not protect other telemetry backends. The hook is synchronous and must not rely on request context, the current span, async work, or network calls. Exceptions and invalid results fail closed by dropping the Langfuse export batch.



113
114
115

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

def mask_otel_spans
  @mask_otel_spans
end

#metrics_reporter ⇒ `#add_to_counter`, ...

Returns Reporter for OpenTelemetry batch span processor metrics. The reporter must be fast, thread-safe, and nonblocking. The application owns its lifecycle.

Returns:

(#add_to_counter, #record_value, #observe_value, nil) —
Reporter for OpenTelemetry batch span processor metrics. The reporter must be fast, thread-safe, and nonblocking. The application owns its lifecycle.



118
119
120

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

def metrics_reporter
  @metrics_reporter
end

#prompt_cache_observer ⇒ `#call`^?

Returns Observer called for prompt cache events.

Returns:

(#call, nil) —
Observer called for prompt cache events



62
63
64

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

def prompt_cache_observer
  @prompt_cache_observer
end

#public_key ⇒ `String`^?

Returns Langfuse public API key.

Returns:

(String, nil) —
Langfuse public API key



25
26
27

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

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



86
87
88

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

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



89
90
91

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

def sample_rate
  @sample_rate
end

#score_queue_capacity ⇒ `Integer`

Returns Maximum number of asynchronous scores held in memory.

Returns:

(Integer) —
Maximum number of asynchronous scores held in memory



77
78
79

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

def score_queue_capacity
  @score_queue_capacity
end

#secret_key ⇒ `String`^?

Returns Langfuse secret API key.

Returns:

(String, nil) —
Langfuse secret API key



28
29
30

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

def secret_key
  @secret_key
end

#should_export_span ⇒ `#call`^?

Returns Callback that decides whether a span should export to Langfuse. The span processor calls it once after each span finishes.

Returns:

(#call, nil) —
Callback that decides whether a span should export to Langfuse. The span processor calls it once after each span finishes.



93
94
95

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

def should_export_span
  @should_export_span
end

#span_exporter ⇒ `#export`, ...

Returns Span exporter used by Langfuse's internal tracer provider. The provider owns the exporter lifecycle after tracing starts. nil selects the default OTLP exporter.

Returns:

(#export, #force_flush, #shutdown, nil) —
Span exporter used by Langfuse's internal tracer provider. The provider owns the exporter lifecycle after tracing starts. nil selects the default OTLP exporter.



123
124
125

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

def span_exporter
  @span_exporter
end

#timeout ⇒ `Integer`

Returns HTTP request timeout in seconds.

Returns:

(Integer) —
HTTP request timeout in seconds



34
35
36

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

def timeout
  @timeout
end

#tracing_async ⇒ `Boolean`

Returns Use OpenTelemetry batch scheduling for trace export.

Returns:

(Boolean) —
Use OpenTelemetry batch scheduling for trace export



65
66
67

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

def tracing_async
  @tracing_async
end

#tracing_enabled ⇒ `Boolean`

Returns Enable Langfuse tracing and scoring.

Returns:

(Boolean) —
Enable Langfuse tracing and scoring



68
69
70

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

def tracing_enabled
  @tracing_enabled
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



303
304
305

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

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

#telemetry_enabled? ⇒ `Boolean`

Check whether Langfuse tracing and scoring are enabled.

Returns:

(Boolean) —
true when Langfuse telemetry is enabled



279
280
281

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

def telemetry_enabled?
  tracing_enabled == true
end

#trace_export_enabled? ⇒ `Boolean`

Check whether OpenTelemetry trace export is enabled.

Returns:

(Boolean) —
true when Langfuse tracing is enabled and the OpenTelemetry SDK is active



286
287
288

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

def trace_export_enabled?
  telemetry_enabled? && !@otel_sdk_disabled
end

#valid? ⇒ `Boolean`

Check whether the configuration can construct a client.

This check is local. It does not validate credentials or network access.

Returns:

(Boolean) —
true when #validate! succeeds

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

def valid?
  validate!
  true
rescue ConfigurationError
  false
end

#validate! ⇒ `void`

This method returns an undefined value.

Validate the configuration

Raises:

(ConfigurationError) —
if configuration is invalid

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

def validate!
  validate_tracing_enabled!
  validate_connection_settings!
  validate_batching_settings!
  validate_sample_rate!
  validate_client_settings!
  validate_callable!(prompt_cache_observer, "prompt_cache_observer")
  validate_logger!
end

#validate_telemetry_disabled! ⇒ `void`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validate settings needed while telemetry is disabled.

Raises:

(ConfigurationError) —
if disabled-client configuration is invalid

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

def validate_telemetry_disabled!
  validate_tracing_enabled!
  validate_logger!
end

#validate_tracing! ⇒ `void`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validate only settings consumed by tracing setup and export.

Raises:

(ConfigurationError) —
if tracing configuration is invalid

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

def validate_tracing!
  validate_tracing_enabled!
  validate_connection_settings!
  validate_batching_settings!
  validate_sample_rate!
  validate_callable!(should_export_span, "should_export_span")
  validate_callable!(mask, "mask")
  validate_callable!(mask_otel_spans, "mask_otel_spans")
  validate_metrics_reporter!
  validate_span_exporter!
  validate_logger!
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?

#mask_otel_spans ⇒ #call?

#metrics_reporter ⇒ #add_to_counter, ...

#prompt_cache_observer ⇒ #call?

#public_key ⇒ String?

#release ⇒ String?

#sample_rate ⇒ Float

#score_queue_capacity ⇒ Integer

#secret_key ⇒ String?

#should_export_span ⇒ #call?

#span_exporter ⇒ #export, ...

#timeout ⇒ Integer

#tracing_async ⇒ Boolean

#tracing_enabled ⇒ Boolean

Instance Method Details

#normalized_stale_ttl ⇒ Integer

Examples:

#telemetry_enabled? ⇒ Boolean

#trace_export_enabled? ⇒ Boolean

#valid? ⇒ Boolean

#validate! ⇒ void

#validate_telemetry_disabled! ⇒ void

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

#mask_otel_spans ⇒ `#call`^?

#metrics_reporter ⇒ `#add_to_counter`, ...

#prompt_cache_observer ⇒ `#call`^?

#public_key ⇒ `String`^?

#release ⇒ `String`^?

#sample_rate ⇒ `Float`

#score_queue_capacity ⇒ `Integer`

#secret_key ⇒ `String`^?

#should_export_span ⇒ `#call`^?

#span_exporter ⇒ `#export`, ...

#timeout ⇒ `Integer`

#tracing_async ⇒ `Boolean`

#tracing_enabled ⇒ `Boolean`

#normalized_stale_ttl ⇒ `Integer`

#telemetry_enabled? ⇒ `Boolean`

#trace_export_enabled? ⇒ `Boolean`

#valid? ⇒ `Boolean`

#validate! ⇒ `void`

#validate_telemetry_disabled! ⇒ `void`

#validate_tracing! ⇒ `void`