Implementation:Langfuse Langfuse ObservationsTable Definition

Knowledge Sources	Langfuse
Domains	Observations, UI
Last Updated	2026-02-14 00:00 GMT

Overview

Defines the column definitions and options types for the observations table, used for both server-side query construction and client-side filter building in the Langfuse UI.

Description

This module provides the canonical list of columns (observationsTableCols) that describe the observations table as presented in the Langfuse web interface. Each column definition includes a display name, a programmatic ID, a filter type (e.g., stringOptions, number, datetime, stringObject), an internal SQL expression for query construction, nullability, and optional runtime-populated filter options.

The columns cover:

• Identity: ID, Name, Type, Trace ID, Parent Observation ID
• Trace context: Trace Name, User ID, Environment
• Timing: Start Time, End Time, Time To First Token, Latency
• Cost: Input Cost, Output Cost, Total Cost
• Quality: Level (DEBUG/DEFAULT/WARNING/ERROR), Status Message
• Model: Model name, Model ID, Input/Output/Total Tokens, Tokens per second
• Metadata: Metadata (key-value), Version
• Scores: Numeric scores (avg), Categorical scores
• Prompt: Prompt Name, Prompt Version
• Tags: Trace Tags
• Comments: Comment Count, Comment Content
• Tools: Available Tool Names, Called Tool Names, Available Tools count, Tool Calls count

The ObservationOptions type defines which columns accept runtime option values (populated from the database at query time). The observationsTableColsWithOptions function merges these runtime options into the column definitions for use in the client-side filter builder.

Usage

Use observationsTableCols server-side when constructing SQL queries against the observations table. Use observationsTableColsWithOptions client-side to provide the filter builder UI with populated dropdown options for filterable columns.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/observationsTable.ts
• Lines: 1-333

Signature

export const observationsTableCols: ColumnDefinition[];

export type ObservationOptions = {
  model: Array<SingleValueOption>;
  modelId: Array<SingleValueOption>;
  name: Array<SingleValueOption>;
  traceName: Array<SingleValueOption>;
  environment: Array<SingleValueOption>;
  scores_avg: Array<string>;
  score_categories: Array<MultiValueOption>;
  promptName: Array<SingleValueOption>;
  tags: Array<SingleValueOption>;
  type: Array<SingleValueOption>;
  toolNames: Array<SingleValueOption>;
  calledToolNames: Array<SingleValueOption>;
};

export function observationsTableColsWithOptions(
  options?: ObservationOptions,
): ColumnDefinition[];

Import

import {
  observationsTableCols,
  observationsTableColsWithOptions,
  type ObservationOptions,
} from "@langfuse/shared";

I/O Contract

Inputs

Name	Type	Required	Description
options	ObservationOptions	No	Runtime-populated filter options for dropdown columns (model names, trace names, environments, etc.)

Outputs

Name	Type	Description
ColumnDefinition[]	array	Array of column definitions with display names, IDs, types, internal SQL expressions, and populated options for use in table rendering and filter building

Usage Examples

import {
  observationsTableColsWithOptions,
  type ObservationOptions,
} from "@langfuse/shared";

// Populate filter options from database query results
const options: ObservationOptions = {
  model: [{ value: "gpt-4" }, { value: "gpt-3.5-turbo" }],
  modelId: [{ value: "model-abc123" }],
  name: [{ value: "chat-completion" }, { value: "embedding" }],
  traceName: [{ value: "main-trace" }],
  environment: [{ value: "production" }, { value: "staging" }],
  scores_avg: ["accuracy", "relevance"],
  score_categories: [{ value: "quality", count: 10 }],
  promptName: [{ value: "summarize-v2" }],
  tags: [{ value: "important" }],
  type: [{ value: "GENERATION" }, { value: "SPAN" }],
  toolNames: [{ value: "calculator" }],
  calledToolNames: [{ value: "calculator" }],
};

// Get column definitions with populated options for the UI filter builder
const columns = observationsTableColsWithOptions(options);