🪢 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 { z } from "zod";
import { parseBlockedCidr } from "./server/webhooks/parseBlockedCidr";
import { removeEmptyEnvVariables } from "./utils/environment";
// Per-segment byte budget for S3 event keys. Off by default (2048 > 800-byte
// idSchema cap). Lower to 255 for MinIO on ext4. Affects only new writes —
// existing objects are read by recorded path, not reconstructed.
// Shared with worker/src/env.ts to keep validation rules identical.
export const langfuseS3EventKeyMaxSegmentBytesSchema = z.coerce
.number()
.int()
.min(64)
.max(2048)
.default(2048);
// Socket-level watchdog for all Redis connections: ioredis destroys and
// reconnects a socket that received no data for this long, so a hung
// connection cannot pin BullMQ concurrency slots forever. Must be 0 (disabled)
// or >= 10s: BullMQ blocking commands (BZPOPMIN) legitimately idle ~5s between
// packets, and lower values make healthy idle workers cycle through
// reconnects (#12944).
export const redisSocketTimeoutMsSchema = z.coerce
.number()
.int()
.refine((ms) => ms === 0 || ms >= 10_000, {
message:
"REDIS_SOCKET_TIMEOUT_MS must be 0 (disabled) or at least 10000; BullMQ blocking commands idle ~5s between packets",
})
.default(30_000);
function commaSeparatedLowercase(value: string | undefined): string[] {
if (!value) return [];
return value
.split(",")
.map((part) => part.toLowerCase().trim())
.filter((part) => part.length > 0);
}
const optionalCommaSeparatedLowercase = z
.string()
.optional()
.transform(commaSeparatedLowercase);
function isCidr(value: string): boolean {
return parseBlockedCidr(value) !== undefined;
}
const DEFAULT_LLM_COMPLETION_TIMEOUT_MS = 120_000;
const EnvSchema = z.object({
NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: z.string().optional(),
// Dev-only override: set to an ISO datetime string to shift the legacy blob
// export cutoff for local testing (e.g. "2020-01-01T00:00:00.000Z" makes
// every project post-cutoff; "2099-01-01T00:00:00.000Z" grandfathers all).
NEXT_PUBLIC_LANGFUSE_BLOB_EXPORT_CUTOFF: z.iso.datetime().optional(),
// Same, for the integration-level cutoff (BlobStorageIntegration.createdAt).
NEXT_PUBLIC_LANGFUSE_BLOB_EXPORTER_CUTOFF: z.iso.datetime().optional(),
NEXT_PUBLIC_LANGFUSE_ANALYTICS_EXPORTER_CUTOFF: z.iso.datetime().optional(),
NODE_ENV: z
.enum(["development", "test", "production"])
.default("development"),
NEXTAUTH_URL: z.url().optional(),
// Internal Topics PoC controls; not a supported self-hosting configuration.
LANGFUSE_TOPICS_ENABLED: z.enum(["true", "false"]).default("false"),
LANGFUSE_TOPICS_ENABLED_PROJECT_IDS: z
.string()
.default("")
.transform((value) =>
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
),
LANGFUSE_TOPICS_TRACING_ENABLED_PROJECT_IDS: z
.string()
.default("")
.transform((value) =>
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
),
LANGFUSE_TOPICS_REDIS_TTL_SECONDS: z.coerce
.number()
.int()
.positive()
.default(10800),
// NextAuth.js falls back to VERCEL_URL when NEXTAUTH_URL is unset; the
// shared base-URL helper mirrors that (see web/src/env.mjs preprocess).
VERCEL_URL: z.string().optional(),
EMAIL_FROM_ADDRESS: z.string().optional(),
// Standard SMTP URL (`smtp://`, `smtps://`) or `ses://<region>` to send via
// AWS SES using the default AWS credential chain (IAM role, SSO, env vars).
// Example: `ses://us-east-1`.
SMTP_CONNECTION_URL: z.string().optional(),
CLOUD_CRM_EMAIL: z.string().optional(),
REDIS_HOST: z.string().nullish(),
REDIS_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(6379)
.nullable(),
REDIS_AUTH: z.string().nullish(),
REDIS_USERNAME: z.string().nullish(),
REDIS_CONNECTION_STRING: z.string().nullish(),
// Optional prefix for Redis keys. Used by BullMQ queues via their native prefix option
// and by the singleton cache instance via ioredis keyPrefix. Useful for multi-tenant Redis.
REDIS_KEY_PREFIX: z.string().nullish(),
REDIS_TLS_ENABLED: z.enum(["true", "false"]).default("false"),
REDIS_TLS_CA_PATH: z.string().optional(),
REDIS_TLS_CERT_PATH: z.string().optional(),
REDIS_TLS_KEY_PATH: z.string().optional(),
REDIS_TLS_SERVERNAME: z.string().optional(),
REDIS_TLS_REJECT_UNAUTHORIZED: z.enum(["true", "false"]).optional(),
REDIS_TLS_CHECK_SERVER_IDENTITY: z.enum(["true", "false"]).optional(),
REDIS_TLS_SECURE_PROTOCOL: z.string().optional(),
REDIS_TLS_CIPHERS: z.string().optional(),
REDIS_TLS_HONOR_CIPHER_ORDER: z.enum(["true", "false"]).optional(),
REDIS_TLS_KEY_PASSPHRASE: z.string().optional(),
REDIS_ENABLE_AUTO_PIPELINING: z.enum(["true", "false"]).default("true"),
REDIS_SOCKET_TIMEOUT_MS: redisSocketTimeoutMsSchema,
LANGFUSE_BULLMQ_SKIP_REDIS_VERSION_CHECK: z
.enum(["true", "false"])
.default("false"),
// Redis Cluster Configuration
REDIS_CLUSTER_ENABLED: z.enum(["true", "false"]).default("false"),
REDIS_CLUSTER_NODES: z.string().optional(),
REDIS_CLUSTER_SLOTS_REFRESH_TIMEOUT: z.coerce
.number()
.int()
.positive()
.default(5000),
REDIS_SENTINEL_ENABLED: z.enum(["true", "false"]).default("false"),
REDIS_SENTINEL_TLS_ENABLED: z.enum(["true", "false"]).default("false"),
REDIS_SENTINEL_NODES: z.string().optional(),
REDIS_SENTINEL_MASTER_NAME: z.string().optional(),
REDIS_SENTINEL_USERNAME: z.string().optional(),
REDIS_SENTINEL_PASSWORD: z.string().optional(),
ENCRYPTION_KEY: z
.string()
.length(
64,
"ENCRYPTION_KEY must be 256 bits, 64 string characters in hex format, generate via: openssl rand -hex 32",
)
.optional(),
LANGFUSE_CACHE_MODEL_MATCH_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_CACHE_MODEL_MATCH_TTL_SECONDS: z.coerce.number().default(86400), // 24 hours
LANGFUSE_LOCAL_CACHE_MODEL_MATCH_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_LOCAL_CACHE_MODEL_MATCH_TTL_MS: z.coerce
.number()
.positive()
.default(10_000),
LANGFUSE_LOCAL_CACHE_MODEL_MATCH_MAX: z.coerce
.number()
.int()
.positive()
.default(20_000),
LANGFUSE_CACHE_PROMPT_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_CACHE_PROMPT_TTL_SECONDS: z.coerce.number().default(3600), // 1h
LANGFUSE_CACHE_SKILL_ENABLED: z.enum(["true", "false"]).default("true"),
LANGFUSE_CACHE_SKILL_TTL_SECONDS: z.coerce
.number()
.int()
.positive()
.default(3600), // 1h
CLICKHOUSE_URL: z.url(),
CLICKHOUSE_READ_ONLY_URL: z.url().optional(),
CLICKHOUSE_EVENTS_READ_ONLY_URL: z.url().optional(),
CLICKHOUSE_CLUSTER_ENABLED: z.enum(["true", "false"]).default("true"),
CLICKHOUSE_CLUSTER_NAME: z.string().default("default"),
CLICKHOUSE_DB: z.string().default("default"),
CLICKHOUSE_USER: z.string(),
CLICKHOUSE_PASSWORD: z.string(),
CLICKHOUSE_KEEP_ALIVE_IDLE_SOCKET_TTL: z.coerce.number().int().default(9000),
CLICKHOUSE_MAX_OPEN_CONNECTIONS: z.coerce.number().int().default(25),
LANGFUSE_JSON_BAD_UNICODE_ESCAPE: z
.enum(["auto", "no_throw", "sanitize"])
.optional(),
// Optional to allow for server-setting fallbacks
CLICKHOUSE_ASYNC_INSERT_MAX_DATA_SIZE: z.string().optional(),
CLICKHOUSE_ASYNC_INSERT_BUSY_TIMEOUT_MS: z.coerce.number().int().optional(),
CLICKHOUSE_ASYNC_INSERT_BUSY_TIMEOUT_MIN_MS: z.coerce
.number()
.int()
.min(50)
.optional(),
CLICKHOUSE_LIGHTWEIGHT_DELETE_MODE: z
.enum(["alter_update", "lightweight_update", "lightweight_update_force"])
.default("alter_update"),
CLICKHOUSE_USE_LIGHTWEIGHT_UPDATE: z.enum(["true", "false"]).default("false"),
CLICKHOUSE_UPDATE_PARALLEL_MODE: z
.enum(["sync", "async", "auto"])
.default("auto"),
// Workarounds for ClickHouse version-specific parser and analyzer bugs. In
// "auto", Langfuse detects the ClickHouse version on startup and applies
// known compatibility settings for affected version bands.
CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION: z
.enum(["auto", "true", "false"])
.default("auto"),
CLICKHOUSE_DISABLE_TOP_K_THROUGH_JOIN: z
.enum(["auto", "true", "false"])
.default("auto"),
// Read-time skip-index evaluation, applied only from the version that fixes
// the patch-part read bug. See the compatibility rule for details.
CLICKHOUSE_ENABLE_SKIP_INDEXES_ON_DATA_READ: z
.enum(["auto", "true", "false"])
.default("auto"),
CLICKHOUSE_MAX_BYTES_BEFORE_EXTERNAL_GROUP_BY: z.coerce
.number()
.default(32_000_000_000), // ~32GB
CLICKHOUSE_USE_QUERY_CONDITION_CACHE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_ENABLE_SINGLE_LEVEL_QUERY_OPTIMIZATION: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_ROOT_EVENT_CONDITION_MAX_WINDOW_HOURS: z.coerce
.number()
.int()
.nonnegative()
.default(168), // 7 days
LANGFUSE_INGESTION_QUEUE_DELAY_MS: z.coerce
.number()
.nonnegative()
.default(15_000),
LANGFUSE_INGESTION_QUEUE_SHARD_COUNT: z.coerce.number().positive().default(1),
LANGFUSE_INGESTION_SECONDARY_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_OTEL_INGESTION_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_OTEL_INGESTION_SECONDARY_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_OTEL_MAX_SPAN_BYTES: z.coerce.number().positive().default(9_500_000), // 9.5MB — just under ClickHouse's 10MB min_chunk_bytes_for_parallel_parsing default
LANGFUSE_EVAL_EXECUTION_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_EVAL_EXECUTION_SECONDARY_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_LLM_AS_JUDGE_EXECUTION_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_CODE_EVAL_EXECUTION_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_CODE_EVAL_DISPATCHER: z
.enum(["insecure-local", "aws-lambda"])
.optional(),
LANGFUSE_CODE_EVAL_AWS_LAMBDA_ENDPOINT: z.string().optional(),
LANGFUSE_CODE_EVAL_AWS_LAMBDA_NODE_FUNCTION_NAME: z
.string()
.default("code-based-eval-executor-node"),
LANGFUSE_CODE_EVAL_AWS_LAMBDA_PYTHON_FUNCTION_NAME: z
.string()
.default("code-based-eval-executor-python"),
LANGFUSE_CODE_EVAL_LOCAL_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(2_000),
LANGFUSE_TRACE_UPSERT_QUEUE_SHARD_COUNT: z.coerce
.number()
.positive()
.default(1),
LANGFUSE_TRACE_UPSERT_QUEUE_ATTEMPTS: z.coerce.number().positive().default(2),
LANGFUSE_TRACE_DELETE_DELAY_MS: z.coerce
.number()
.nonnegative()
.default(5_000),
LANGFUSE_LARGE_PROJECT_IDS: z
.string()
.default("")
.transform(
(value) =>
new Set(
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
),
),
LANGFUSE_DELETE_SKIP_PROJECT_IDS: z
.string()
.optional()
.transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
// Has no effect in events_only mode, where the v3 experience cannot work.
LANGFUSE_FORCE_V3_EXPERIENCE: z
.string()
.optional()
.transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
SALT: z.string().optional(), // used by components imported by web package
LANGFUSE_LOG_LEVEL: z
.enum(["trace", "debug", "info", "warn", "error", "fatal"])
.optional(),
LANGFUSE_LOG_FORMAT: z.enum(["text", "json"]).default("text"),
LANGFUSE_LOG_PROPAGATED_HEADERS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
ENABLE_AWS_CLOUDWATCH_METRIC_PUBLISHING: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_CONCURRENT_WRITES: z.coerce.number().positive().default(50),
LANGFUSE_S3_UPLOAD_ENABLE_BUFFERED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_UPLOAD_MAX_PART_ATTEMPTS: z.coerce
.number()
.min(1)
.max(10)
.default(3),
LANGFUSE_S3_UPLOAD_MAX_CONCURRENT_PARTS: z.coerce
.number()
.min(1)
.max(10)
.default(3),
LANGFUSE_S3_EVENT_UPLOAD_BUCKET: z.string(), // Langfuse requires a bucket name for S3 Event Uploads.
LANGFUSE_S3_EVENT_UPLOAD_PREFIX: z.string().default(""),
LANGFUSE_TRACE_BATCH_TRANSCRIPT_STORAGE_REQUEST_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(10_000), // 10 seconds
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(),
LANGFUSE_S3_EVENT_KEY_MAX_SEGMENT_BYTES:
langfuseS3EventKeyMaxSegmentBytesSchema,
LANGFUSE_OTEL_MEDIA_UPLOAD_CONCURRENCY: z.coerce
.number()
.int()
.positive()
.default(100),
LANGFUSE_OTEL_MEDIA_UPLOAD_MAX_BYTES: z.coerce
.number()
.int()
.positive()
.default(128 * 1024 * 1024),
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_S3_MEDIA_UPLOAD_REQUEST_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(30_000),
LANGFUSE_USE_AZURE_BLOB: z.enum(["true", "false"]).default("false"),
LANGFUSE_AZURE_SKIP_CONTAINER_CHECK: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_USE_GOOGLE_CLOUD_STORAGE: z.enum(["true", "false"]).default("false"),
LANGFUSE_GOOGLE_CLOUD_STORAGE_CREDENTIALS: z.string().optional(),
GOOGLE_CLOUD_UNIVERSE_DOMAIN: z.string().default("googleapis.com"),
LANGFUSE_USE_OCI_NATIVE_OBJECT_STORAGE: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_OCI_AUTH_TYPE: z
.enum([
"workload_identity",
"instance_principal",
"resource_principal",
"oci_profile",
"session_token",
])
.optional(),
LANGFUSE_OCI_CONFIG_FILE: z.string().optional(),
LANGFUSE_OCI_CONFIG_PROFILE: z.string().optional(),
NODE_EXTRA_CA_CERTS: z.string().optional(),
STRIPE_SECRET_KEY: z.string().optional(),
LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG: z
.enum(["true", "false"])
.default("true"),
// Max concurrent S3 deleteFiles requests the blob-storage cleanup consumer
// keeps in flight. Bounds memory and backpressures the ClickHouse ref stream.
LANGFUSE_BLOB_STORAGE_DELETE_S3_CONCURRENCY: z.coerce
.number()
.min(1)
.max(20)
.default(5),
// V4 write mode. Mirrors worker/src/env.ts so the web package can gate
// public API routes that rely on the legacy traces/observations tables.
// The worker owns the writes; the web only needs to know whether legacy
// tables are still being populated to decide whether to serve reads.
// Defaults to `events_only` for the v4 target state (v3 shipped `legacy`);
// keep this value in sync with worker/src/env.ts and web/src/env.mjs.
LANGFUSE_MIGRATION_V4_WRITE_MODE: z
.enum(["legacy", "dual", "events_only"])
.default("events_only"),
LANGFUSE_S3_LIST_MAX_KEYS: z.coerce.number().positive().default(200),
// Checksum algorithm for S3 DeleteObjects requests; unset keeps the SDK
// default (CRC32). Some S3-compatible stores reject CRC32 with 400
// MissingContentMD5 and need "MD5" (sent as the legacy Content-MD5 header),
// e.g. MinIO before RELEASE.2025-02-03 (langfuse/langfuse-k8s#356). MD5 is
// unavailable on FIPS runtimes; stores that support it also accept e.g.
// SHA256 as a FIPS-approved alternative.
LANGFUSE_S3_DELETE_OBJECTS_CHECKSUM_ALGORITHM: z
.enum(["MD5", "CRC32", "CRC32C", "CRC64NVME", "SHA1", "SHA256"])
.optional(),
LANGFUSE_S3_RATE_ERROR_SLOWDOWN_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_RATE_ERROR_SLOWDOWN_TTL_SECONDS: z.coerce
.number()
.positive()
.default(3600), // 1 hour
LANGFUSE_INGEST_FAILURE_PROJECT_TTL_SECONDS: z.coerce
.number()
.int()
.gt(60)
.default(600), // 10 minutes
LANGFUSE_S3_CORE_DATA_EXPORT_IS_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_S3_CORE_DATA_EXPORT_SSE: z.enum(["AES256", "aws:kms"]).optional(),
LANGFUSE_S3_CORE_DATA_EXPORT_SSE_KMS_KEY_ID: z.string().optional(),
LANGFUSE_POSTGRES_METERING_DATA_EXPORT_IS_ENABLED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_CUSTOM_SSO_EMAIL_CLAIM: z.string().default("email"),
LANGFUSE_CUSTOM_SSO_NAME_CLAIM: z.string().default("name"),
LANGFUSE_CUSTOM_SSO_SUB_CLAIM: z.string().default("sub"),
LANGFUSE_CUSTOM_SSO_IMAGE_CLAIM: z.string().default("picture"),
LANGFUSE_API_TRACE_OBSERVATIONS_SIZE_LIMIT_BYTES: z.coerce
.number()
.default(80e6), // 80MB
// How many observations the trace detail view loads (startTime ASC, so the
// chronological tail is what a bigger trace loses). Also a crash guard: the
// client builds one node per observation before it renders.
LANGFUSE_MAX_OBSERVATIONS_PER_TRACE: z.coerce
.number()
.int()
.positive()
.default(20_000),
LANGFUSE_CLICKHOUSE_DELETION_TIMEOUT_MS: z.coerce.number().default(600_000), // 10 minutes
LANGFUSE_CLICKHOUSE_QUERY_MAX_ATTEMPTS: z.coerce.number().default(3), // Maximum attempts for socket hang up errors
LANGFUSE_SKIP_S3_LIST_FOR_OBSERVATIONS_PROJECT_IDS: z.string().optional(),
LANGFUSE_INGESTION_PROCESSING_SAMPLED_PROJECTS: z
.string()
.optional()
.transform((val) => {
try {
if (!val) return new Map<string, number>();
const map = new Map<string, number>();
const parts = val.split(",");
for (const part of parts) {
const [projectId, sampleRateStr] = part.split(":");
if (!projectId || sampleRateStr === undefined) {
throw new Error(`Invalid format: ${part}`);
}
// Validate sample rate is between 0 and 1
const sampleRate = z.coerce
.number()
.min(0)
.max(1)
.parse(sampleRateStr);
map.set(projectId, sampleRate);
}
return map;
} catch {
return new Map<string, number>();
}
}),
LANGFUSE_WEBHOOK_WHITELISTED_IPS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_WEBHOOK_WHITELISTED_IP_SEGMENTS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_WEBHOOK_WHITELISTED_HOST: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
// When non-empty, webhook URLs must use one of these hosts. Distinct from
// LANGFUSE_WEBHOOK_WHITELISTED_HOST, which only exempts a host from the
// private-address block. Does not apply to other callers of that exemption
// list. Entries are exact hostnames (no scheme or port; IPv6 in brackets).
LANGFUSE_WEBHOOK_ALLOWED_HOSTS: optionalCommaSeparatedLowercase,
LANGFUSE_LLM_CONNECTION_WHITELISTED_IPS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_LLM_CONNECTION_WHITELISTED_IP_SEGMENTS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_LLM_CONNECTION_WHITELISTED_HOST: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
// When non-empty, every outbound LLM request must use one of these hosts,
// including provider default hosts and Langfuse AI. Bedrock checks
// bedrock-runtime.<region>.<partition>, or the host of
// AWS_ENDPOINT_URL_BEDROCK_RUNTIME / AWS_ENDPOINT_URL when one of those is
// set. Ignored on Langfuse Cloud, same as the LLM exemption list above.
LANGFUSE_LLM_CONNECTION_ALLOWED_HOSTS: optionalCommaSeparatedLowercase,
LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IPS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_HOST: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
// When non-empty, blob storage export endpoints must use one of these hosts,
// and blob endpoint validation is on. Listed hosts may resolve to private
// addresses. Bucket names under a listed host ({bucket}.{host}) are allowed
// too, but still may not resolve to a private address unless it is in
// LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IPS / _IP_SEGMENTS; private
// S3-compatible stores can use path-style instead. S3 exports without a
// custom endpoint connect to s3.<region>.amazonaws.com, which must then be
// listed; region "auto" first connects to s3.us-east-1.amazonaws.com. S3
// exports using host credentials (web identity or an assumed role) also
// call sts.<region>.amazonaws.com through the same check, so list it too.
// GCS exports always connect to Google and are not checked. Ignored on
// Langfuse Cloud.
LANGFUSE_BLOB_STORAGE_ENDPOINT_ALLOWED_HOSTS: optionalCommaSeparatedLowercase,
LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
// When non-empty, external media storage endpoints must use one of these
// hosts. Ignored on Langfuse Cloud.
LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_ALLOWED_HOSTS:
optionalCommaSeparatedLowercase,
// Buckets that keyless GOOGLE_CLOUD_STORAGE blob exports (default credentials,
// no service account key) may write to. Those run as the deployment's own GCP
// identity (ADC), so without this allowlist any project owner could export into
// any bucket that identity can write. Empty disables keyless GCS exports;
// exports with a service account key are unaffected.
LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS: z
.string()
.optional()
.transform((s) =>
s
? s
.split(",")
.map((s) => s.toLowerCase().trim())
.filter(Boolean)
: [],
),
LANGFUSE_SSO_DISCOVERY_WHITELISTED_IPS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_SSO_DISCOVERY_WHITELISTED_IP_SEGMENTS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
LANGFUSE_SSO_DISCOVERY_WHITELISTED_HOST: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
// Extra CIDR ranges merged into the private-address block for outbound URL
// checks that already run. Blob storage stays opt-in: these ranges apply
// there only when a blob endpoint exemption or allowed-hosts list turns
// blob endpoint validation on. Exemptions
// in the per-surface *_WHITELISTED_* lists still win.
LANGFUSE_OUTBOUND_BLOCKED_IP_SEGMENTS: optionalCommaSeparatedLowercase.refine(
(segments) => segments.every(isCidr),
{
message:
"LANGFUSE_OUTBOUND_BLOCKED_IP_SEGMENTS must be a comma-separated list of CIDR ranges",
},
),
SLACK_CLIENT_ID: z.string().optional(),
SLACK_CLIENT_SECRET: z.string().optional(),
SLACK_STATE_SECRET: z.string().optional(),
SLACK_PAGE_SIZE: z.coerce
.number()
.positive()
.int()
.max(1000)
.optional()
.default(1000) // Use high default to minimize number of API calls and hence avoid rate limits
.describe("Number of channels to fetch per Slack API page"),
HTTPS_PROXY: z.string().optional(),
// Hosts that must be reached directly instead of through HTTPS_PROXY,
// using the standard NO_PROXY grammar (undici EnvHttpProxyAgent
// semantics). The lowercase variant wins when both are set, mirroring
// undici and curl.
NO_PROXY: z.string().optional(),
no_proxy: z.string().optional(),
LANGFUSE_SERVER_SIDE_IO_CHAR_LIMIT: z.coerce
.number()
.int()
.positive()
.default(1_000),
LANGFUSE_CLICKHOUSE_DATA_EXPORT_REQUEST_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(3_600_000), // 60 minutes
LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS: z.coerce
.number()
.int()
.positive()
.default(DEFAULT_LLM_COMPLETION_TIMEOUT_MS), // 2 minutes
// LANGFUSE_AI_PROVIDER is optional at boot. Unset means unconfigured;
// bedrock requires LANGFUSE_AI_PROVIDER=bedrock.
// LANGFUSE_AI_MODEL / LANGFUSE_AI_SMALL_MODEL / LANGFUSE_AI_AWS_BEDROCK_REGION
// apply to all providers. LANGFUSE_AI_API_KEY / LANGFUSE_AI_BASE_URL /
// LANGFUSE_AI_EXTRA_HEADERS apply to anthropic and openai.
// LANGFUSE_AI_USE_RESPONSES_API applies to openai only.
// LANGFUSE_AI_VERTEX_LOCATION applies to vertex only; like bedrock, vertex
// authenticates through the instance credential chain (GCP application
// default credentials) and takes no key.
LANGFUSE_AI_PROVIDER: z
.enum(["bedrock", "anthropic", "openai", "vertex"])
.optional(),
LANGFUSE_AI_MODEL: z.string().optional(),
LANGFUSE_AI_SMALL_MODEL: z.string().optional(),
LANGFUSE_AI_API_KEY: z.string().optional(),
LANGFUSE_AI_BASE_URL: z.string().optional(),
LANGFUSE_AI_USE_RESPONSES_API: z.enum(["true", "false"]).optional(),
LANGFUSE_AI_EXTRA_HEADERS: z
.string()
.optional()
.refine(
(value) => {
if (value == null || value.trim() === "") {
return true;
}
try {
z.record(z.string(), z.string()).parse(JSON.parse(value));
return true;
} catch {
return false;
}
},
{
message:
"LANGFUSE_AI_EXTRA_HEADERS must be a JSON object of string header names and values",
},
),
LANGFUSE_AI_AWS_BEDROCK_REGION: z.string().optional(),
// Cloud runtime credentials require an operator-provisioned connection.
LANGFUSE_BEDROCK_LLM_CONNECTION_RUNTIME_CREDENTIALS_ALLOWED_PROJECT_IDS: z
.string()
.default("")
.transform((value) =>
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
),
// Local AI credentials; production normally uses the AWS role chain.
AWS_PROFILE: z.string().optional(),
LANGFUSE_AI_FEATURES_AWS_PROFILE: z.string().optional(),
// Legacy local profile alias.
LANGFUSE_IN_APP_AGENT_AWS_PROFILE: z.string().optional(),
LANGFUSE_AI_VERTEX_LOCATION: z.string().optional(),
LANGFUSE_IN_APP_AGENT_ENABLED: z.enum(["true", "false"]).optional(),
LANGFUSE_EVALUATOR_MEDIA_TRANSPORT: z
.enum(["url", "inline", "disabled"])
.optional(),
LANGFUSE_EVALUATOR_MEDIA_INLINE_MAX_BYTES: z.coerce
.number()
.int()
.positive()
.default(20_000_000),
// API Performance Flags
// Whether to add a `FINAL` modifier to the observations CTE in GET /api/public/traces.
// Can be used to improve performance for self-hosters that are fully on the new OTel SDKs.
LANGFUSE_API_CLICKHOUSE_DISABLE_OBSERVATIONS_FINAL: z
.enum(["true", "false"])
.default("false"),
// Enable Redis-based tracking of projects using OTEL API to optimize ClickHouse queries.
// When enabled, projects ingesting via OTEL API skip the FINAL modifier on some observations queries for better performance.
LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS: z
.enum(["true", "false"])
.default("false"),
// Comma-separated project ids whose scores are never updated after ingestion.
// Reads of the scores table skip deduplication (FINAL / LIMIT 1 BY) for them.
LANGFUSE_SKIP_SCORES_DEDUP_PROJECT_IDS: z
.string()
.default("")
.transform(
(value) =>
new Set(
value
.split(",")
.map((id) => id.trim())
.filter(Boolean),
),
),
// Langfuse AI Features
LANGFUSE_AI_FEATURES_PUBLIC_KEY: z.string().optional(),
LANGFUSE_AI_FEATURES_SECRET_KEY: z.string().optional(),
LANGFUSE_AI_FEATURES_HOST: z.string().optional(),
LANGFUSE_AI_FEATURES_PROJECT_ID: z.string().optional(),
// Dataset Service
LANGFUSE_DATASET_SERVICE_WRITE_TO_VERSIONED_IMPLEMENTATION: z
.enum(["true", "false"])
.default("true"),
LANGFUSE_DATASET_SERVICE_READ_FROM_VERSIONED_IMPLEMENTATION: z
.enum(["true", "false"])
.default("true"),
// API ClickHouse query options
LANGFUSE_API_CLICKHOUSE_PROPAGATE_OBSERVATIONS_TIME_BOUNDS: z
.enum(["true", "false"])
.default("false"),
// EE License
LANGFUSE_EE_LICENSE_KEY: z.string().optional(),
// FIPS mode (EE feature): refuse to start without an enterprise license or
// an active OpenSSL FIPS provider. See server/ee/fips.
LANGFUSE_REQUIRE_FIPS: z.enum(["true", "false"]).default("false"),
// Ingestion Masking (EE feature)
LANGFUSE_INGESTION_MASKING_CALLBACK_URL: z.url().optional(),
LANGFUSE_INGESTION_MASKING_CALLBACK_TIMEOUT_MS: z.coerce
.number()
.positive()
.default(500),
LANGFUSE_INGESTION_MASKING_CALLBACK_FAIL_CLOSED: z
.enum(["true", "false"])
.default("false"),
LANGFUSE_INGESTION_MASKING_MAX_RETRIES: z.coerce
.number()
.nonnegative()
.default(1),
LANGFUSE_INGESTION_MASKING_PROPAGATED_HEADERS: z
.string()
.optional()
.transform((s) =>
s ? s.split(",").map((h) => h.toLowerCase().trim()) : [],
),
});
export type SharedEnv = z.infer<typeof EnvSchema>;
export const env: SharedEnv =
process.env.DOCKER_BUILD === "1" // eslint-disable-line turbo/no-undeclared-env-vars
? (process.env as any)
: EnvSchema.parse(removeEmptyEnvVariables(process.env));