Observation Data Loading#

Overview#

Observation data loading in Langfuse refers to the server-side mechanism for fetching observation records (spans, generations, events) from ClickHouse. The central optimization is conditional field exclusion: large fields (input, output, metadata, and tool-related fields) are omitted from the SQL SELECT by default and only included when explicitly requested. This directly reduces query payload size, CPU cost, and memory pressure for high-observation-count traces.

Core Query Function: getObservationsForTrace#

The primary function for trace-scoped observation loading is getObservationsForTrace in packages/shared/src/server/repositories/observations.ts.

Signature:

type GetObservationsForTraceOpts<IncludeIO extends boolean> = {
  traceId: string;
  projectId: string;
  timestamp?: Date;
  includeIO?: IncludeIO; // defaults to false
  preferredClickhouseService?: PreferredClickhouseService;
};

1

The includeIO flag uses a generic type parameter (IncludeIO extends boolean) for type-safe conditional field inclusion. When false (the default), the SQL SELECT clause omits input, output, metadata, tool_definitions, tool_calls, and tool_call_names entirely — not at the application layer, but at the ClickHouse query level 2:

${includeIO === true ? "input, output, metadata," : ""}
...
${includeIO === true ? "tool_definitions, tool_calls, tool_call_names," : ""}

Payload Size Guard#

Even when includeIO: true, the function enforces a byte-level limit after fetching. It accumulates the string lengths of input, output, and metadata values across all returned observations and throws if the total exceeds env.LANGFUSE_API_TRACE_OBSERVATIONS_SIZE_LIMIT_BYTES 3. This is a secondary defense against NextJS's ~5 MB response size limit.

Usage at the tRPC Layer#

The tRPC traces.byIdWithObservationsAndScores procedure calls getObservationsForTrace with includeIO: false 4. The observations are returned to the frontend without I/O — the UI fetches individual observation I/O separately on demand. This keeps the initial trace load fast even for large traces.

Related Query Functions#

The same conditional-exclusion pattern appears across several observation repository functions 5:

Trace Download: Adaptive Field Inclusion (PR #13033)#

PR #13033 (feat: Add new trace download endpoint) introduces a two-level adaptive strategy for the /api/traces/[traceId]/download endpoint:

1. Observation-count threshold: Defined as TRACE_DOWNLOAD_OMIT_LARGE_FIELDS_THRESHOLD = 350 in web/src/features/traces/shared/traceDownloadConfig.ts. Traces with ≥ 350 observations fetch with selectIOAndMetadata: false and selectToolData: false; smaller traces fetch with both flags true. 6

2. Byte-level validation: The download builder iterates observations and sums input/output/metadata byte lengths. If the total exceeds env.LANGFUSE_API_TRACE_OBSERVATIONS_SIZE_LIMIT_BYTES, it throws a TraceDownloadTooLargeError with the actual and limit sizes. 6

The response omits the large fields from the export object when omitLargeFields = true, using a spread:

...(!omitLargeFields ? { toolDefinitions, toolCalls, input, output, metadata } : {})

Observations v2 API: Field Group System#

The newer GET /api/public/v2/observations endpoint (ClickHouse-backed, feature-flagged via LANGFUSE_ENABLE_EVENTS_TABLE_V2_APIS) uses a more granular field group system instead of a single boolean 7:

• The fields query parameter accepts comma-separated group names (core, basic, io, metadata, model, usage, prompt, metrics, time).
• Omitting fields defaults to ["core", "basic"] — no I/O or metadata loaded.
• When io or metadata are requested, the query switches to a CTE-based split strategy: filtering/ordering on the lightweight events_core table first, then fetching I/O only for matched rows from events_full. 7
• The OBSERVATION_FIELD_GROUPS constant in packages/shared/src/server/repositories/events.ts is the authoritative list of valid group names.

Key Source Files#