🪢 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
feat(worker): add optional startup jitter before queue registration (#18525)
Niklas Semmler034d581dafd2
diff --git a/worker/src/__tests__/startupJitter.unit.test.ts b/worker/src/__tests__/startupJitter.unit.test.tsnew file mode 100644index 0000000000..2d6158e874--- /dev/null+++ b/worker/src/__tests__/startupJitter.unit.test.ts@@ -0,0 +1,14 @@+import { describe, expect, it } from "vitest";+import { getStartupJitterMs } from "../utils/startupJitter";++describe("getStartupJitterMs", () => {+ it("returns 0 when disabled", () => {+ expect(getStartupJitterMs(0, () => 0.9)).toBe(0);+ });++ it("scales the random value to [0, maxMs]", () => {+ expect(getStartupJitterMs(10_000, () => 0)).toBe(0);+ expect(getStartupJitterMs(10_000, () => 0.5)).toBe(5_000);+ expect(getStartupJitterMs(10_000, () => 0.999999999)).toBe(10_000);+ });+});diff --git a/worker/src/env.ts b/worker/src/env.tsindex ea09e5f1dc..db3887217c 100644--- a/worker/src/env.ts+++ b/worker/src/env.ts@@ -797,6 +797,17 @@ const EnvSchema = z.object({.default(2),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>;diff --git a/worker/src/index.ts b/worker/src/index.tsindex 5dd5112e1d..1a39254a81 100644--- a/worker/src/index.ts+++ b/worker/src/index.ts@@ -4,12 +4,15 @@ import type { Server } from "http";import { initializeWorker } from "./initialize";import { env } from "./env";import { logger } from "@langfuse/shared/src/server";+import { delayStartupByJitter } from "./utils/startupJitter";export let server: Server | undefined;const startWorker = async (): Promise<void> => {await initializeWorker();+ await delayStartupByJitter(env.LANGFUSE_WORKER_STARTUP_JITTER_MAX_MS);+type AppDefault = typeof import("./app.js").default;const mod = (await import("./app.js")) as unknown as {default: AppDefault | { default: AppDefault };diff --git a/worker/src/utils/startupJitter.ts b/worker/src/utils/startupJitter.tsnew file mode 100644index 0000000000..b5d90403a8--- /dev/null+++ b/worker/src/utils/startupJitter.ts@@ -0,0 +1,26 @@+import { logger, sleep } from "@langfuse/shared/src/server";++/**+ * Returns a uniformly distributed delay in [0, maxMs] milliseconds.+ *+ * Used to spread out the Redis connection setup of workers that boot at the+ * same time, e.g. when autoscaling adds many tasks in one step.+ */+export const getStartupJitterMs = (+ maxMs: number,+ random: () => number = Math.random,+): number => {+ if (maxMs <= 0) return 0;+ return Math.floor(random() * (maxMs + 1));+};++/**+ * Sleeps for a random startup jitter of up to `maxMs` before queue consumers+ * and periodic runners open their Redis connections.+ */+export const delayStartupByJitter = async (maxMs: number): Promise<void> => {+ const jitterMs = getStartupJitterMs(maxMs);+ if (jitterMs <= 0) return;+ logger.info(`Delaying queue registration by ${jitterMs}ms (startup jitter)`);+ await sleep(jitterMs);+};