Skip to content

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

feat(otel): simulate worker admission in shadow mode (#17437)

Valery Meleshkine19d3715c05b
diff --git a/.env.prod.example b/.env.prod.example
index ef4e88247a..70f4290a4c 100644
--- a/.env.prod.example
+++ b/.env.prod.example
@@ -292,6 +292,8 @@ LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG=true
# LANGFUSE_INGESTION_CLICKHOUSE_MAX_ATTEMPTS=
# Maximum encoded and decompressed OTLP request body size in bytes (default: 536870912 = 512 MiB)
# LANGFUSE_OTEL_INGESTION_MAX_BODY_BYTES=536870912
+# Simulate OTLP worker admission while keeping inline ingestion authoritative (default: false)
+# LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED=false
# Evaluation worker concurrency
# LANGFUSE_EVAL_EXECUTION_WORKER_CONCURRENCY=5
diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml
index 00cc226252..79e45b1af4 100644
--- a/.github/workflows/pipeline.yml
+++ b/.github/workflows/pipeline.yml
@@ -698,7 +698,7 @@ jobs:
# at run creation, so this job starts immediately (!cancelled() lets the
# condition evaluate despite the skipped dependency).
if: ${{ !cancelled() && (github.event_name != 'push' || needs.pre-job.outputs.should_skip != 'true') }}
- name: tests-web (node${{ matrix.node-version }}, pg${{ matrix.postgres-version }}, mode${{ matrix.deploy-mode }})
+ name: tests-web (node${{ matrix.node-version }}, pg${{ matrix.postgres-version }}, mode${{ matrix.deploy-mode }}, otel-worker-shadow=${{ matrix.deploy-mode != '-azure' }})
env:
VITEST_MAX_WORKERS: "12"
NODE_ENV: test
@@ -771,6 +771,7 @@ jobs:
# phase below reapplies the mode-specific config and prerendering.
write_test_env .env.dev.example .env
write_test_env .env.dev${{ matrix.deploy-mode }}.example .env.runtime
+ echo "LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED=${{ matrix.deploy-mode != '-azure' }}" >> .env.runtime
- name: Setup Turbo remote cache
if: env.CI_CACHE_ALLOWED == 'true'
continue-on-error: true
@@ -806,6 +807,8 @@ jobs:
NEXT_DISABLE_BUILD_CACHE: "true"
NODE_OPTIONS: --max_old_space_size=8192
NEXT_IGNORE_BUILD_ERRORS: "true"
+ - name: Build OTel ingestion worker
+ run: pnpm --filter web run build:otel-worker
- name: Wait for dev containers
run: |
timeout 300 bash -c 'until [ -f /tmp/compose-up.exit ]; do sleep 1; done' \
diff --git a/knip.jsonc b/knip.jsonc
index 96f3722edc..8868fadc51 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -39,8 +39,12 @@
],
},
"web": {
- // Components imported by MDX documentation, which Knip does not trace.
- "entry": [".storybook/docs/**/*.tsx"],
+ "entry": [
+ // Components imported by MDX documentation, which Knip does not trace.
+ ".storybook/docs/**/*.tsx",
+ // Runtime worker entry loaded by filename through Piscina.
+ "src/server/otel/otelIngestionWorker.ts",
+ ],
"ignoreFiles": [
// Standalone benchmark invoked directly with Node rather than imported by the application.
"src/features/traces/components/AdvancedJsonViewer/lazy/benchByteJsonIndex.ts",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f642709fab..f419949a08 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -803,6 +803,12 @@ importers:
next-themes:
specifier: ^0.4.6
+ p-queue:
+ specifier: 9.3.3
+ version: 9.3.3
+ piscina:
+ specifier: 5.3.0
+ version: 5.3.0
posthog-js:
specifier: ^1.417.1
version: 1.417.1([email protected])
@@ -993,6 +999,9 @@ importers:
dotenv-expand:
specifier: ^10.0.0
version: 10.0.0
+ esbuild:
+ specifier: 0.28.1
+ version: 0.28.1
eslint:
specifier: 'catalog:'
@@ -3058,6 +3067,119 @@ packages:
resolution: {integrity: sha512-sgOZ89+y8cDbY+3WbzR8CtIhCuFRWotZ9/2PjPVDJHz6np5KFTAev0DrwiyTJTgFsCRDhfGlbmhMgyhHbWdZ6g==}
engines: {node: ^22.20 || ^24.12 || >=25}
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-kjirL3N6TnRPv5iuHw36wnucNqXAO46dzK9oPb0wj076R5Xm8PfUVA9nAFB5ZNMmfJQJVKACAPd/Z2KYMppthw==}
+ engines: {node: '>= 10'}
+ cpu: [arm]
+ os: [android]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-blG0i7dXgbInN5urONoUCNf+DUEAavRffrO7fZSeoRMJc5qD+BJeNcpr54msPF6qfDD6kzs9AQJogZvT2KD5nw==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [android]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-s/E7w45NaLqTGuOjC2p96pct4jRfo61xb9bU1unM/MJ/RFkKlJyJDx7OJI/O0ll/hrfpqKopuAFDV8yo0hfT7A==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-dGoEBnVpsdcC+oHHmW1LRK5eiyzLwdgNQq3BmZIav+9/5WTZwBYX7r5ZkQC07Nxd3KHOCkgbHSh4wPkH1N1LiQ==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-kHv4kEHAylMYmlNwcQcDtXjklYp4FCf0b05E+0h6nDHsZ+F0bDe04U/tXNOqrx5CmIAth4vwfkjjUmp4c4JktQ==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [freebsd]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-E1t7K0efyKXZDoZg1LzCOLxgolxV58HCkaEkEvIYQx12ht2pa8hoBo+4OB3qh7e+QiBlp1SRf+voWUZFxyhyqg==}
+ engines: {node: '>= 10'}
+ cpu: [arm]
+ os: [linux]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-CIKLA12DTIZlmTaaKhQP88R3Xao+gyJxNWEn04wZwC2wmRapNnxCUZkVwggInMJvtVElA+D4ZzOU5sX4jV+SmQ==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-+2Rzdb3nTIYZ0YJF43qf2twhqOCkiSrHx2Pg6DJaCPYhhaxbLcdlV8hCRMHghQ+EtZQWGNcS2xF4KxBhSGeutg==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-4FS8oc0GeHpwvv4tKciKkw3Y4jKsL7FRhaOeiPei0X9T4Jd619wHNe4xCLmN2EMgZoeGg+Q7GY7BsvwKpL22Tg==}
+ engines: {node: '>= 10'}
+ cpu: [ppc64]
+ os: [linux]
+ libc: [glibc]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-HU0nw9uD4FO/oGCCk409tCi5IzIZpH2agE6nN4fqpwVlCn5BOq0MS1dXGjXaG17JaAvrlpV5ZeyZwSon10XOXw==}
+ engines: {node: '>= 10'}
+ cpu: [riscv64]
+ os: [linux]
+ libc: [glibc]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-2YqKJWWl24EwrX0DzCQgPLKQBxYDdBxOHot1KWEq7aY2uYeX+Uvtv4I8xFVVygJDgf6/92h9N3Y43WPx8+PAgQ==}
+ engines: {node: '>= 10'}
+ cpu: [s390x]
+ os: [linux]
+ libc: [glibc]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-/gaNz3R92t+dcrfCw/96pDopcmec7oCcAQ3l/M+Zxr82KT4DljD37CpgrnXV+pJC263JkW572pdbP3hP+KjcIg==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-xScCGnyj/oppsNPMnevsBe3pvNaoK7FGvMjT35riz9YdhB2WtTG47ZlbxtOLpjeO9SqqQ2J2igCmz6IJOD5JYw==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-6uJPRVwVCLDeoOaNyeiW0gp2kFIM4r7PL2MczdZQHkFi9gVlgm+Vn+V6nTWRcu856mJ2WjYJiumEajfSm7arPQ==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [openharmony]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-uoTb4eAvM5B2aj/z8j+Nv8OttPf2m+HVx3UjA5jcFxASvNhQriyCQF1OB1lHL43ZhW+VwZlgvjmP5qF3+59atA==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-CNQqlQT9MwuCsg1Vd/oKXiuH+TcsSPJmlAFc5frFyX/KkOh0UpBLEj7aoY656d5UKZQMQFP7vJNa1DNUNORvug==}
+ engines: {node: '>= 10'}
+ cpu: [ia32]
+ os: [win32]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-vB+4G/jBQCAh0jelMTY3+kgFy00Hlx2f2/1zjMoH821IbplbWZOkLiTYXQkygNTzQJTq5cvwBDgn2ppHD+bglQ==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [win32]
+
+ '@napi-rs/[email protected]':
+ resolution: {integrity: sha512-xJIPs+bYuc9ASBl+cvGsKbGrJmS6fAKaSZCnT0lhahT5rhA2VVy9/EcIgd2JhtEuFOJNx7UHNn/qiTPTY4nrQw==}
+ engines: {node: '>= 10'}
+
'@napi-rs/[email protected]':
resolution: {integrity: sha512-cAhnA10cSusAUbcE9HtjQY/tZ9BH/0w2sKtRcQc94TzIlnm7QSr1htJSd/PPrbWNPtrv1orXb2CkrHlVlbnlHA==}
engines: {node: '>= 10'}
@@ -10519,6 +10641,10 @@ packages:
resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==}
engines: {node: '>=8'}
+ resolution: {integrity: sha512-NXAOdnEe5FsZJfT4oK84lE1Y5cFFdWlRuOo5tww8DyNMxyRXwn39fIkUtNLKppcPC+UYU/bXujNCUGDv01y7CA==}
+ engines: {node: '>=20'}
+
resolution: {integrity: sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==}
engines: {node: '>=8'}
@@ -10535,6 +10661,10 @@ packages:
resolution: {integrity: sha512-MyIV3ZA/PmyBN/ud8vV9XzwTrNtR4jFrObymZYnZqMmW0zA8Z17vnT0rBgFE/TlohB+YCHqXMgZzb3Csp49vqg==}
engines: {node: '>=14.16'}
+ resolution: {integrity: sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg==}
+ engines: {node: '>=20'}
+
resolution: {integrity: sha512-HyCoVbyQ/nbVlQ/R6wBu0YXhbG2oAnEK5BQ3xMyj1OffQmU5NoOnpLzgPlKHaobUzz5NK0+AZHby4TdydAEBUA==}
engines: {node: '>= 14'}
@@ -10640,6 +10770,10 @@ packages:
resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-9D3tPBayfoal6l9l4Y8NrMn1jkV718qJoYrla6P51+hh9h0Q+9/1c8KgEnoBQqhguyfgjay4biADI8HJG3pkoA==}
+ engines: {node: '>=20.x'}
+
resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
engines: {node: '>=16.20.0'}
@@ -14796,6 +14930,78 @@ snapshots:
'@napi-rs/lzma-win32-ia32-msvc': 1.5.1
'@napi-rs/lzma-win32-x64-msvc': 1.5.1
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optional: true
+
+ '@napi-rs/[email protected]':
+ optionalDependencies:
+ '@napi-rs/nice-android-arm-eabi': 1.1.1
+ '@napi-rs/nice-android-arm64': 1.1.1
+ '@napi-rs/nice-darwin-arm64': 1.1.1
+ '@napi-rs/nice-darwin-x64': 1.1.1
+ '@napi-rs/nice-freebsd-x64': 1.1.1
+ '@napi-rs/nice-linux-arm-gnueabihf': 1.1.1
+ '@napi-rs/nice-linux-arm64-gnu': 1.1.1
+ '@napi-rs/nice-linux-arm64-musl': 1.1.1
+ '@napi-rs/nice-linux-ppc64-gnu': 1.1.1
+ '@napi-rs/nice-linux-riscv64-gnu': 1.1.1
+ '@napi-rs/nice-linux-s390x-gnu': 1.1.1
+ '@napi-rs/nice-linux-x64-gnu': 1.1.1
+ '@napi-rs/nice-linux-x64-musl': 1.1.1
+ '@napi-rs/nice-openharmony-arm64': 1.1.1
+ '@napi-rs/nice-win32-arm64-msvc': 1.1.1
+ '@napi-rs/nice-win32-ia32-msvc': 1.1.1
+ '@napi-rs/nice-win32-x64-msvc': 1.1.1
+ optional: true
+
'@napi-rs/[email protected]':
optional: true
@@ -23088,6 +23294,11 @@ snapshots:
eventemitter3: 4.0.7
p-timeout: 3.2.0
+ dependencies:
+ eventemitter3: 5.0.4
+ p-timeout: 7.0.1
+
dependencies:
'@types/retry': 0.12.0
@@ -23103,6 +23314,8 @@ snapshots:
+
dependencies:
agent-base: 8.0.0
@@ -23204,6 +23417,10 @@ snapshots:
+ optionalDependencies:
+ '@napi-rs/nice': 1.1.1
+
diff --git a/web/next.config.mjs b/web/next.config.mjs
index 2f492d11a8..421d2d2d52 100644
--- a/web/next.config.mjs
+++ b/web/next.config.mjs
@@ -107,6 +107,7 @@ const nextConfig = {
"bullmq",
"@opentelemetry/sdk-node",
"@opentelemetry/instrumentation-winston",
+ "piscina",
],
poweredByHeader: false,
basePath: env.NEXT_PUBLIC_BASE_PATH,
diff --git a/web/package.json b/web/package.json
index f862a1516c..7c8653144a 100644
--- a/web/package.json
+++ b/web/package.json
@@ -7,9 +7,10 @@
"node": "24"
},
"scripts": {
- "build": "INLINE_RUNTIME_CHUNK=false dotenv -e ../.env -- next build",
+ "build": "INLINE_RUNTIME_CHUNK=false dotenv -e ../.env -- next build && pnpm run build:otel-worker",
"build:test": "INLINE_RUNTIME_CHUNK=false dotenv -e ../.env -- next build --experimental-build-mode compile",
- "build:check": "NEXT_DIST_DIR=.next-check INLINE_RUNTIME_CHUNK=false dotenv -e ../.env -- next build",
+ "build:check": "NEXT_DIST_DIR=.next-check INLINE_RUNTIME_CHUNK=false dotenv -e ../.env -- next build && NEXT_DIST_DIR=.next-check pnpm run build:otel-worker",
+ "build:otel-worker": "DOCKER_BUILD=1 dotenv -e ../.env -- node scripts/build-otel-ingestion-worker.mjs",
"typecheck": "dotenv -e ../.env -- tsc -p tsconfig.json --noEmit --skipLibCheck --incremental --tsBuildInfoFile .tsbuildinfo",
"dev": "dotenv -e ../.env -- next dev",
"dev:http": "dotenv -e ../.env -- next dev --experimental-https --experimental-https-key ./localhost+1-key.pem --experimental-https-cert ./localhost+1.pem",
@@ -138,6 +139,8 @@
"next-auth": "^4.24.14",
"next-query-params": "^5.1.0",
"next-themes": "^0.4.6",
+ "p-queue": "9.3.3",
+ "piscina": "5.3.0",
"posthog-js": "^1.417.1",
"posthog-node": "^5.49.1",
"prexit": "^2.2.0",
@@ -203,6 +206,7 @@
"dotenv": "^16.6.1",
"dotenv-cli": "^7.4.2",
"dotenv-expand": "^10.0.0",
+ "esbuild": "0.28.1",
"eslint": "catalog:",
"eslint-plugin-boundaries": "7.2.0",
"eslint-plugin-check-file": "3.3.2",
diff --git a/web/scripts/build-otel-ingestion-worker.mjs b/web/scripts/build-otel-ingestion-worker.mjs
new file mode 100644
index 0000000000..befde1e3bc
--- /dev/null
+++ b/web/scripts/build-otel-ingestion-worker.mjs
@@ -0,0 +1,60 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { build } from "esbuild";
+import Piscina from "piscina";
+
+const distDir = process.env.NEXT_DIST_DIR || ".next";
+const outfile = path.resolve(
+ distDir,
+ "standalone",
+ "web",
+ "otelIngestionWorker.js",
+);
+
+await mkdir(path.dirname(outfile), { recursive: true });
+
+await build({
+ absWorkingDir: process.cwd(),
+ entryPoints: ["src/server/otel/otelIngestionWorker.ts"],
+ outfile,
+ bundle: true,
+ format: "cjs",
+ platform: "node",
+ target: "node24",
+ tsconfig: "tsconfig.json",
+ footer: { js: "module.exports = module.exports.default;" },
+ sourcemap: false,
+});
+
+const pool = new Piscina({
+ filename: outfile,
+ minThreads: 1,
+ maxThreads: 1,
+ maxQueue: 0,
+ atomics: "disabled",
+});
+
+try {
+ const warmup = await pool.run({ type: "warmup" });
+ if (warmup?.kind !== "warmup") {
+ throw new Error(
+ `Unexpected OTel worker warm-up result: ${JSON.stringify(warmup)}`,
+ );
+ }
+
+ const startedAt = performance.now();
+ const shadow = await pool.run({ type: "shadow", durationMs: 20 });
+ if (shadow?.kind !== "shadow") {
+ throw new Error(
+ `Unexpected OTel worker shadow result: ${JSON.stringify(shadow)}`,
+ );
+ }
+ if (performance.now() - startedAt < 15) {
+ throw new Error("OTel worker shadow task returned without sleeping");
+ }
+} finally {
+ await pool.destroy();
+}
+
+console.log(`OTel ingestion worker built and smoke tested: ${outfile}`);
diff --git a/web/src/__tests__/server/unit/otel-ingestion-worker-pool.servertest.ts b/web/src/__tests__/server/unit/otel-ingestion-worker-pool.servertest.ts
new file mode 100644
index 0000000000..997b09fb1d
--- /dev/null
+++ b/web/src/__tests__/server/unit/otel-ingestion-worker-pool.servertest.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { tryScheduleOtelIngestionWorkerLifecycle } from "@/src/server/otel/otelIngestionWorkerPool";
+
+function deferred() {
+ return Promise.withResolvers<void>();
+}
+
+describe("OTel ingestion worker admission", () => {
+ it("runs one lifecycle, queues one, and rejects a third", async () => {
+ const firstRelease = deferred();
+ const secondRelease = deferred();
+ const started: string[] = [];
+
+ const first = tryScheduleOtelIngestionWorkerLifecycle(async () => {
+ started.push("first");
+ await firstRelease.promise;
+ });
+ await vi.waitFor(() => expect(started).toEqual(["first"]));
+
+ const second = tryScheduleOtelIngestionWorkerLifecycle(async () => {
+ started.push("second");
+ await secondRelease.promise;
+ });
+ const third = tryScheduleOtelIngestionWorkerLifecycle(async () => {});
+
+ expect(first).toBeDefined();
+ expect(second).toBeDefined();
+ expect(third).toBeUndefined();
+ expect(started).toEqual(["first"]);
+
+ firstRelease.resolve();
+ await first;
+ await vi.waitFor(() => expect(started).toEqual(["first", "second"]));
+ secondRelease.resolve();
+ await second;
+ });
+
+ it("removes an aborted waiter so its queue slot can be reused", async () => {
+ const firstRelease = deferred();
+ const first = tryScheduleOtelIngestionWorkerLifecycle(
+ async () => firstRelease.promise,
+ );
+ const abortController = new AbortController();
+ let abortedTaskStarted = false;
+ const aborted = tryScheduleOtelIngestionWorkerLifecycle(async () => {
+ abortedTaskStarted = true;
+ }, abortController.signal);
+
+ abortController.abort();
+ await expect(aborted).rejects.toMatchObject({ name: "AbortError" });
+
+ let nextTaskStarted = false;
+ const next = tryScheduleOtelIngestionWorkerLifecycle(async () => {
+ nextTaskStarted = true;
+ });
+ expect(next).toBeDefined();
+
+ firstRelease.resolve();
+ await first;
+ await next;
+ expect(abortedTaskStarted).toBe(false);
+ expect(nextTaskStarted).toBe(true);
+ });
+});
diff --git a/web/src/env.mjs b/web/src/env.mjs
index c0c8857bad..2366b55133 100644
--- a/web/src/env.mjs
+++ b/web/src/env.mjs
@@ -582,6 +582,10 @@ export const env = createEnv({
LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS: z
.enum(["true", "false"])
.default("false"),
+ // Simulate worker admission without changing OTLP request processing.
+ LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED: z
+ .enum(["true", "false"])
+ .default("false"),
// Maximum encoded and decompressed OTLP request body size in bytes.
LANGFUSE_OTEL_INGESTION_MAX_BODY_BYTES: z.coerce
.number()
@@ -1171,6 +1175,8 @@ export const env = createEnv({
// Api Performance Flags
LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS:
process.env.LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS,
+ LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED:
+ process.env.LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED,
LANGFUSE_OTEL_INGESTION_MAX_BODY_BYTES:
process.env.LANGFUSE_OTEL_INGESTION_MAX_BODY_BYTES,
diff --git a/web/src/instrumentation.ts b/web/src/instrumentation.ts
index cfcb804f27..5d7a17fefd 100644
--- a/web/src/instrumentation.ts
+++ b/web/src/instrumentation.ts
@@ -36,4 +36,21 @@ export async function register() {
if (isNodeRuntime && isInitLoadingEnabled) {
await import("./initialize");
}
+
+ if (isNodeRuntime) {
+ const { env } = await import("./env.mjs");
+ if (env.LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED === "true") {
+ const { preloadOtelIngestionWorkerShadow } =
+ await import("./server/otel/otelIngestionWorkerShadow");
+ try {
+ await preloadOtelIngestionWorkerShadow();
+ } catch (error) {
+ const { logger } = await import("@langfuse/shared/src/server");
+ logger.error(
+ "Failed to preload OTel ingestion worker shadow; shadow disabled",
+ error,
+ );
+ }
+ }
+ }
}
diff --git a/web/src/pages/api/public/otel/v1/traces/index.ts b/web/src/pages/api/public/otel/v1/traces/index.ts
index a54e44eab3..b8c563b6ea 100644
--- a/web/src/pages/api/public/otel/v1/traces/index.ts
+++ b/web/src/pages/api/public/otel/v1/traces/index.ts
@@ -42,6 +42,12 @@ export default withMiddlewares({
// Mark project as using OTEL API
await markProjectAsOtelUser(auth.scope.projectId);
+ if (env.LANGFUSE_OTEL_INGESTION_WORKER_SHADOW_ENABLED === "true") {
+ const { startOtelIngestionWorkerAdmissionShadow } =
+ await import("@/src/server/otel/otelIngestionWorkerShadow");
+ startOtelIngestionWorkerAdmissionShadow(res, auth.scope.projectId);
+ }
+
const maxBodyBytes = env.LANGFUSE_OTEL_INGESTION_MAX_BODY_BYTES;
let body: Buffer;
diff --git a/web/src/server/otel/otelIngestionWorker.ts b/web/src/server/otel/otelIngestionWorker.ts
new file mode 100644
index 0000000000..fe29e7216c
--- /dev/null
+++ b/web/src/server/otel/otelIngestionWorker.ts
@@ -0,0 +1,18 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
+export type OtelIngestionWorkerRequest =
+ | { type: "warmup" }
+ | { type: "shadow"; durationMs: number };
+
+export type OtelIngestionWorkerResult = { kind: "warmup" } | { kind: "shadow" };
+
+export default async function runOtelIngestionWorker(
+ request: OtelIngestionWorkerRequest,
+): Promise<OtelIngestionWorkerResult> {
+ if (request.type === "warmup") {
+ return { kind: "warmup" };
+ }
+
+ await sleep(request.durationMs);
+ return { kind: "shadow" };
+}
diff --git a/web/src/server/otel/otelIngestionWorkerPool.ts b/web/src/server/otel/otelIngestionWorkerPool.ts
new file mode 100644
index 0000000000..760e8f01d4
--- /dev/null
+++ b/web/src/server/otel/otelIngestionWorkerPool.ts
@@ -0,0 +1,114 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { logger } from "@langfuse/shared/src/server";
+import PQueue from "p-queue";
+import Piscina from "piscina";
+
+import type {
+ OtelIngestionWorkerRequest,
+ OtelIngestionWorkerResult,
+} from "./otelIngestionWorker";
+
+const MAX_WORKER_QUEUE_DEPTH = 2;
+
+let workerPool:
+ | Piscina<OtelIngestionWorkerRequest, OtelIngestionWorkerResult>
+ | undefined;
+let workerPreloadPromise: Promise<void> | undefined;
+const workerQueue = new PQueue({ concurrency: 1 });
+
+function getWorkerFilename(): string {
+ const distDir = process.env.NEXT_DIST_DIR || ".next";
+ const serverEntry = process.argv[1];
+ const candidates = [
+ ...(serverEntry
+ ? [
+ path.join(
+ path.dirname(path.resolve(serverEntry)),
+ "otelIngestionWorker.js",
+ ),
+ ]
+ : []),
+ path.join(process.cwd(), "web", "otelIngestionWorker.js"),
+ path.join(
+ process.cwd(),
+ distDir,
+ "standalone",
+ "web",
+ "otelIngestionWorker.js",
+ ),
+ ];
+ const filename = candidates.find((candidate) => existsSync(candidate));
+
+ if (!filename) {
+ throw new Error(
+ "OTel ingestion worker artifact is missing; run the web build before enabling worker ingestion",
+ );
+ }
+
+ return filename;
+}
+
+function getWorkerPool(): Piscina<
+ OtelIngestionWorkerRequest,
+ OtelIngestionWorkerResult
+> {
+ if (!workerPool) {
+ workerPool = new Piscina({
+ filename: getWorkerFilename(),
+ minThreads: 1,
+ maxThreads: 1,
+ maxQueue: 0,
+ atomics: "disabled",
+ });
+ workerPool.on("error", (error) => {
+ logger.error("OTel ingestion worker pool error", error);
+ });
+ }
+
+ return workerPool;
+}
+
+export function dispatchOtelIngestionWorkerTask(
+ request: OtelIngestionWorkerRequest,
+ options?: Parameters<
+ Piscina<OtelIngestionWorkerRequest, OtelIngestionWorkerResult>["run"]
+ >[1],
+): Promise<OtelIngestionWorkerResult> {
+ return getWorkerPool().run(request, options);
+}
+
+/**
+ * Owns admission for both shadow and real worker ingestion. The task must cover
+ * the complete request lifecycle so a waiting request stays paused and unread.
+ */
+export function tryScheduleOtelIngestionWorkerLifecycle(
+ task: (signal?: AbortSignal) => Promise<void>,
+ signal?: AbortSignal,
+): Promise<void> | undefined {
+ if (workerQueue.pending + workerQueue.size >= MAX_WORKER_QUEUE_DEPTH) {
+ return undefined;
+ }
+
+ return workerQueue.add(
+ async ({ signal: queueSignal }) => task(queueSignal),
+ signal ? { signal } : undefined,
+ );
+}
+
+async function runWorkerPreload(): Promise<void> {
+ const result = await dispatchOtelIngestionWorkerTask({ type: "warmup" });
+ if (result.kind !== "warmup") {
+ throw new Error(
+ "OTel ingestion worker did not report ready during warm-up",
+ );
+ }
+}
+
+export function preloadOtelIngestionWorker(): Promise<void> {
+ if (!workerPreloadPromise) {
+ workerPreloadPromise = runWorkerPreload();
+ }
+ return workerPreloadPromise;
+}
diff --git a/web/src/server/otel/otelIngestionWorkerShadow.ts b/web/src/server/otel/otelIngestionWorkerShadow.ts
new file mode 100644
index 0000000000..25555ca660
--- /dev/null
+++ b/web/src/server/otel/otelIngestionWorkerShadow.ts
@@ -0,0 +1,97 @@
+import {
+ logger,
+ recordDistribution,
+ recordIncrement,
+} from "@langfuse/shared/src/server";
+import type { NextApiResponse } from "next";
+
+import {
+ dispatchOtelIngestionWorkerTask,
+ preloadOtelIngestionWorker,
+ tryScheduleOtelIngestionWorkerLifecycle,
+} from "./otelIngestionWorkerPool";
+
+let lastProcessingDurationMs: number | undefined;
+let workerPreloadPromise: Promise<void> | undefined;
+let workerShadowAvailable = false;
+
+function scheduleAdmissionShadow(projectId: string, durationMs: number): void {
+ const task = tryScheduleOtelIngestionWorkerLifecycle(async (signal) => {
+ const result = await dispatchOtelIngestionWorkerTask(
+ { type: "shadow", durationMs },
+ { signal },
+ );
+ if (result.kind !== "shadow") {
+ throw new Error(
+ "OTel ingestion worker returned an invalid shadow result",
+ );
+ }
+ });
+
+ if (!task) {
+ recordIncrement("langfuse.ingestion.otel.worker_shadow.admission", 1, {
+ outcome: "would_reject",
+ });
+ logger.warn("OTel ingestion worker shadow would reject request", {
+ projectId,
+ simulatedProcessingDurationMs: durationMs,
+ });
+ return;
+ }
+
+ recordIncrement("langfuse.ingestion.otel.worker_shadow.admission", 1, {
+ outcome: "admitted",
+ });
+ task.catch((error: unknown) => {
+ logger.error("OTel ingestion worker shadow task failed", error);
+ });
+}
+
+export function startOtelIngestionWorkerAdmissionShadow(
+ res: NextApiResponse,
+ projectId: string,
+): void {
+ if (!workerShadowAvailable) return;
+
+ if (lastProcessingDurationMs !== undefined) {
+ scheduleAdmissionShadow(projectId, lastProcessingDurationMs);
+ }
+
+ const startedAt = performance.now();
+ let completed = false;
+ function stopTracking() {
+ res.off("finish", recordProcessingDuration);
+ res.off("close", stopTracking);
+ }
+ function recordProcessingDuration() {
+ if (completed) return;
+ completed = true;
+ stopTracking();
+ const processingDurationMs = Math.max(
+ 1,
+ Math.round(performance.now() - startedAt),
+ );
+ lastProcessingDurationMs = processingDurationMs;
+ recordDistribution(
+ "langfuse.ingestion.otel.worker_shadow.real_processing_duration_ms",
+ processingDurationMs,
+ );
+ }
+
+ res.once("finish", recordProcessingDuration);
+ // A client disconnect does not mean inline processing has completed.
+ res.once("close", stopTracking);
+}
+
+async function runWorkerPreload(): Promise<void> {
+ await preloadOtelIngestionWorker();
+ workerShadowAvailable = true;
+ logger.info("OTel ingestion worker shadow preloaded");
+}
+
+export function preloadOtelIngestionWorkerShadow(): Promise<void> {
+ if (!workerPreloadPromise) {
+ workerPreloadPromise = runWorkerPreload();
+ }
+ return workerPreloadPromise;
+}