Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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);
+};