Implementation:Langfuse Langfuse Analytics Integration Types

Knowledge Sources	Langfuse
Domains	Analytics Integrations, PostHog, Mixpanel
Last Updated	2026-02-14 00:00 GMT

Overview

Defines the TypeScript type interfaces for analytics integration events sent to external platforms such as PostHog and Mixpanel, representing the raw data structures from ClickHouse queries.

Description

This module provides four event type definitions that standardize the shape of data exported from Langfuse to external analytics platforms:

• AnalyticsTraceEvent: Represents a trace-level event with fields for trace identification (langfuse_id, timestamp), trace metadata (langfuse_trace_name, langfuse_url, langfuse_user_url), cost (langfuse_cost_usd), observation count (langfuse_count_observations), session and project context, user tracking, latency, release/version info, tags, environment, and external session IDs (posthog_session_id, mixpanel_session_id).

• AnalyticsGenerationEvent: Represents a generation-level event (LLM calls) with additional fields for generation name, associated trace info, token usage breakdowns (langfuse_input_units, langfuse_output_units, langfuse_total_units), time to first token, and model identification.

• AnalyticsScoreEvent: Represents a score event with score-specific fields including name, value, comment, metadata, string value, data type, entity type, and dataset run ID.

• AnalyticsObservationEvent: Represents a generic observation event with fields similar to generation events but also including observation type (langfuse_type).

All fields except langfuse_id and timestamp are optional, and all values are typed as unknown to accommodate the dynamic nature of ClickHouse query results. Each event type includes both posthog_session_id and mixpanel_session_id for cross-platform session correlation, plus langfuse_event_version for schema versioning.

Usage

Use these types when building or consuming analytics integration pipelines. They define the contract between the ClickHouse query layer that fetches event data and the integration services that format and send events to PostHog, Mixpanel, or other analytics platforms.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/analytics-integrations/types.ts
• Lines: 1-105

Signature

export type AnalyticsTraceEvent = {
  langfuse_id: unknown;
  timestamp: unknown;
  langfuse_trace_name?: unknown;
  langfuse_url?: unknown;
  // ... additional optional fields
  posthog_session_id?: unknown;
  mixpanel_session_id?: unknown;
};

export type AnalyticsGenerationEvent = {
  langfuse_id: unknown;
  timestamp: unknown;
  langfuse_generation_name?: unknown;
  // ... additional optional fields
};

export type AnalyticsScoreEvent = {
  langfuse_id: unknown;
  timestamp: unknown;
  langfuse_score_name?: unknown;
  langfuse_score_value?: unknown;
  // ... additional optional fields
};

export type AnalyticsObservationEvent = {
  langfuse_id: unknown;
  timestamp: unknown;
  langfuse_observation_name?: unknown;
  langfuse_type?: unknown;
  // ... additional optional fields
};

Import

import type {
  AnalyticsTraceEvent,
  AnalyticsGenerationEvent,
  AnalyticsScoreEvent,
  AnalyticsObservationEvent,
} from "@langfuse/shared/src/server/analytics-integrations/types";

I/O Contract

Inputs

Name	Type	Required	Description
(none)	N/A	N/A	These are pure type definitions with no runtime inputs.

Outputs

Name	Type	Description
AnalyticsTraceEvent	type	Shape of a trace event for analytics export, 21 fields.
AnalyticsGenerationEvent	type	Shape of a generation event for analytics export, 24 fields.
AnalyticsScoreEvent	type	Shape of a score event for analytics export, 24 fields.
AnalyticsObservationEvent	type	Shape of an observation event for analytics export, 25 fields.

Usage Examples

import type { AnalyticsTraceEvent } from "@langfuse/shared/src/server/analytics-integrations/types";

function formatTraceForPostHog(event: AnalyticsTraceEvent): Record<string, unknown> {
  return {
    distinct_id: String(event.langfuse_user_id ?? "anonymous"),
    event: "langfuse_trace",
    properties: {
      trace_name: event.langfuse_trace_name,
      cost_usd: event.langfuse_cost_usd,
      latency: event.langfuse_latency,
      $session_id: event.posthog_session_id,
    },
    timestamp: event.timestamp,
  };
}