Implementation:Langfuse Langfuse IsTraceIdInSample

Knowledge Sources	Langfuse
Domains	Observability, Trace Ingestion
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for deterministic trace-level sampling using SHA-256 consistent hashing provided by Langfuse.

Description

The isTraceIdInSample function determines whether a given ingestion event should be processed or dropped based on the project's configured sampling rate. It uses a SHA-256 hash of the trace ID to produce a deterministic and uniformly distributed decision.

The function operates as follows:

1. Look up the project's sampling configuration from the LANGFUSE_INGESTION_PROCESSING_SAMPLED_PROJECTS environment variable (a map of project IDs to sampling rates between 0 and 1).
2. If the project has no sampling configuration, return isSampled: true (include the event).
3. Extract the trace ID from the event: for trace-create events, use body.id; for all other events, use body.traceId.
4. If no trace ID can be determined, return isSampled: true (be conservative).
5. Compute SHA-256(traceId), take the first 8 hex characters (32 bits), convert to an integer, normalize to [0, 1] by dividing by 0xFFFFFFFF, and compare against the sampling rate.

The helper function isInSample handles edge cases: invalid sample rates (negative or greater than 1) default to including the event, sampleRate === 0 excludes all events, and sampleRate === 1 includes all events.

Usage

This function is called from processEventBatch for each event group before queue dispatch. Events that are not sampled are dropped with a metric increment for monitoring purposes.

Code Reference

Source Location

• Repository: langfuse
• File: packages/shared/src/server/ingestion/sampling.ts
• Lines: L6-28 (isTraceIdInSample), L30-53 (isInSample), L55-59 (parseTraceId)

Signature

export function isTraceIdInSample(params: {
  projectId: string | null;
  event: IngestionEventType;
}): { isSampled: boolean; isSamplingConfigured: boolean }

Import

import { isTraceIdInSample } from "@langfuse/shared/src/server/ingestion/sampling";

I/O Contract

Inputs

Name	Type	Required	Description
params.projectId	null	Yes	The ID of the project the event belongs to. Used to look up the sampling rate configuration.
params.event	IngestionEventType	Yes	A validated ingestion event. The trace ID is extracted from either body.id (for trace-create) or body.traceId (for all other event types).

Outputs

Name	Type	Description
isSampled	boolean	true if the event should be processed, false if it should be dropped.
isSamplingConfigured	boolean	true if the project has a sampling configuration entry, false if the project is not listed in the sampling config (meaning all events are processed).

Usage Examples

Basic Sampling Check

import { isTraceIdInSample } from "@langfuse/shared/src/server/ingestion/sampling";

const event = {
  id: "evt_001",
  timestamp: "2024-01-15T10:30:00.000Z",
  type: "trace-create" as const,
  body: {
    id: "trace_abc123",
    name: "My Trace",
    environment: "default",
  },
};

const { isSampled, isSamplingConfigured } = isTraceIdInSample({
  projectId: "proj_xyz",
  event,
});

if (!isSampled) {
  // Drop the event; it falls outside the configured sample.
  console.log("Event dropped by sampling");
  return;
}

// Proceed with processing...

Conditional Metric Recording

import { isTraceIdInSample } from "@langfuse/shared/src/server/ingestion/sampling";
import { recordIncrement } from "@langfuse/shared/src/server/instrumentation";

const { isSampled, isSamplingConfigured } = isTraceIdInSample({
  projectId: authCheck.scope.projectId,
  event: eventData.data[0],
});

if (!isSampled) {
  recordIncrement("langfuse.ingestion.sampling", eventData.data.length, {
    projectId: authCheck.scope.projectId ?? "<not set>",
    sampling_decision: "out",
  });
  return;
}

if (isSamplingConfigured) {
  recordIncrement("langfuse.ingestion.sampling", eventData.data.length, {
    projectId: authCheck.scope.projectId ?? "<not set>",
    sampling_decision: "in",
  });
}

Observation Event Sampling

import { isTraceIdInSample } from "@langfuse/shared/src/server/ingestion/sampling";

// For observation events, the trace ID is extracted from body.traceId
const generationEvent = {
  id: "evt_002",
  timestamp: "2024-01-15T10:30:01.000Z",
  type: "generation-create" as const,
  body: {
    id: "gen_001",
    traceId: "trace_abc123",  // Same trace ID -> same sampling decision
    name: "LLM Call",
    model: "gpt-4",
    environment: "default",
  },
};

const result = isTraceIdInSample({
  projectId: "proj_xyz",
  event: generationEvent,
});

// result.isSampled will be the same as for the trace-create event
// with trace ID "trace_abc123", because SHA-256 is deterministic.

Related Pages

Implements Principle

• Principle:Langfuse_Langfuse_Trace_Sampling