🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
import { removeEmptyEnvVariables } from "@langfuse/shared";
import { langfuseS3EventKeyMaxSegmentBytesSchema } from "@langfuse/shared/src/env";
import { z } from "zod";
const EnvSchema = z.object({
BUILD_ID: z.string().optional(),
NODE_ENV: z
.enum(["development", "test", "production"])
.default("development"),
DATABASE_URL: z.string(),
HOSTNAME: z.string().default("0.0.0.0"),
PORT: z.coerce
.number() // ".env files convert numbers to strings, therefore we have to enforce them to be numbers"
.positive()
.max(65536, `options.port should be >= 0 and < 65536`)
.default(3030),
NEXTAUTH_URL: z.string().optional(),
// Base URL for the in-app agent's MCP calls. Defaults to NEXTAUTH_URL.
// Set this instead of redirecting NEXTAUTH_URL when the worker should reach
// web internally: NEXTAUTH_URL also builds user-facing links in emails and
// Slack messages, which must stay externally resolvable.
// Web validates the Host header of MCP requests, so any hostname used here
// other than NEXTAUTH_URL's own must be listed in LANGFUSE_MCP_ALLOWED_HOSTS
// on web, or the requests are rejected.
LANGFUSE_MCP_BASE_URL: z.url().optional(),
NEXT_PUBLIC_BASE_PATH: z.string().optional(),
NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: z
.enum(["US", "EU", "STAGING", "DEV", "HIPAA", "JP"])
.optional(),
STRIPE_SECRET_KEY: z.string().optional(),
// ClickHouse Billing cutoff, shared with web via the provider resolver in
// @langfuse/shared (getBillingProvider). The worker only consults it in the
// defensive usage-metering guard; unset = CHB routing off. Date-only
// (YYYY-MM-DD) so the cutline is a single unambiguous instant of UTC
// midnight, which is what new Date() yields for a date-only string. Parsed
// here so every consumer gets the same instant; keep in sync with
// web/src/env.mjs.
LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE: z.iso
.date()
.optional()
.transform((date) => (date ? new Date(date) : null)),
// Comma-separated Langfuse organization ids routed to CHB regardless of the
// cutoff; keep in sync with web/src/env.mjs.
LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: z
.string()
.default("")
.transform((value) =>
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
),
// CHB REST credentials, mirroring web/src/env.mjs. The worker needs them for
// one read: the spend-alert job asks for the open period's accrued usage.
CLICKHOUSE_BILLING_BASE_URL: z.url().optional(),
CLICKHOUSE_BILLING_AUTH0_DOMAIN: z.string().optional(),
CLICKHOUSE_BILLING_AUTH0_CLIENT_ID: z.string().optional(),
CLICKHOUSE_BILLING_AUTH0_CLIENT_SECRET: z.string().optional(),
// CHB's resource-server identifier. Defaulted because it is the same value
// in every CHB tenant, and overridable in case that stops being true.
CLICKHOUSE_BILLING_AUTH0_AUDIENCE: z.string().default("billing-api"),
// Compares each metered Stripe interval with the billable_events ledger and
// reports the gap. Requires the ledger table, which only Langfuse Cloud has;
// keep in sync with web/src/env.mjs.
LANGFUSE_BILLING_LEDGER_SHADOW_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_CACHE_AUTOMATIONS_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_CACHE_AUTOMATIONS_TTL_SECONDS: z.coerce.number().default(60),
LANGFUSE_S3_BATCH_EXPORT_ENABLED: z.enum(["true", "false"]).default("false"),
LANGFUSE_S3_BATCH_EXPORT_BUCKET: z.string().optional(),
LANGFUSE_S3_BATCH_EXPORT_PREFIX: z.string().default(""),
LANGFUSE_S3_BATCH_EXPORT_REGION: z.string().optional(),
LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: z.string().optional(),
LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT: z.string().optional(),
LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: z.string().optional(),
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: z.string().optional(),
LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_BATCH_EXPORT_SSE: z.enum(["AES256", "aws:kms"]).optional(),
LANGFUSE_S3_BATCH_EXPORT_SSE_KMS_KEY_ID: z.string().optional(),
LANGFUSE_S3_EVENT_UPLOAD_BUCKET: z.string({
error: "Langfuse requires a bucket name for S3 Event Uploads.",
}),
LANGFUSE_S3_EVENT_UPLOAD_PREFIX: z.string().default(""),
LANGFUSE_S3_EVENT_UPLOAD_REGION: z.string().optional(),
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: z.string().optional(),
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: z.string().optional(),
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: z.string().optional(),
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_EVENT_UPLOAD_SSE: z.enum(["AES256", "aws:kms"]).optional(),
LANGFUSE_S3_EVENT_UPLOAD_SSE_KMS_KEY_ID: z.string().optional(),
// Validation rules live in `@langfuse/shared/src/env` so producer and
// consumer agree on what values are accepted. Must match the web container's
// resolved value at deploy time; otherwise web and worker can write/read
// different S3 keys for the same id.
LANGFUSE_S3_EVENT_KEY_MAX_SEGMENT_BYTES:
langfuseS3EventKeyMaxSegmentBytesSchema,
BATCH_EXPORT_PAGE_SIZE: z.coerce.number().positive().default(500),
BATCH_EXPORT_ROW_LIMIT: z.coerce.number().positive().default(1_500_000),
BATCH_EXPORT_DOWNLOAD_LINK_EXPIRATION_HOURS: z.coerce
.number()
.positive()
.default(24),
BATCH_EXPORT_S3_PART_SIZE_MIB: z.coerce.number().min(5).max(100).default(10),
BATCH_ACTION_EXPORT_ROW_LIMIT: z.coerce.number().positive().default(50_000),
LANGFUSE_MAX_HISTORIC_EVAL_CREATION_LIMIT: z.coerce
.number()
.positive()
.default(50_000),
EMAIL_FROM_ADDRESS: z.string().optional(),
SMTP_CONNECTION_URL: z.string().optional(),
CLOUD_CRM_EMAIL: z.string().optional(),
LANGFUSE_OTEL_INGESTION_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_OTEL_INGESTION_SECONDARY_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_OTEL_MEDIA_UPLOAD_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_OTEL_EARLY_MEDIA_EXTRACTION_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_OTEL_EARLY_MEDIA_EXTRACTION_PROJECT_IDS: z
.string()
.default("")
.transform((value) =>
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
)
.refine((ids) => !ids.includes("*") || ids.length === 1, {
message:
'Use "*" alone to select all projects, or a comma-separated list of project IDs',
}),
LANGFUSE_TRACE_BATCH_INGESTION_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_TRACE_BATCH_SAMPLING_RATE: z.coerce
.number()
.min(0)
.max(1)
.default(0),
LANGFUSE_TRACE_BATCH_DISPATCHER_ENABLED: z
.enum(["true", "false"])
.default("false"),
QUEUE_CONSUMER_TRACE_BATCH_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_TRACE_BATCH_READ_ENABLED: z.enum(["true", "false"]).default("false"),
LANGFUSE_TRACE_BATCH_TRANSCRIPT_STORAGE_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_TRACE_BATCH_TRANSCRIPT_METRICS_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_TRACE_BATCH_CONCURRENCY: z.coerce
.number()
.int()
.positive()
.default(2),
LANGFUSE_TRACE_BATCH_MAX_THREADS: z.coerce
.number()
.int()
.positive()
.default(2),
LANGFUSE_TRACE_BATCH_REQUEST_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(40_000),
LANGFUSE_TRACE_BATCH_MAX_PENDING_SUMMARY_BYTES: z.coerce
.number()
.int()
.positive()
.default(100 * 1024 * 1024),
// Traces summarized and embedded at once per Topics job, in both trace-batch and manual processing.
LANGFUSE_TOPICS_TRACE_CONCURRENCY: z.coerce
.number()
.int()
.positive()
.default(20),
// Admission policy for full-cohort fitting; excludes child-process and runtime overhead.
LANGFUSE_TOPICS_MAX_CLUSTERING_ROWS: z.coerce
.number()
.int()
.positive()
.default(20_000),
LANGFUSE_TOPICS_MAX_CLUSTERING_BYTES: z.coerce
.number()
.int()
.positive()
.default(256 * 1024 * 1024),
LANGFUSE_TRACE_BATCH_MAX_BLOCK_SIZE: z.coerce
.number()
.int()
.positive()
.optional(),
LANGFUSE_TRACE_BATCH_EXPERIMENT_ID: z
.string()
.min(1)
.max(64)
.regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/)
.optional(),
LANGFUSE_TRACE_BATCH_MAX_SIZE: z.coerce
.number()
.int()
.positive()
.max(10_000)
.default(60),
// Weight budgets use ingestion-time estimates; 0 disables a budget.
LANGFUSE_TRACE_BATCH_MAX_BATCH_EVENT_UPDATES: z.coerce
.number()
.int()
.nonnegative()
.default(1_500),
LANGFUSE_TRACE_BATCH_MAX_BATCH_SERIALIZED_BYTES: z.coerce
.number()
.int()
.nonnegative()
.default(64 * 1024 * 1024),
LANGFUSE_TRACE_BATCH_MAX_TRACE_EVENT_UPDATES: z.coerce
.number()
.int()
.nonnegative()
.default(5_000),
LANGFUSE_TRACE_BATCH_MAX_TRACE_SERIALIZED_BYTES: z.coerce
.number()
.int()
.nonnegative()
.default(50 * 1024 * 1024),
LANGFUSE_TRACE_BATCH_STRATEGY: z
.enum(["project", "locality"])
.default("project"),
LANGFUSE_TRACE_BATCH_IDLE_MS: z.coerce.number().int().positive(),
LANGFUSE_TRACE_BATCH_SHARD_COUNT: z.coerce.number().int().min(1).max(256),
LANGFUSE_TRACE_BATCH_FIRST_SEEN_TTL_MS: z.coerce
.number()
.int()
.positive()
.max(2 * 24 * 60 * 60 * 1_000)
.default(24 * 60 * 60 * 1_000),
// Recovery grace after readiness; whole-key expiry includes the idle interval.
LANGFUSE_TRACE_BATCH_PENDING_TTL_MS: z.coerce
.number()
.int()
.positive()
.default(7_200_000),
LANGFUSE_TRACE_BATCH_DISPATCH_INTERVAL_MS: z.coerce
.number()
.int()
.positive()
.default(30_000),
LANGFUSE_SECONDARY_OTEL_INGESTION_QUEUE_ENABLED_PROJECT_IDS: z
.string()
.optional(),
LANGFUSE_INGESTION_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(20),
LANGFUSE_INGESTION_SECONDARY_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_SECONDARY_INGESTION_QUEUE_ENABLED_PROJECT_IDS: z.string().optional(),
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_BATCH_SIZE: z.coerce
.number()
.positive()
.default(1000),
LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS: z.coerce
.number()
.positive()
.default(1000),
LANGFUSE_INGESTION_CLICKHOUSE_MAX_ATTEMPTS: z.coerce
.number()
.positive()
.default(3),
LANGFUSE_USE_AZURE_BLOB: z.enum(["true", "false"]).default("false"),
CLICKHOUSE_URL: z.url(),
CLICKHOUSE_USER: z.string(),
CLICKHOUSE_CLUSTER_NAME: z.string().default("default"),
CLICKHOUSE_DB: z.string().default("default"),
CLICKHOUSE_PASSWORD: z.string(),
CLICKHOUSE_CLUSTER_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_EVAL_CREATOR_LIMITER_DURATION: z.coerce
.number()
.positive()
.default(500),
LANGFUSE_EVAL_CREATOR_WORKER_CONCURRENCY: z.coerce
.number()
.positive()
.default(2),
LANGFUSE_TRACE_UPSERT_WORKER_CONCURRENCY: z.coerce
.number()
.positive()
.default(25),
LANGFUSE_TRACE_DELETE_CONCURRENCY: z.coerce.number().positive().default(1),
LANGFUSE_SCORE_DELETE_CONCURRENCY: z.coerce.number().positive().default(1),
// Delay (ms) inserted after each Mixpanel flush to throttle analytics exports
// and avoid overwhelming the target instance (see issue #12786).
LANGFUSE_MIXPANEL_FLUSH_DELAY_MS: z.coerce.number().min(0).default(100),
// Timeout (ms) for each Mixpanel import request, so an unresponsive endpoint
// cannot hold the integration job indefinitely (see issue #15958).
LANGFUSE_MIXPANEL_TIMEOUT_MS: z.coerce.number().positive().default(30000),
// Delay (ms) after each PostHog flush. Together with 1,000-event flushes,
// this bounds the export rate for fast-acknowledging target instances.
LANGFUSE_POSTHOG_FLUSH_DELAY_MS: z.coerce.number().min(0).default(100),
LANGFUSE_DATASET_DELETE_CONCURRENCY: z.coerce.number().positive().default(1),
LANGFUSE_PROJECT_DELETE_CONCURRENCY: z.coerce.number().positive().default(1),
LANGFUSE_EVAL_EXECUTION_WORKER_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_LLM_AS_JUDGE_EXECUTION_WORKER_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_LLM_AS_JUDGE_QUEUE_RETRY_MAX_ATTEMPTS: z.coerce
.number()
.int()
.min(0)
.default(4),
LANGFUSE_LLM_AS_JUDGE_QUEUE_RETRY_MAX_AGE_SECONDS: z.coerce
.number()
.int()
.positive()
.default(120 * 60),
LANGFUSE_CODE_EVAL_EXECUTION_WORKER_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_EVAL_EXECUTION_SECONDARY_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_SECONDARY_EVAL_EXECUTION_QUEUE_ENABLED_PROJECT_IDS: z
.string()
.optional(),
LANGFUSE_EXPERIMENT_CREATOR_WORKER_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
// Skip the read from ClickHouse within the Ingestion pipeline for the given
// project ids. Applicable for projects that were created after the S3 write
// was activated and which don't rely on historic updates.
LANGFUSE_SKIP_INGESTION_CLICKHOUSE_READ_PROJECT_IDS: z.string().default(""),
// Set a date after which S3 was active. Projects created after this date do
// perform a ClickHouse read as part of the ingestion pipeline.
LANGFUSE_SKIP_INGESTION_CLICKHOUSE_READ_MIN_PROJECT_CREATE_DATE: z.iso
.date()
.optional(),
// Otel
OTEL_EXPORTER_OTLP_ENDPOINT: z.string().default("http://localhost:4318"),
OTEL_SERVICE_NAME: z.string().default("worker"),
// Stamps ECS task/cluster (aws.ecs.*, cloud.*) and container.id resource
// attributes onto every exported span.
OTEL_CONTAINER_RESOURCE_DETECTORS_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_ENABLE_BACKGROUND_MIGRATIONS: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_ENABLE_REDIS_SEEN_EVENT_CACHE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_BLOB_STORAGE_FAILURE_NOTIFICATION_COOLDOWN_HOURS: z.coerce
.number()
.positive()
.default(24),
// Comma-separated list of project IDs that should only export traces table (skip observations and scores)
LANGFUSE_BLOB_STORAGE_EXPORT_TRACE_ONLY_PROJECT_IDS: z
.string()
.optional()
.transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
LANGFUSE_MONITOR_SCHEDULER_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_MONITOR_SCHEDULERS: z.coerce.number().int().min(1).default(1),
// Flags to toggle queue consumers on or off.
QUEUE_CONSUMER_MONITOR_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
// Run execution follows LANGFUSE_IN_APP_AGENT_ENABLED unless opted out.
QUEUE_CONSUMER_IN_APP_AGENT_RUN_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.optional(),
LANGFUSE_IN_APP_AGENT_INTEGRITY_RUNNER_ENABLED: z
.enum(["true", "false"])
.optional(),
LANGFUSE_IN_APP_AGENT_RETENTION_CLEANER_ENABLED: z
.enum(["true", "false"])
.default("true"),
// Opt in to the AI-features project's production skills with this tag.
LANGFUSE_IN_APP_AGENT_SKILLS_TAG: z.string().trim().min(1).optional(),
LANGFUSE_IN_APP_AGENT_SANDBOX_PROVIDER: z
.enum(["dangerous-docker", "lambda-microvm"])
.optional(),
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_IMAGE_IDENTIFIER: z
.string()
.optional(),
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_EXECUTION_ROLE_ARN: z
.string()
.optional(),
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_EGRESS_NETWORK_CONNECTOR_ARN:
z.string().optional(),
LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_REGION: z
.string()
.optional(),
QUEUE_CONSUMER_CLOUD_USAGE_METERING_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_CLOUD_SPEND_ALERT_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_FREE_TIER_USAGE_THRESHOLD_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_INGESTION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_BATCH_EXPORT_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_BATCH_ACTION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_TOPICS_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_TOPICS_UPDATE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_TOPICS_EMBEDDING_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_TOPICS_AUTOMATION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_EVAL_EXECUTION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_EVAL_EXECUTION_SECONDARY_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_CODE_EVAL_EXECUTION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_TRACE_UPSERT_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_CREATE_EVAL_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_TRACE_DELETE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_SCORE_DELETE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_DATASET_DELETE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_PROJECT_DELETE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_DATASET_RUN_ITEM_UPSERT_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_EXPERIMENT_CREATE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_POSTHOG_INTEGRATION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_V4_LEGACY_API_USAGE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_MIXPANEL_INTEGRATION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_BLOB_STORAGE_INTEGRATION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_OTEL_INGESTION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_OTEL_INGESTION_SECONDARY_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_INGESTION_SECONDARY_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_DATA_RETENTION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_DEAD_LETTER_RETRY_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("false"),
QUEUE_CONSUMER_WEBHOOK_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_ENTITY_CHANGE_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_EVENT_PROPAGATION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
QUEUE_CONSUMER_NOTIFICATION_QUEUE_IS_ENABLED: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_DATASET_RUN_BACKFILL_CHUNK_SIZE: z.coerce
.number()
.positive()
.default(100),
LANGFUSE_EXPERIMENT_BACKFILL_THROTTLE_MS: z.coerce
.number()
.positive()
.default(5 * 60 * 1000), // 5 minutes
// Comma-separated list of project IDs to exclude from experiment backfill processing
LANGFUSE_EXPERIMENT_BACKFILL_EXCLUDE_PROJECT_IDS: z
.string()
.optional()
.transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
// Comma-separated list of project IDs to exclude from event propagation dual-write
LANGFUSE_EVENT_PROPAGATION_EXCLUDE_PROJECT_IDS: z
.string()
.optional()
.transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
LANGFUSE_EVENT_PROPAGATION_MAX_INSERT_THREADS: z.coerce
.number()
.int()
.positive()
.default(8),
// Optional propagation-only overrides; unset values use ClickHouse profile settings.
LANGFUSE_EVENT_PROPAGATION_MAX_BLOCK_SIZE: z.coerce
.number()
.int()
.positive()
.optional(),
LANGFUSE_EVENT_PROPAGATION_MIN_INSERT_BLOCK_SIZE_ROWS: z.coerce
.number()
.int()
.nonnegative()
.optional(),
LANGFUSE_EVENT_PROPAGATION_MIN_INSERT_BLOCK_SIZE_BYTES: z.coerce
.number()
.int()
.nonnegative()
.optional(),
// Core data S3 upload - Langfuse Cloud
LANGFUSE_S3_CORE_DATA_EXPORT_IS_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_CORE_DATA_UPLOAD_BUCKET: z.string().optional(),
LANGFUSE_S3_CORE_DATA_UPLOAD_PREFIX: z.string().default(""),
LANGFUSE_S3_CORE_DATA_UPLOAD_REGION: z.string().optional(),
LANGFUSE_S3_CORE_DATA_UPLOAD_ENDPOINT: z.string().optional(),
LANGFUSE_S3_CORE_DATA_UPLOAD_ACCESS_KEY_ID: z.string().optional(),
LANGFUSE_S3_CORE_DATA_UPLOAD_SECRET_ACCESS_KEY: z.string().optional(),
LANGFUSE_S3_CORE_DATA_UPLOAD_FORCE_PATH_STYLE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_CORE_DATA_UPLOAD_SSE: z.enum(["AES256", "aws:kms"]).optional(),
LANGFUSE_S3_CORE_DATA_UPLOAD_SSE_KMS_KEY_ID: z.string().optional(),
// Media upload
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: z.string().optional(),
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: z.string().default(""),
LANGFUSE_S3_MEDIA_UPLOAD_REGION: z.string().optional(),
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: z.string().optional(),
LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT: z.string().optional(),
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: z.string().optional(),
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: z.string().optional(),
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_MEDIA_UPLOAD_SSE: z.enum(["AES256", "aws:kms"]).optional(),
LANGFUSE_S3_MEDIA_UPLOAD_SSE_KMS_KEY_ID: z.string().optional(),
LANGFUSE_OBSERVATION_FIELD_OVERFLOW_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_OBSERVATION_FIELD_SIZE_LIMIT_BYTES: z.coerce
.number()
.int()
.positive()
.default(2 * 1024 * 1024),
// Metering data Postgres export - Langfuse Cloud
LANGFUSE_POSTGRES_METERING_DATA_EXPORT_IS_ENABLED: z
.enum(["true", "false"])
.default("false"),
// When disabled: Usage is still tracked in DB but no emails are sent and no orgs are blocked
// When enabled: Full enforcement (emails + blocking)
LANGFUSE_FREE_TIER_USAGE_THRESHOLD_ENFORCEMENT_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_CONCURRENT_READS: z.coerce.number().positive().default(50),
LANGFUSE_CLICKHOUSE_PROJECT_DELETION_CONCURRENCY_DURATION_MS: z.coerce
.number()
.positive()
.default(600_000), // 10 minutes
LANGFUSE_CLICKHOUSE_TRACE_DELETION_CONCURRENCY_DURATION_MS: z.coerce
.number()
.positive()
.default(120_000), // 2 minutes
LANGFUSE_CLICKHOUSE_DATASET_DELETION_CONCURRENCY_DURATION_MS: z.coerce
.number()
.positive()
.default(120_000), // 2 minutes
// Batch Project Cleaner configuration
LANGFUSE_BATCH_PROJECT_CLEANER_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_BATCH_PROJECT_CLEANER_CHECK_INTERVAL_MS: z.coerce
.number()
.positive()
.default(600_000), // 10 minutes between checks after successful processing
LANGFUSE_BATCH_PROJECT_CLEANER_SLEEP_ON_EMPTY_MS: z.coerce
.number()
.positive()
.default(3_600_000), // 1 hour sleep when there is no data to process
LANGFUSE_BATCH_PROJECT_CLEANER_PROJECT_LIMIT: z.coerce
.number()
.positive()
.default(1000), // Max projects per batch
LANGFUSE_BATCH_PROJECT_CLEANER_DELETE_TIMEOUT_MS: z.coerce
.number()
.positive()
.default(3_600_000), // 1 hour for DELETE operations
// Batch Project Media Cleaner configuration (S3/PostgreSQL)
LANGFUSE_BATCH_PROJECT_MEDIA_CLEANER_BATCH_SIZE: z.coerce
.number()
.positive()
.default(5000), // Media items per chunk
// Batch Data Retention Cleaner configuration (ClickHouse)
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_INTERVAL_MS: z.coerce
.number()
.positive()
.default(3_600_000), // 1 hour between runs
LANGFUSE_MEDIA_RETENTION_CLEANER_INTERVAL_MS: z.coerce
.number()
.positive()
.default(600_000), // 10 minutes between runs
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_PROJECT_LIMIT: z.coerce
.number()
.positive()
.default(100), // Max projects per batch DELETE
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_CHUNK_SIZE: z.coerce
.number()
.positive()
.default(100), // Chunk size for counting projects in ClickHouse
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_QUERY_CONCURRENCY: z.coerce
.number()
.int()
.positive()
.default(2), // Max concurrent query pipelines per table cleaner
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_CANDIDATE_QUERY_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(180_000), // 3 minutes for candidate and enrichment queries
LANGFUSE_BATCH_DATA_RETENTION_CLEANER_DELETE_TIMEOUT_MS: z.coerce
.number()
.positive()
.default(3_600_000), // 1 hour for DELETE operations
// ClickHouse deleted-mask cleaner configuration
LANGFUSE_CLICKHOUSE_DELETED_MASK_CLEANER_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_CLICKHOUSE_DELETED_MASK_CLEANER_INTERVAL_MS: z.coerce
.number()
.positive()
.default(3_600_000), // 1 hour between runs
LANGFUSE_CLICKHOUSE_DELETED_MASK_CLEANER_SUBMIT_TIMEOUT_MS: z.coerce
.number()
.positive()
.default(60_000), // Wait up to 1 minute for ALTER submission; mutation can run for hours
LANGFUSE_CLICKHOUSE_DELETED_MASK_CLEANER_CLUSTER_MODE_ENABLED: z
.enum(["true", "false"])
.default("false"), // Use ON CLUSTER and clusterAllReplicas for cleaner operations
// Audit log relay: moves audit_log_staging rows into ClickHouse audit_logs.
// Runs only in cloud deployments (NEXT_PUBLIC_LANGFUSE_CLOUD_REGION set),
// where it is on unless disabled here.
LANGFUSE_AUDIT_LOG_RELAY_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_AUDIT_LOG_RELAY_INTERVAL_MS: z.coerce
.number()
.int()
.positive()
.default(10_000),
// Tasks without the lease check it every half TTL, and a batch must finish
// within half of it.
LANGFUSE_AUDIT_LOG_RELAY_LOCK_TTL_SECONDS: z.coerce
.number()
.int()
.positive()
.default(60),
// Media Retention Cleaner configuration (S3/PostgreSQL)
LANGFUSE_MEDIA_RETENTION_CLEANER_ITEM_LIMIT: z.coerce
.number()
.positive()
.default(10_000), // Max items (media files) to process per batch
// Batch Trace Deletion Cleaner configuration
LANGFUSE_BATCH_TRACE_DELETION_CLEANER_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_BATCH_TRACE_DELETION_CLEANER_INTERVAL_MS: z.coerce
.number()
.positive()
.default(600_000), // 10 minutes between runs
LANGFUSE_BATCH_TRACE_DELETION_CLEANER_LOCK_TTL_SECONDS: z.coerce
.number()
.positive()
.default(7200), // 2 hours to handle worst-case deletions
LANGFUSE_TRACE_DELETE_BATCH_ACTION_RUNNER_ENABLED: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_TRACE_DELETE_BATCH_ACTION_RUNNER_INTERVAL_MS: z.coerce
.number()
.positive()
.default(10_000),
LANGFUSE_TRACE_DELETE_BATCH_ACTION_RUNNER_LOCK_TTL_SECONDS: z.coerce
.number()
.positive()
.default(1_800),
LANGFUSE_TRACE_DELETE_BATCH_ACTION_RUNNER_MAX_BATCHES_PER_RUN: z.coerce
.number()
.positive()
.default(5),
// V4 migration flags. See LFE-9778.
// Defaults reflect the Langfuse v4 target state: net-new deployments write
// straight into the events tables. The v3 line ships these as `legacy` /
// `dual_write` / `false`; local dev and CI pin explicit values via
// .env.dev*.example, so these defaults only apply to bare deployments.
LANGFUSE_MIGRATION_V4_WRITE_MODE: z
.enum(["legacy", "dual", "events_only"])
.default("events_only"),
LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR: z
.enum(["dual_write", "direct"])
.default("direct"),
// Cloud-only rollout boundary for automatic direct OTel event writes.
// Organizations created on or after this date are past the point where the v4
// preview is force-enabled and cannot be switched off, so the events table is
// the only surface they read; their OTLP traffic therefore takes the direct
// write even without an `x-langfuse-ingestion-version: 4` header. Applies to
// non-Langfuse-SDK exports only — an older SDK keeps its established
// dual-write shape. An ISO date (YYYY-MM-DD) read as midnight UTC; a plain
// date is enough precision and easier to reason about than a timestamp.
// Unset disables the rule, which is the right default when self-hosting:
// those deployments move the whole deployment at once via
// LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct instead of rolling a
// tenant cohort forward.
LANGFUSE_MIGRATION_V4_OTEL_DIRECT_WRITE_ORG_CREATED_CUTOFF: z.iso
.date()
.optional(),
LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN: z
.enum(["true", "false"])
.default("true"),
// Background-migration env gates. Names share the LANGFUSE_BACKGROUND_MIGRATION_
// prefix so the BackgroundMigrationManager can discover them by scanning env
// keys; each gates one or more rows in the background_migrations table via
// `args.envGate`. The historic backfill defaults on in v4 (it is a no-op for
// net-new deployments with no legacy data); the pid/tid sorting-table cleanup
// stays opt-in so its intermediate artifacts are only dropped once the
// operator confirms the backfill succeeded.
LANGFUSE_BACKGROUND_MIGRATION_V4_ENABLE_HISTORIC_BACKFILL: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_BACKGROUND_MIGRATION_V4_DROP_PID_TID_SORTING_TABLES: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_EXPERIMENT_EVENT_PROPAGATION_PARTITION_DELAY_MINUTES: z.coerce
.number()
.positive()
.int()
.default(10),
// Health-check threshold for the event-propagation ("dual write") job. When a
// client opts in via /api/health?failIfEventPropagationStuck=true, the check
// returns 503 if the heartbeat has not been refreshed within this many minutes,
// letting k8s liveness probes restart a container whose global-concurrency
// slot is wedged. The heartbeat is refreshed at the top of every invocation and
// per-chunk during the experiment backfill, so the threshold only needs to
// exceed the longest un-heartbeated step — a single CH INSERT (request_timeout
// 30 min). 35 min leaves headroom.
//
// Probes using this flag MUST set initialDelaySeconds >= 60s (one cron cycle):
// the heartbeat is only refreshed when the minute-boundary cron next runs, so a
// just-restarted (or just-re-enabled) container can carry a stale value until
// then. A shorter delay can crash-loop the very restart this check triggers.
LANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES: z.coerce
.number()
.positive()
.int()
.default(35),
// Liveness threshold for the opt-in ?failIfQueueConsumptionStuck=true health
// check: fail once this container's BullMQ workers have neither picked up nor
// completed a single job for this long. Default-on repeatable jobs keep a
// healthy worker busy at least once per hour (blob storage integration
// scheduler every 20 min, PostHog/Mixpanel schedulers hourly), so an hour of
// total silence indicates a wedged worker.
// In multi-replica deployments each scheduler tick lands
// on only one replica — raise the threshold if replicas can legitimately sit
// idle (no ingestion or other traffic) for extended periods.
LANGFUSE_QUEUE_CONSUMPTION_STUCK_THRESHOLD_MINUTES: z.coerce
.number()
.positive()
.int()
.default(60),
LANGFUSE_WEBHOOK_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
LANGFUSE_WEBHOOK_TIMEOUT_MS: z.coerce.number().positive().default(10000),
LANGFUSE_WEBHOOK_MAX_REDIRECTS: z.coerce.number().positive().default(10),
LANGFUSE_ENTITY_CHANGE_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(2),
LANGFUSE_MONITOR_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(10),
LANGFUSE_IN_APP_AGENT_RUN_QUEUE_PROCESSING_CONCURRENCY: z.coerce
.number()
.positive()
.default(5),
// Default 15 minutes. Do not go below the heartbeat-stale window (60s) or a
// live worker can lose the race. Faster also adds no resolution: every
// deadline this runner reports against is 5 minutes or longer.
LANGFUSE_IN_APP_AGENT_INTEGRITY_RUNNER_INTERVAL_MS: z.coerce
.number()
.positive()
.default(15 * 60_000),
LANGFUSE_IN_APP_AGENT_DLQ_RETRY_INTERVAL_MS: z.coerce
.number()
.positive()
.default(600_000),
LANGFUSE_DELETE_BATCH_SIZE: z.coerce.number().positive().default(2000),
LANGFUSE_TOKEN_COUNT_WORKER_POOL_SIZE: z.coerce
.number()
.positive()
.default(2),
/** Interval at which one worker per queue set polls queue depth and DLQ age */
LANGFUSE_QUEUE_METRICS_INTERVAL_MS: z.coerce.number().min(100).default(1000),
LANGFUSE_QUEUE_METRICS_ENABLED: z.enum(["true", "false"]).default("true"),
// Upper bound for a random delay before the worker registers its queues and
// starts its periodic runners. Spreads the Redis connection setup of tasks
// that boot together (e.g. an autoscaling step) over time. 0 disables it.
// Keep it below the container health check grace period: the HTTP server
// only starts listening after the delay.
LANGFUSE_WORKER_STARTUP_JITTER_MAX_MS: z.coerce
.number()
.int()
.min(0)
.max(120_000)
.default(0),
});
type ParsedEnv = z.infer<typeof EnvSchema>;
// V4 migration flag helpers.
export const v4WritesToEventsTable = (envValue: ParsedEnv): boolean =>
envValue.LANGFUSE_MIGRATION_V4_WRITE_MODE !== "legacy";
export const v4WritesToLegacyTables = (envValue: ParsedEnv): boolean =>
envValue.LANGFUSE_MIGRATION_V4_WRITE_MODE !== "events_only";
export const v4ForceDirectOtelWrite = (envValue: ParsedEnv): boolean =>
envValue.LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR === "direct";
const v4AllowPreviewOptIn = (envValue: ParsedEnv): boolean =>
envValue.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN === "true";
const validateV4Flags = (parsed: ParsedEnv): void => {
const mode = parsed.LANGFUSE_MIGRATION_V4_WRITE_MODE;
const otel = parsed.LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR;
// Hard errors: combinations that would silently lose data.
if (mode === "legacy" && otel === "direct") {
throw new Error(
"Invalid V4 config: LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct " +
"requires LANGFUSE_MIGRATION_V4_WRITE_MODE in {dual, events_only}. " +
"Direct OTel writes target events_full, which is not read in legacy mode.",
);
}
if (mode === "events_only" && otel === "dual_write") {
throw new Error(
"Invalid V4 config: LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=dual_write " +
"is incoherent with LANGFUSE_MIGRATION_V4_WRITE_MODE=events_only " +
"(would dual-write to legacy tables the deployment otherwise skips).",
);
}
if (mode === "events_only" && !v4AllowPreviewOptIn(parsed)) {
throw new Error(
"Invalid V4 config: LANGFUSE_MIGRATION_V4_WRITE_MODE=events_only requires " +
"LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true. Web reads are gated " +
"solely on the opt-in flag; without it they target the legacy " +
"traces/observations tables that events_only mode no longer writes to.",
);
}
};
const validateInAppAgentSandboxConfig = (parsed: ParsedEnv): void => {
if (parsed.LANGFUSE_IN_APP_AGENT_SANDBOX_PROVIDER !== "lambda-microvm") {
return;
}
if (
!parsed.LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_IMAGE_IDENTIFIER ||
!parsed.LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_EXECUTION_ROLE_ARN ||
!parsed.LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_REGION
) {
throw new Error(
"Invalid lambda-microvm sandbox config: image identifier, execution role ARN, and region are required.",
);
}
};
const parseEnv = (): ParsedEnv => {
const source = { ...removeEmptyEnvVariables(process.env) };
if (source.LANGFUSE_TRACE_BATCH_IDLE_MS === undefined) {
source.LANGFUSE_TRACE_BATCH_IDLE_MS =
source.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION === "DEV" ? "120000" : "600000";
}
if (source.LANGFUSE_TRACE_BATCH_SHARD_COUNT === undefined) {
source.LANGFUSE_TRACE_BATCH_SHARD_COUNT =
source.REDIS_CLUSTER_ENABLED === "true" ? "16" : "1";
}
const parsed = EnvSchema.parse(source);
validateV4Flags(parsed);
validateInAppAgentSandboxConfig(parsed);
return parsed;
};
export const env: ParsedEnv =
process.env.DOCKER_BUILD === "1" // eslint-disable-line turbo/no-undeclared-env-vars
? (process.env as any)
: parseEnv();