Class: Langfuse::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/langfuse/client.rb

Overview

Main client for Langfuse SDK

Provides a unified interface for interacting with the Langfuse API. Handles prompt fetching and returns the appropriate prompt client (TextPromptClient or ChatPromptClient) based on the prompt type.

rubocop:disable Metrics/ClassLength

Examples:

config = Langfuse::Config.new(
  public_key: "pk_...",
  secret_key: "sk_...",
  cache_ttl: 120
)
client = Langfuse::Client.new(config)
prompt = client.get_prompt("greeting")
compiled = prompt.compile(name: "Alice")

Constant Summary collapse

DATASET_ITEMS_PAGE_SIZE =

Returns Default page size when fetching all dataset items.

Returns:

  • (Integer) —

    Default page size when fetching all dataset items

50

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ Client

Initialize a new Langfuse client

Parameters:

  • config (Config) —

    Configuration object



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/langfuse/client.rb', line 35

def initialize(config)
  @config = config
  @config.validate!

  # Create cache if enabled
  cache = create_cache if cache_enabled?

  # Create API client with cache
  @api_client = ApiClient.new(
    public_key: config.public_key,
    secret_key: config.secret_key,
    base_url: config.base_url,
    timeout: config.timeout,
    logger: config.logger,
    cache: cache
  )

  @project_id = nil
  # One-shot lookup: avoids repeated blocking API calls in URL helpers
  # (trace_url, dataset_url, dataset_run_url) when the project endpoint is down.
  @project_id_fetched = false

  # Initialize score client for batching score events
  @score_client = ScoreClient.new(api_client: @api_client, config: config)
end

Instance Attribute Details

#api_client ⇒ ApiClient (readonly)

Returns The underlying API client.

Returns:



29
30
31
 
# File 'lib/langfuse/client.rb', line 29

def api_client
  @api_client
end

#config ⇒ Config (readonly)

Returns The client configuration.

Returns:

  • (Config) —

    The client configuration



26
27
28
 
# File 'lib/langfuse/client.rb', line 26

def config
  @config
end

Instance Method Details

#compile_prompt(name, variables: {}, version: nil, label: nil, fallback: nil, type: nil) ⇒ String, Array<Hash>

Convenience method: fetch and compile a prompt in one call

This is a shorthand for calling get_prompt followed by compile. Returns the compiled prompt ready to use with your LLM.

Examples:

Compile a text prompt

text = client.compile_prompt("greeting", variables: { name: "Alice" })
# => "Hello Alice!"

Compile a chat prompt

messages = client.compile_prompt("support-bot", variables: { company: "Acme" })
# => [{ role: :system, content: "You are a support agent for Acme" }]

With fallback

text = client.compile_prompt(
  "greeting",
  variables: { name: "Alice" },
  fallback: "Hello {{name}}!",
  type: :text
)

Parameters:

  • name (String) —

    The name of the prompt

  • variables (Hash) (defaults to: {}) —

    Variables to substitute in the prompt

  • version (Integer, nil) (defaults to: nil) —

    Optional specific version number

  • label (String, nil) (defaults to: nil) —

    Optional label (e.g., “production”, “latest”)

  • fallback (String, Array, nil) (defaults to: nil) —

    Optional fallback prompt to use on error

  • type (Symbol, nil) (defaults to: nil) —

    Required when fallback is provided (:text or :chat)

Returns:

  • (String, Array<Hash>) —

    Compiled prompt (String for text, Array for chat)

Raises:

  • (ArgumentError) —

    if both version and label are provided

  • (ArgumentError) —

    if fallback is provided without type

  • (NotFoundError) —

    if the prompt is not found and no fallback provided

  • (UnauthorizedError) —

    if authentication fails and no fallback provided

  • (ApiError) —

    for other API errors and no fallback provided



151
152
153
154
 
# File 'lib/langfuse/client.rb', line 151

def compile_prompt(name, variables: {}, version: nil, label: nil, fallback: nil, type: nil)
  prompt = get_prompt(name, version: version, label: label, fallback: fallback, type: type)
  prompt.compile(**variables)
end

#create_dataset(name:, description: nil, metadata: nil) ⇒ DatasetClient

Create a new dataset

Examples:

dataset = client.create_dataset(name: "my-dataset", description: "QA evaluation set")

Parameters:

  • name (String) —

    Dataset name (required)

  • description (String, nil) (defaults to: nil) —

    Optional description

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

Returns:

Raises:



414
415
416
417
 
# File 'lib/langfuse/client.rb', line 414

def create_dataset(name:, description: nil, metadata: nil)
  data = api_client.create_dataset(name: name, description: description, metadata: metadata)
  DatasetClient.new(data, client: self)
end

#create_dataset_item(dataset_name:, input: nil, expected_output: nil, metadata: nil, id: nil, source_trace_id: nil, source_observation_id: nil, status: nil) ⇒ DatasetItemClient

Create a new dataset item

rubocop:disable Metrics/ParameterLists

Examples:

item = client.create_dataset_item(
  dataset_name: "my-dataset",
  input: { query: "What is Ruby?" },
  expected_output: { answer: "A programming language" }
)

Parameters:

  • dataset_name (String) —

    Name of the dataset to add item to (required)

  • input (Object, nil) (defaults to: nil) —

    Input data for the item

  • expected_output (Object, nil) (defaults to: nil) —

    Expected output for evaluation

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

  • id (String, nil) (defaults to: nil) —

    Optional ID for upsert behavior

  • source_trace_id (String, nil) (defaults to: nil) —

    Link to source trace

  • source_observation_id (String, nil) (defaults to: nil) —

    Link to source observation

  • status (Symbol, nil) (defaults to: nil) —

    Item status (:active or :archived)

Returns:

Raises:



498
499
500
501
502
503
504
505
506
507
 
# File 'lib/langfuse/client.rb', line 498

def create_dataset_item(dataset_name:, input: nil, expected_output: nil,
                        metadata: nil, id: nil, source_trace_id: nil,
                        source_observation_id: nil, status: nil)
  data = api_client.create_dataset_item(
    dataset_name: dataset_name, input: input, expected_output: expected_output,
    metadata: metadata, id: id, source_trace_id: source_trace_id,
    source_observation_id: source_observation_id, status: status
  )
  DatasetItemClient.new(data, client: self)
end

#create_dataset_run_item(dataset_item_id:, run_name:, trace_id: nil, observation_id: nil, metadata: nil, run_description: nil) ⇒ Hash

Create a dataset run item (link a trace to a dataset item)

Parameters:

  • dataset_item_id (String) —

    Dataset item ID (required)

  • run_name (String) —

    Run name (required)

  • trace_id (String, nil) (defaults to: nil) —

    Trace ID

  • observation_id (String, nil) (defaults to: nil) —

    Observation ID

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

  • run_description (String, nil) (defaults to: nil) —

    Optional run description

Returns:

  • (Hash) —

    The created dataset run item data



579
580
581
582
583
584
585
586
587
588
589
 
# File 'lib/langfuse/client.rb', line 579

def create_dataset_run_item(dataset_item_id:, run_name:, trace_id: nil,
                            observation_id: nil, metadata: nil, run_description: nil)
  api_client.create_dataset_run_item(
    dataset_item_id: dataset_item_id,
    run_name: run_name,
    trace_id: trace_id,
    observation_id: observation_id,
    metadata: metadata,
    run_description: run_description
  )
end

#create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil) ⇒ TextPromptClient, ChatPromptClient

Create a new prompt (or new version if name already exists)

Creates a new prompt in Langfuse. If a prompt with the same name already exists, this creates a new version of that prompt.

rubocop:disable Metrics/ParameterLists

Examples:

Create a text prompt

prompt = client.create_prompt(
  name: "greeting",
  prompt: "Hello {{name}}!",
  type: :text,
  labels: ["production"],
  config: { model: "gpt-4o", temperature: 0.7 }
)

Create a chat prompt

prompt = client.create_prompt(
  name: "support-bot",
  prompt: [
    { role: "system", content: "You are a {{role}} assistant" },
    { role: "user", content: "{{question}}" }
  ],
  type: :chat,
  labels: ["staging"]
)

Parameters:

  • name (String) —

    The prompt name (required)

  • prompt (String, Array<Hash>) —

    The prompt content (required)

    • For text prompts: a string with {variable} placeholders

    • For chat prompts: array of message hashes with role and content

  • type (Symbol) —

    Prompt type (:text or :chat) (required)

  • config (Hash) (defaults to: {}) —

    Optional configuration (model parameters, tools, etc.)

  • labels (Array<String>) (defaults to: []) —

    Optional labels (e.g., [“production”])

  • tags (Array<String>) (defaults to: []) —

    Optional tags for categorization

  • commit_message (String, nil) (defaults to: nil) —

    Optional commit message

Returns:

Raises:

  • (ArgumentError) —

    if required parameters are missing or invalid

  • (UnauthorizedError) —

    if authentication fails

  • (ApiError) —

    for other API errors



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/langfuse/client.rb', line 195

def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
  validate_prompt_type!(type)
  validate_prompt_content!(prompt, type)

  prompt_data = api_client.create_prompt(
    name: name,
    prompt: normalize_prompt_content(prompt, type),
    type: type.to_s,
    config: config,
    labels: labels,
    tags: tags,
    commit_message: commit_message
  )

  build_prompt_client(prompt_data)
end

#create_score(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) ⇒ void

This method returns an undefined value.

Create a score event and queue it for batching

rubocop:disable Metrics/ParameterLists

Examples:

Numeric score

client.create_score(name: "quality", value: 0.85, trace_id: "abc123")

Boolean score

client.create_score(name: "passed", value: true, trace_id: "abc123", data_type: :boolean)

Categorical score

client.create_score(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value (type depends on data_type)

  • id (String, nil) (defaults to: nil) —

    Score ID

  • trace_id (String, nil) (defaults to: nil) —

    Trace ID to associate with the score

  • session_id (String, nil) (defaults to: nil) —

    Session ID to associate with the score

  • observation_id (String, nil) (defaults to: nil) —

    Observation ID to associate with the score

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • environment (String, nil) (defaults to: nil) —

    Optional environment

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical)

  • dataset_run_id (String, nil) (defaults to: nil) —

    Optional dataset run ID to associate with the score

  • config_id (String, nil) (defaults to: nil) —

    Optional score config ID

Raises:

  • (ArgumentError) —

    if validation fails



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/langfuse/client.rb', line 310

def create_score(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)
  @score_client.create(
    name: name,
    value: 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,
    dataset_run_id: dataset_run_id,
    config_id: config_id
  )
end

#dataset_run_url(dataset_id:, dataset_run_id:) ⇒ String?

Generate URL for viewing a dataset run in Langfuse UI

Parameters:

  • dataset_id (String) —

    The dataset ID

  • dataset_run_id (String) —

    The dataset run ID

Returns:

  • (String, nil) —

    URL to view the dataset run, or nil if project ID unavailable



280
281
282
 
# File 'lib/langfuse/client.rb', line 280

def dataset_run_url(dataset_id:, dataset_run_id:)
  project_url("datasets/#{dataset_id}/runs/#{dataset_run_id}")
end

#dataset_url(dataset_id) ⇒ String?

Generate URL for viewing a dataset in Langfuse UI

Parameters:

  • dataset_id (String) —

    The dataset ID

Returns:

  • (String, nil) —

    URL to view the dataset, or nil if project ID unavailable



271
272
273
 
# File 'lib/langfuse/client.rb', line 271

def dataset_url(dataset_id)
  project_url("datasets/#{dataset_id}")
end

#delete_dataset_item(id) ⇒ nil

Note:

404 responses are treated as success to keep DELETE idempotent across retries

Delete a dataset item by ID

Examples:

client.delete_dataset_item("item-uuid-123")

Parameters:

  • id (String) —

    Dataset item ID

Returns:

  • (nil)

Raises:



565
566
567
568
 
# File 'lib/langfuse/client.rb', line 565

def delete_dataset_item(id)
  api_client.delete_dataset_item(id)
  nil
end

#flush_scores ⇒ void

This method returns an undefined value.

Force flush all queued score events

Sends all queued score events to the API immediately.

Examples:

client.flush_scores


389
390
391
 
# File 'lib/langfuse/client.rb', line 389

def flush_scores
  @score_client.flush
end

#get_dataset(name) ⇒ DatasetClient

Fetch a dataset by name

Examples:

dataset = client.get_dataset("my-dataset")

Parameters:

  • name (String) —

    Dataset name (supports folder paths like “evaluation/qa-dataset”)

Returns:

Raises:



429
430
431
432
 
# File 'lib/langfuse/client.rb', line 429

def get_dataset(name)
  data = api_client.get_dataset(name)
  DatasetClient.new(data, client: self)
end

#get_dataset_item(id) ⇒ DatasetItemClient

Fetch a dataset item by ID

Examples:

item = client.get_dataset_item("item-uuid-123")

Parameters:

  • id (String) —

    Dataset item ID

Returns:

Raises:



520
521
522
523
 
# File 'lib/langfuse/client.rb', line 520

def get_dataset_item(id)
  data = api_client.get_dataset_item(id)
  DatasetItemClient.new(data, client: self)
end

#get_prompt(name, version: nil, label: nil, fallback: nil, type: nil) ⇒ TextPromptClient, ChatPromptClient

Fetch a prompt and return the appropriate client

Fetches the prompt from the Langfuse API and returns either a TextPromptClient or ChatPromptClient based on the prompt type.

Examples:

With fallback for graceful degradation

prompt = client.get_prompt("greeting", fallback: "Hello {{name}}!", type: :text)

Parameters:

  • name (String) —

    The name of the prompt

  • version (Integer, nil) (defaults to: nil) —

    Optional specific version number

  • label (String, nil) (defaults to: nil) —

    Optional label (e.g., “production”, “latest”)

  • fallback (String, Array, nil) (defaults to: nil) —

    Optional fallback prompt to use on error

  • type (Symbol, nil) (defaults to: nil) —

    Required when fallback is provided (:text or :chat)

Returns:

Raises:

  • (ArgumentError) —

    if both version and label are provided

  • (ArgumentError) —

    if fallback is provided without type

  • (NotFoundError) —

    if the prompt is not found and no fallback provided

  • (UnauthorizedError) —

    if authentication fails and no fallback provided

  • (ApiError) —

    for other API errors and no fallback provided



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/langfuse/client.rb', line 80

def get_prompt(name, version: nil, label: nil, fallback: nil, type: nil)
  # Validate fallback usage
  if fallback && !type
    raise ArgumentError, "type parameter is required when fallback is provided (use :text or :chat)"
  end

  # Try to fetch from API
  prompt_data = api_client.get_prompt(name, version: version, label: label)
  build_prompt_client(prompt_data)
rescue ApiError, NotFoundError, UnauthorizedError => e
  # If no fallback, re-raise the error
  raise e unless fallback

  # Log warning and return fallback
  config.logger.warn("Langfuse API error for prompt '#{name}': #{e.message}. Using fallback.")
  build_fallback_prompt_client(name, fallback, type)
end

#get_trace(id) ⇒ Hash

Fetch a trace by ID

Examples:

trace = client.get_trace("trace-uuid-123")

Parameters:

  • id (String) —

    Trace ID

Returns:

  • (Hash) —

    The trace data

Raises:



473
474
475
 
# File 'lib/langfuse/client.rb', line 473

def get_trace(id)
  api_client.get_trace(id)
end

#list_dataset_items(dataset_name:, page: nil, limit: nil, source_trace_id: nil, source_observation_id: nil) ⇒ Array<DatasetItemClient>

List items in a dataset

When page is nil (default), auto-paginates to fetch all items. When page is provided, returns only that single page.

Examples:

items = client.list_dataset_items(dataset_name: "my-dataset", limit: 50)

Parameters:

  • dataset_name (String) —

    Name of the dataset (required)

  • page (Integer, nil) (defaults to: nil) —

    Optional page number for pagination

  • limit (Integer, nil) (defaults to: nil) —

    Optional limit per page

  • source_trace_id (String, nil) (defaults to: nil) —

    Filter by source trace ID

  • source_observation_id (String, nil) (defaults to: nil) —

    Filter by source observation ID

Returns:

Raises:



541
542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/langfuse/client.rb', line 541

def list_dataset_items(dataset_name:, page: nil, limit: nil,
                       source_trace_id: nil, source_observation_id: nil)
  filters = { dataset_name: dataset_name, source_trace_id: source_trace_id,
              source_observation_id: source_observation_id }

  items = if page
            fetch_dataset_items_page(page: page, limit: limit, **filters)
          else
            fetch_all_dataset_items(limit: limit, **filters)
          end

  items.map { |data| DatasetItemClient.new(data, client: self) }
end

#list_datasets(page: nil, limit: nil) ⇒ Array<Hash>

List all datasets in the project

Examples:

datasets = client.list_datasets(page: 1, limit: 10)

Parameters:

  • page (Integer, nil) (defaults to: nil) —

    Optional page number for pagination

  • limit (Integer, nil) (defaults to: nil) —

    Optional limit per page

Returns:

  • (Array<Hash>) —

    Array of dataset metadata hashes

Raises:



444
445
446
 
# File 'lib/langfuse/client.rb', line 444

def list_datasets(page: nil, limit: nil)
  api_client.list_datasets(page: page, limit: limit)
end

#list_prompts(page: nil, limit: nil) ⇒ Array<Hash>

List all prompts in the Langfuse project

Fetches a list of all prompt names available in your project. Returns metadata only, not full prompt content.

Examples:

prompts = client.list_prompts
prompts.each do |prompt|
  puts "#{prompt['name']} (v#{prompt['version']})"
end

Parameters:

  • page (Integer, nil) (defaults to: nil) —

    Optional page number for pagination

  • limit (Integer, nil) (defaults to: nil) —

    Optional limit per page

Returns:

  • (Array<Hash>) —

    Array of prompt metadata hashes

Raises:



114
115
116
 
# File 'lib/langfuse/client.rb', line 114

def list_prompts(page: nil, limit: nil)
  api_client.list_prompts(page: page, limit: limit)
end

#list_traces(page: nil, limit: nil, **filters) ⇒ Array<Hash>

List traces in the project

Examples:

traces = client.list_traces(page: 1, limit: 10, name: "my-trace")

Parameters:

  • page (Integer, nil) (defaults to: nil) —

    Optional page number for pagination

  • limit (Integer, nil) (defaults to: nil) —

    Optional limit per page

  • filters (Hash) —

    Additional filters (user_id, name, session_id, etc.)

Returns:

  • (Array<Hash>) —

    Array of trace hashes

Raises:



459
460
461
 
# File 'lib/langfuse/client.rb', line 459

def list_traces(page: nil, limit: nil, **filters)
  api_client.list_traces(page: page, limit: limit, **filters)
end

#project_id ⇒ String?

Lazily-fetched project ID for URL generation

Fetches the project ID from the API on first access and caches it. Returns nil if the API call fails (URL generation is non-critical).

Returns:

  • (String, nil) —

    The Langfuse project ID



249
250
251
252
253
 
# File 'lib/langfuse/client.rb', line 249

def project_id
  return @project_id if @project_id_fetched

  fetch_project_id
end

#run_experiment(name:, task:, data: nil, dataset_name: nil, description: nil, evaluators: [], run_evaluators: [], metadata: nil, run_name: nil) ⇒ ExperimentResult

Run an experiment against local data or a named dataset

rubocop:disable Metrics/ParameterLists

Parameters:

  • name (String) —

    Experiment/run name (required)

  • data (Array<Hash, DatasetItemClient>, nil) (defaults to: nil) —

    Local data items (each Hash with :input/:expected_output or “input”/“expected_output”; also accepts DatasetItemClient objects, e.g. when called from DatasetClient#run_experiment)

  • dataset_name (String, nil) (defaults to: nil) —

    Dataset name to fetch items from

  • task (Proc) —

    Callable receiving a single argument (the item). The item is a DatasetItemClient (when using dataset_name:) or ExperimentItem (when using data:). Tracing is handled automatically; use DatasetItemClient#run for direct span access.

  • description (String, nil) (defaults to: nil) —

    Optional run description

  • evaluators (Array<Proc>) (defaults to: []) —

    Item-level evaluators

  • run_evaluators (Array<Proc>) (defaults to: []) —

    Run-level evaluators

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

  • run_name (String, nil) (defaults to: nil) —

    Explicit run name (defaults to “name - timestamp”)

Returns:

Raises:

  • (ArgumentError) 


609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
 
# File 'lib/langfuse/client.rb', line 609

def run_experiment(name:, task:, data: nil, dataset_name: nil, description: nil,
                   evaluators: [], run_evaluators: [], metadata: nil, run_name: nil)
  raise ArgumentError, "Provide either data: or dataset_name:, not both" if data && dataset_name
  raise ArgumentError, "Provide data: or dataset_name:" unless data || dataset_name

  items = resolve_experiment_items(data, dataset_name)

  ExperimentRunner.new(
    client: self,
    name: name,
    items: items,
    task: task,
    evaluators: evaluators,
    run_evaluators: run_evaluators,
    metadata: metadata,
    description: description,
    run_name: run_name
  ).execute
end

#score_active_observation(name:, value:, comment: nil, metadata: nil, data_type: :numeric) ⇒ void

This method returns an undefined value.

Create a score for the currently active observation (from OTel span)

Extracts observation_id and trace_id from the active OpenTelemetry span.

Examples:

Langfuse.observe("operation") do |obs|
  client.score_active_observation(name: "accuracy", value: 0.92)
end

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical)

Raises:

  • (ArgumentError) —

    if no active span or validation fails



345
346
347
348
349
350
351
352
353
 
# File 'lib/langfuse/client.rb', line 345

def score_active_observation(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
  @score_client.score_active_observation(
    name: name,
    value: value,
    comment: comment,
    metadata: metadata,
    data_type: data_type
  )
end

#score_active_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric) ⇒ void

This method returns an undefined value.

Create a score for the currently active trace (from OTel span)

Extracts trace_id from the active OpenTelemetry span.

Examples:

Langfuse.observe("operation") do |obs|
  client.score_active_trace(name: "overall_quality", value: 5)
end

Parameters:

  • name (String) —

    Score name (required)

  • value (Numeric, Integer, String) —

    Score value

  • comment (String, nil) (defaults to: nil) —

    Optional comment

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata hash

  • data_type (Symbol) (defaults to: :numeric) —

    Data type (:numeric, :boolean, :categorical)

Raises:

  • (ArgumentError) —

    if no active span or validation fails



371
372
373
374
375
376
377
378
379
 
# File 'lib/langfuse/client.rb', line 371

def score_active_trace(name:, value:, comment: nil, metadata: nil, data_type: :numeric)
  @score_client.score_active_trace(
    name: name,
    value: value,
    comment: comment,
    metadata: metadata,
    data_type: data_type
  )
end

#shutdown ⇒ void

This method returns an undefined value.

Shutdown the client and flush any pending scores

Also shuts down the cache if it supports shutdown (e.g., SWR thread pool).



398
399
400
401
 
# File 'lib/langfuse/client.rb', line 398

def shutdown
  @score_client.shutdown
  @api_client.shutdown
end

#trace_url(trace_id) ⇒ String?

Generate URL for viewing a trace in Langfuse UI

Examples:

url = client.trace_url("abc123...")
puts "View trace at: #{url}"

Parameters:

  • trace_id (String) —

    The trace ID (hex-encoded, 32 characters)

Returns:

  • (String, nil) —

    URL to view the trace, or nil if project ID unavailable



263
264
265
 
# File 'lib/langfuse/client.rb', line 263

def trace_url(trace_id)
  project_url("traces/#{trace_id}")
end

#update_prompt(name:, version:, labels:) ⇒ TextPromptClient, ChatPromptClient

Update an existing prompt version’s metadata

Updates the labels of an existing prompt version. Note: The prompt content itself cannot be changed after creation.

Examples:

Update labels to promote to production

prompt = client.update_prompt(
  name: "greeting",
  version: 2,
  labels: ["production"]
)

Parameters:

  • name (String) —

    The prompt name (required)

  • version (Integer) —

    The version number to update (required)

  • labels (Array<String>) —

    New labels (replaces existing). Required.

Returns:

Raises:



233
234
235
236
237
238
239
240
241
 
# File 'lib/langfuse/client.rb', line 233

def update_prompt(name:, version:, labels:)
  prompt_data = api_client.update_prompt(
    name: name,
    version: version,
    labels: labels
  )

  build_prompt_client(prompt_data)
end