Implementation:Langfuse Langfuse ObservationForEval

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

Overview

Defines the schema, types, filter columns, and variable mapping columns used to represent and evaluate observations within the Langfuse evaluation system.

Description

This module provides the foundational data structures for the observation-based evaluation pipeline. It contains:

1. observationForEvalSchema: A Zod v4 schema that describes the shape of an observation record as consumed by the eval system. Fields include identifiers (span_id, trace_id, project_id), core properties (type, name, environment, level), trace-level denormalized properties (trace_name, user_id, session_id, tags), model information, prompt references, usage/cost details, tool call data, experiment context, and I/O data (input, output, metadata).

1. convertEventRecordToObservationForEval: A function that converts a raw EventRecordBaseType from the ClickHouse events table into the validated ObservationForEval shape.

1. Filter column definitions: observationEvalFilterColumns and experimentEvalFilterColumns define which fields are available for filtering when configuring which observations an eval applies to. These support runtime population of options (e.g., environment names, tags, trace names).

1. Variable column definitions: observationEvalVariableColumns and availableObservationEvalVariableColumns define which observation fields can be mapped to template variables in eval prompts (e.g., mapping input to Template:Input).

1. Helper functions: observationEvalFilterColsWithOptions, experimentEvalFilterColsWithOptions, and mapEventEvalFilterColumnIdToField provide utilities for populating filter options at runtime and resolving camelCase column IDs to snake_case observation fields.

Usage

Use this module when building or configuring observation-based evaluations. The schema validates observation records before eval processing. The filter and variable column definitions drive the UI for eval configuration and the backend for eval filtering logic.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/features/evals/observationForEval.ts
• Lines: 1-353

Signature

export const observationForEvalSchema = z.object({
  span_id: z.string(),
  trace_id: z.string(),
  project_id: z.string(),
  type: z.string(),
  name: z.string(),
  environment: z.string().default(DEFAULT_TRACE_ENVIRONMENT),
  input: z.unknown().nullish(),
  output: z.unknown().nullish(),
  metadata: z.record(z.string(), z.unknown()).nullish(),
  // ... additional fields
});

export type ObservationForEval = z.infer<typeof observationForEvalSchema>;

export function convertEventRecordToObservationForEval(
  record: EventRecordBaseType,
): ObservationForEval;

export type ObservationEvalFilterColumnInternal = keyof Pick<ObservationForEval, ...>;
export type ObservationEvalMappingColumnInternal = keyof Pick<ObservationForEval, ...>;

export const observationEvalVariableColumns: ObservationEvalVariableColumn[];
export const availableObservationEvalVariableColumns: Array<...>;
export const observationEvalFilterColumns: ObservationEvalColumnDef[];
export const experimentEvalFilterColumns: ObservationEvalColumnDef[];
export const eventsEvalFilterColumns: ObservationEvalColumnDef[];

export function observationEvalFilterColsWithOptions(
  options?: ObservationEvalOptions,
  cols?: ColumnDefinition[],
): ColumnDefinition[];

export function experimentEvalFilterColsWithOptions(
  options?: ExperimentEvalOptions,
  cols?: ColumnDefinition[],
): ColumnDefinition[];

export function mapEventEvalFilterColumnIdToField(
  observation: ObservationForEval,
  column: string,
): unknown;

Import

import {
  observationForEvalSchema,
  convertEventRecordToObservationForEval,
  observationEvalFilterColumns,
  observationEvalVariableColumns,
  mapEventEvalFilterColumnIdToField,
} from "@langfuse/shared";

I/O Contract

Inputs

Name	Type	Required	Description
record	EventRecordBaseType	Yes	A raw event record from ClickHouse to be converted into an ObservationForEval
options	ObservationEvalOptions	No	Runtime filter options (environment, tags, traceName, name) to populate column definitions
column	string	Yes	A camelCase column ID to resolve against the eval filter column definitions

Outputs

Name	Type	Description
ObservationForEval	object	Validated observation record with all fields parsed and defaults applied
ColumnDefinition[]	array	Filter column definitions with runtime options populated
unknown	any	The value from the observation matching the specified column ID

Usage Examples

import {
  convertEventRecordToObservationForEval,
  observationEvalFilterColsWithOptions,
  mapEventEvalFilterColumnIdToField,
} from "@langfuse/shared";

// Convert a raw event record for eval processing
const observation = convertEventRecordToObservationForEval(rawEventRecord);

// Populate filter columns with runtime options for the UI
const filterCols = observationEvalFilterColsWithOptions({
  environment: [{ value: "production" }, { value: "staging" }],
  tags: [{ value: "important" }],
  traceName: [{ value: "chat-completion" }],
  name: [{ value: "gpt-4-call" }],
});

// Resolve a filter column ID to the actual observation field value
const value = mapEventEvalFilterColumnIdToField(observation, "traceName");
// Returns observation.trace_name

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics