Implementation:Langfuse Langfuse Tracing Factory

Knowledge Sources	Langfuse
Domains	Testing, Tracing, ClickHouse
Last Updated	2026-02-14 00:00 GMT

Overview

This module provides factory functions for creating test fixture data for traces, observations, scores, dataset run items, and events used in ClickHouse-based tests.

Description

The tracing-factory.ts file is a test utility module in the shared package that contains factory functions for generating ClickHouse-compatible insert records with sensible defaults. Each factory function accepts a Partial of the corresponding record insert type, allowing tests to override only the fields they care about while the factory fills in the rest with UUIDs, timestamps, and representative default values.

The module provides seven factory functions:

• createTrace - Creates a TraceRecordInsertType with defaults including a random name, tags, release info, and metadata.
• createObservation - Creates an ObservationRecordInsertType with defaults for a GENERATION-type observation, including usage details (input/output/total tokens), cost details, model parameters, and prompt info.
• createTraceScore - Creates a ScoreRecordInsertType associated with a trace, with numeric data type and API source.
• createSessionScore - Creates a ScoreRecordInsertType associated with a session (trace_id and observation_id are null).
• createDatasetRunScore - Creates a ScoreRecordInsertType associated with a dataset run (trace_id, observation_id, and session_id are null).
• createDatasetRunItem - Creates a DatasetRunItemRecordInsertType with dataset item input/output/metadata.
• createEvent - Creates an EventRecordInsertType with extensive defaults covering metadata arrays, experiment properties, source metadata (OTel instrumentation fields), and timestamps in microsecond precision.

All functions use uuid.v4() for generating unique identifiers and Date.now() for timestamps. The spread operator pattern (...trace) at the end of each factory ensures that provided overrides take precedence over defaults, with specific exceptions for score factories where certain fields are explicitly set to null after the spread to enforce the score's target type (e.g., session scores always have null trace_id).

Usage

Use these factory functions in test files when you need to:

• Insert test traces, observations, or scores into ClickHouse for integration tests.
• Create test data with predictable structure while only specifying the fields relevant to the test case.
• Generate dataset run items for testing dataset evaluation flows.
• Create event records for testing the events table pipeline.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/test-utils/tracing-factory.ts
• Lines: 1-305

Signature

export const createTrace: (trace: Partial<TraceRecordInsertType>) => TraceRecordInsertType;

export const createDatasetRunItem: (datasetRunItem: Partial<DatasetRunItemRecordInsertType>) => DatasetRunItemRecordInsertType;

export const createObservation: (observation: Partial<ObservationRecordInsertType>) => ObservationRecordInsertType;

export const createTraceScore: (score: Partial<ScoreRecordInsertType>) => ScoreRecordInsertType;

export const createSessionScore: (score: Partial<ScoreRecordInsertType>) => ScoreRecordInsertType;

export const createDatasetRunScore: (score: Partial<ScoreRecordInsertType>) => ScoreRecordInsertType;

export const createEvent: (event: Partial<EventRecordInsertType>) => EventRecordInsertType;

Import

import {
  createTrace,
  createObservation,
  createTraceScore,
  createSessionScore,
  createDatasetRunScore,
  createDatasetRunItem,
  createEvent,
} from "@langfuse/shared/src/server/test-utils/tracing-factory";

I/O Contract

Inputs

Name	Type	Required	Description
trace	Partial<TraceRecordInsertType>	Yes	Partial trace record; unspecified fields receive defaults
observation	Partial<ObservationRecordInsertType>	Yes	Partial observation record; defaults to GENERATION type
score	Partial<ScoreRecordInsertType>	Yes	Partial score record; defaults vary by score target (trace, session, or dataset run)
datasetRunItem	Partial<DatasetRunItemRecordInsertType>	Yes	Partial dataset run item record with dataset metadata defaults
event	Partial<EventRecordInsertType>	Yes	Partial event record with extensive defaults for all event columns

Outputs

Name	Type	Description
TraceRecordInsertType	TraceRecordInsertType	Complete trace record ready for ClickHouse insertion
ObservationRecordInsertType	ObservationRecordInsertType	Complete observation record with usage/cost details
ScoreRecordInsertType	ScoreRecordInsertType	Complete score record with appropriate null fields based on score type
DatasetRunItemRecordInsertType	DatasetRunItemRecordInsertType	Complete dataset run item record
EventRecordInsertType	EventRecordInsertType	Complete event record with metadata arrays, experiment fields, and microsecond timestamps

Usage Examples

import { createTrace, createObservation, createTraceScore } from "@langfuse/shared/src/server/test-utils/tracing-factory";

// Create a trace with specific project and session
const trace = createTrace({
  project_id: "test-project-123",
  session_id: "session-abc",
  name: "my-test-trace",
});

// Create an observation linked to the trace
const observation = createObservation({
  project_id: trace.project_id,
  trace_id: trace.id,
  type: "SPAN",
  name: "database-call",
  usage_details: { input: 0, output: 0, total: 0 },
});

// Create a score for the trace
const score = createTraceScore({
  project_id: trace.project_id,
  trace_id: trace.id,
  name: "accuracy",
  value: 0.95,
  data_type: "NUMERIC",
});

// Create a session score (trace_id will be null)
const sessionScore = createSessionScore({
  project_id: trace.project_id,
  session_id: trace.session_id,
  name: "session-quality",
  value: 4.5,
});

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics