🪢 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(api): limit legacy ingestion to scores for new organizations (#19042)
Max Deichmann348afb05ab23
diff --git a/.env.dev.example b/.env.dev.exampleindex 2761ce8c3a..99846ade5d 100644--- a/.env.dev.example+++ b/.env.dev.example@@ -410,6 +410,12 @@ LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=dual_write# organizations created on/after this date direct-write plain-OTel traffic.# Unset disables it; see worker/src/env.ts for the full semantics.# LANGFUSE_MIGRATION_V4_OTEL_DIRECT_WRITE_ORG_CREATED_CUTOFF=+# Web-only. Organizations created at or after this ISO 8601 timestamp take the+# v4 events_only path on legacy ingestion: POST /api/public/ingestion accepts+# only score-create, and legacy POST/PATCH trace, generation, span, and event+# routes return 404. Unset leaves those routes unchanged. The worker does not+# read this; set it on the web service.+# LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF=# Keep the WIP historic backfill dormant for local dev / CI. The v4 code default# is `true`, but the general test suite should not run the backfill underneath it# (it has a dedicated e2e spec). Set to `true` to exercise the backfill locally.diff --git a/.env.prod.example b/.env.prod.exampleindex 25716c6de7..0b4dacf7d1 100644--- a/.env.prod.example+++ b/.env.prod.example@@ -84,6 +84,13 @@ OTEL_SERVICE_NAME="langfuse"# LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED=false# LANGFUSE_API_ORGANIZATION_CUTOFF_DATE=2026-09-16T00:00:00.000Z+# Web-only. Organizations created at or after this ISO 8601 timestamp take the+# v4 events_only path on legacy ingestion: POST /api/public/ingestion accepts+# only score-create, and legacy POST/PATCH trace, generation, span, and event+# routes return 404. Unset leaves those routes unchanged. The worker does not+# read this; set it on the web service.+# LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF=+# Auth, optional configuration# AUTH_DOMAINS_WITH_SSO_ENFORCEMENT=domain1.com,domain2.com# AUTH_IGNORE_ACCOUNT_FIELDS=foo,bardiff --git a/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts b/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.tsindex 4043bffe13..67692aa62b 100644--- a/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts+++ b/web/src/__tests__/server/unit/create-authed-project-api-route-auth-errors.servertest.ts@@ -47,6 +47,10 @@ const {NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: undefined as string | undefined,LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED: "false" as "true" | "false",LANGFUSE_API_ORGANIZATION_CUTOFF_DATE: "2026-09-16T00:00:00.000Z",+ LANGFUSE_MIGRATION_V4_WRITE_MODE: "dual" as "dual" | "events_only",+ LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF: undefined as+ | string+ | undefined,},}));@@ -168,6 +172,8 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {});mockEnv.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;mockEnv.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED = "false";+ mockEnv.LANGFUSE_MIGRATION_V4_WRITE_MODE = "dual";+ mockEnv.LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF = undefined;});async function callRoute(options?: {@@ -630,4 +636,79 @@ describe("createAuthedProjectAPIRoute auth error handling", () => {expect(res._isEndCalled()).toBe(true);expect(res._getData()).toBe("");});++ describe("legacy write rejection messages", () => {+ async function callLegacyWrite() {+ const fn = vi.fn(async () => ({ ok: true as const }));+ const handler = createAuthedProjectAPIRoute({+ name: "Create Trace (Legacy)",+ action: "traces:create",+ responseSchema: z.object({ ok: z.literal(true) }),+ rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,+ fn,+ });+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);+ const { req, res } = createMocks<NextApiRequest, NextApiResponse>({+ method: "POST",+ url: "/api/public/traces",+ headers: { authorization: "Basic test" },+ });+ await handler(req, res);+ return { res, fn };+ }++ it("tells a cutoff organization to upgrade SDKs or use OTel, without events_only text", async () => {+ mockEnv.LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF =+ validAuth.scope.organizationCreatedAt;++ const { res, fn } = await callLegacyWrite();++ expect(res.statusCode).toBe(404);+ const { message } = res._getJSONData() as { message: string };+ expect(message).toContain(+ "no longer accepts trace or observation writes for this organization",+ );+ expect(message).toContain("Upgrade to the latest Langfuse SDKs");+ expect(message).toContain("POST /api/public/otel/v1/traces");+ expect(message).not.toContain("events_only");+ expect(fn).not.toHaveBeenCalled();+ });++ it("leaves legacy reads open for a cutoff organization", async () => {+ mockEnv.LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF =+ validAuth.scope.organizationCreatedAt;+ const fn = vi.fn(async () => ({ ok: true as const }));+ const handler = createAuthedProjectAPIRoute({+ name: "Get Traces",+ action: "traces:read",+ responseSchema: z.object({ ok: z.literal(true) }),+ rejectInEventsOnlyMode: true,+ fn,+ });+ mockVerifyAuthHeaderAndReturnScope.mockResolvedValueOnce(validAuth);+ const { req, res } = createMocks<NextApiRequest, NextApiResponse>({+ method: "GET",+ url: "/api/public/traces",+ headers: { authorization: "Basic test" },+ });++ await handler(req, res);++ expect(res.statusCode).toBe(200);+ expect(fn).toHaveBeenCalledOnce();+ });++ it("keeps the events_only explanation and adds the SDK and OTel pointer", async () => {+ mockEnv.LANGFUSE_MIGRATION_V4_WRITE_MODE = "events_only";++ const { res } = await callLegacyWrite();++ expect(res.statusCode).toBe(404);+ const { message } = res._getJSONData() as { message: string };+ expect(message).toContain("Langfuse v4 events_only mode");+ expect(message).toContain("Upgrade to the latest Langfuse SDKs");+ expect(message).toContain("POST /api/public/otel/v1/traces");+ });+ });});diff --git a/web/src/__tests__/server/unit/ingestion-write-mode.servertest.ts b/web/src/__tests__/server/unit/ingestion-write-mode.servertest.tsindex 857be10ea3..97ed5de321 100644--- a/web/src/__tests__/server/unit/ingestion-write-mode.servertest.ts+++ b/web/src/__tests__/server/unit/ingestion-write-mode.servertest.ts@@ -9,10 +9,23 @@ import handler, {filterBatchForEventsOnly,} from "@/src/pages/api/public/ingestion";-const { migration, shadowAuth, recordIncrement } = vi.hoisted(() => ({+const {+ migration,+ shadowAuth,+ recordIncrement,+ legacyIngestionGate,+ originalProcessEventBatch,+} = vi.hoisted(() => ({migration: { mode: "shadow" as "legacy" | "shadow" | "enforce" },shadowAuth: vi.fn(),recordIncrement: vi.fn(),+ legacyIngestionGate: {+ writeMode: "dual" as "legacy" | "dual" | "events_only",+ scoreOnlyCutoff: undefined as string | undefined,+ },+ originalProcessEventBatch: {+ current: undefined as typeof processEventBatch | undefined,+ },}));vi.mock(import("@/src/env.mjs"), async (importOriginal) => {@@ -21,7 +34,14 @@ vi.mock(import("@/src/env.mjs"), async (importOriginal) => {env: new Proxy(original.env, {get(target, property, receiver) {if (property === "API_AUTH_MIGRATION") return migration.mode;- if (property === "LANGFUSE_MIGRATION_V4_WRITE_MODE") return "dual";+ if (property === "LANGFUSE_MIGRATION_V4_WRITE_MODE") {+ return legacyIngestionGate.writeMode;+ }+ if (+ property === "LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF"+ ) {+ return legacyIngestionGate.scoreOnlyCutoff;+ }return Reflect.get(target, property, receiver);},}),@@ -35,6 +55,7 @@ vi.mock(import("@/src/features/public-api/server"), async (importOriginal) => ({vi.mock(import("@langfuse/shared/src/server"), async (importOriginal) => {const original = await importOriginal();+ originalProcessEventBatch.current = original.processEventBatch;return {...original,processEventBatch: vi.fn(original.processEventBatch),@@ -56,7 +77,9 @@ describe("legacy ingestion write-mode filter", () => {const sdkLogEvent = { id: "log", type: "sdk-log" };it("allows only score events in v4-only mode", () => {- expect(filterBatchForEventsOnly([scoreEvent, sdkLogEvent], true)).toEqual({+ expect(+ filterBatchForEventsOnly([scoreEvent, sdkLogEvent], "events_only"),+ ).toEqual({batchForProcessing: [scoreEvent],rejectedErrors: [expect.objectContaining({@@ -69,20 +92,206 @@ describe("legacy ingestion write-mode filter", () => {});});+ it("points events_only rejections at the SDK upgrade, the OTel endpoint, and the write-mode bridge", () => {+ const [rejection] = filterBatchForEventsOnly(+ [sdkLogEvent],+ "events_only",+ ).rejectedErrors;++ expect(rejection.error).toContain("Upgrade to the latest Langfuse SDKs");+ expect(rejection.error).toContain("POST /api/public/otel/v1/traces");+ expect(rejection.error).toContain("LANGFUSE_MIGRATION_V4_WRITE_MODE=dual");+ });+it("preserves sdk-log compatibility outside v4-only mode", () => {- expect(filterBatchForEventsOnly([sdkLogEvent], false)).toEqual({+ expect(filterBatchForEventsOnly([sdkLogEvent], null)).toEqual({batchForProcessing: [sdkLogEvent],rejectedErrors: [],});});});+const CUTOFF = "2026-10-01T00:00:00.000Z";++const mixedBatch = [+ {+ id: "trace-event",+ timestamp: "2026-10-01T00:00:00.000Z",+ type: "trace-create",+ body: { id: "trace-id" },+ },+ {+ id: "score-event",+ timestamp: "2026-10-01T00:00:00.000Z",+ type: "score-create",+ body: { id: "score-id", name: "quality", value: 1 },+ },+ {+ id: "log-event",+ timestamp: "2026-10-01T00:00:00.000Z",+ type: "sdk-log",+ body: { log: "test" },+ },+ {+ id: "generation-event",+ timestamp: "2026-10-01T00:00:00.000Z",+ type: "generation-update",+ body: { id: "generation-id" },+ },+];++describe("legacy ingestion score-only organization cutoff", () => {+ beforeEach(() => {+ migration.mode = "legacy";+ legacyIngestionGate.writeMode = "dual";+ legacyIngestionGate.scoreOnlyCutoff = undefined;+ shadowAuth.mockReset();+ recordIncrement.mockClear();+ vi.mocked(processEventBatch).mockReset();+ vi.mocked(processEventBatch).mockImplementation(async (batch) => ({+ successes: (batch as { id?: string }[]).map((event) => ({+ id: typeof event.id === "string" ? event.id : "unknown",+ status: 201,+ })),+ errors: [],+ }));+ });++ function authorizeOrg(organizationCreatedAt?: string) {+ shadowAuth.mockResolvedValue({+ success: true,+ scope: {+ accessLevel: "project",+ projectId: "project",+ orgId: "org",+ organizationCreatedAt,+ apiKeyId: "key",+ publicKey: "pk-lf-test",+ plan: "cloud:hobby",+ rateLimitOverrides: [],+ },+ });+ }++ async function postBatch() {+ const { req, res } = createMocks<NextApiRequest, NextApiResponse>({+ method: "POST",+ headers: { authorization: "Basic dGVzdDp0ZXN0" },+ body: { batch: mixedBatch },+ });+ await handler(req, res);+ return res;+ }++ it("keeps every event when the cutoff is unset", async () => {+ authorizeOrg("2026-10-02T00:00:00.000Z");++ const res = await postBatch();++ expect(res._getStatusCode()).toBe(207);+ expect(res._getJSONData().errors).toEqual([]);+ expect(vi.mocked(processEventBatch).mock.calls[0][0]).toEqual(mixedBatch);+ expect(recordIncrement).not.toHaveBeenCalledWith(+ "langfuse.public_api.legacy_ingestion_non_score_rejected",+ expect.anything(),+ expect.anything(),+ );+ });++ it("keeps every event for an organization created before the cutoff", async () => {+ legacyIngestionGate.scoreOnlyCutoff = CUTOFF;+ authorizeOrg("2026-09-30T23:59:59.999Z");++ const res = await postBatch();++ expect(res._getStatusCode()).toBe(207);+ expect(res._getJSONData().errors).toEqual([]);+ expect(vi.mocked(processEventBatch).mock.calls[0][0]).toEqual(mixedBatch);+ expect(recordIncrement).not.toHaveBeenCalledWith(+ "langfuse.public_api.legacy_ingestion_non_score_rejected",+ expect.anything(),+ expect.anything(),+ );+ });++ it.each([+ ["on the cutoff", CUTOFF],+ ["after the cutoff", "2026-10-02T00:00:00.000Z"],+ ])(+ "rejects non-score events with the organization cutoff error for an organization created %s",+ async (_label, organizationCreatedAt) => {+ legacyIngestionGate.scoreOnlyCutoff = CUTOFF;+ authorizeOrg(organizationCreatedAt);++ const res = await postBatch();++ const cutoffError = expect.stringContaining(+ "no longer accepts trace or observation writes for this organization",+ );+ expect(res._getStatusCode()).toBe(207);+ expect(res._getJSONData()).toMatchObject({+ successes: [{ id: "score-event", status: 201 }],+ errors: [+ {+ id: "trace-event",+ status: 400,+ message: "Event type not accepted",+ error: cutoffError,+ },+ {+ id: "log-event",+ status: 400,+ message: "Event type not accepted",+ error: cutoffError,+ },+ {+ id: "generation-event",+ status: 400,+ message: "Event type not accepted",+ error: cutoffError,+ },+ ],+ });+ const [rejection] = res._getJSONData().errors as { error: string }[];+ expect(rejection.error).toContain("POST /api/public/otel/v1/traces");+ expect(rejection.error).toContain("POST /api/public/scores");+ expect(rejection.error).not.toContain("events_only");+ expect(rejection.error).not.toContain("LANGFUSE_MIGRATION_V4_WRITE_MODE");+ expect(vi.mocked(processEventBatch).mock.calls[0][0]).toEqual([+ mixedBatch[1],+ ]);+ expect(recordIncrement).toHaveBeenCalledTimes(1);+ expect(recordIncrement).toHaveBeenCalledWith(+ "langfuse.public_api.legacy_ingestion_non_score_rejected",+ 3,+ { route: "POST /api/public/ingestion" },+ );+ },+ );++ it("keeps ingestion unchanged when the scope has no organization createdAt", async () => {+ legacyIngestionGate.scoreOnlyCutoff = CUTOFF;+ authorizeOrg(undefined);++ const res = await postBatch();++ expect(res._getJSONData().errors).toEqual([]);+ expect(vi.mocked(processEventBatch).mock.calls[0][0]).toEqual(mixedBatch);+ expect(recordIncrement).not.toHaveBeenCalled();+ });+});+describe("ingestion per-event shadow comparison", () => {beforeEach(() => {migration.mode = "shadow";+ legacyIngestionGate.writeMode = "dual";+ legacyIngestionGate.scoreOnlyCutoff = undefined;shadowAuth.mockReset();recordIncrement.mockClear();- vi.mocked(processEventBatch).mockClear();+ vi.mocked(processEventBatch).mockReset();+ vi.mocked(processEventBatch).mockImplementation((input, auth, options) =>+ originalProcessEventBatch.current!(input, auth, options),+ );});it.each([diff --git a/web/src/env.mjs b/web/src/env.mjsindex 2ec3bbda04..168c6a4774 100644--- a/web/src/env.mjs+++ b/web/src/env.mjs@@ -650,6 +650,12 @@ export const env = createEnv({LANGFUSE_API_ORGANIZATION_CUTOFF_DATE: z.iso.datetime().default("2026-09-16T00:00:00.000Z"),+ // Organizations created at or after this instant take the v4 events_only+ // path on legacy ingestion. Unset leaves that API unchanged. Read on the+ // web request path; the worker never re-checks event types.+ LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF: z.iso+ .datetime()+ .optional(),// V4 preview opt-in. See LFE-9778. Defaults on for the v4 target state so// the events read paths are available out of the box (v3 shipped "false").@@ -1268,6 +1274,8 @@ export const env = createEnv({process.env.LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED,LANGFUSE_API_ORGANIZATION_CUTOFF_DATE:process.env.LANGFUSE_API_ORGANIZATION_CUTOFF_DATE,+ LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF:+ process.env.LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF,LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN:process.env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN,LANGFUSE_MIGRATION_V4_WRITE_MODE:diff --git a/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts b/web/src/features/public-api/server/createAuthedProjectAPIRoute.tsindex 5d06a8cb1d..eb576286f9 100644--- a/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts+++ b/web/src/features/public-api/server/createAuthedProjectAPIRoute.ts@@ -34,13 +34,29 @@ import {type PublicApiErrorContract,} from "./structuredPublicApiErrorContract";import { clickHouseRouteForRequest } from "@/src/features/public-api/server/clickHouseRequestTags";-import { sendAuthErrorJson } from "@/src/features/public-api/server/deprecations";+import {+ EVENTS_ONLY_UNAVAILABLE_MESSAGE,+ LEGACY_INGESTION_ORG_CUTOFF_MESSAGE,+ sendAuthErrorJson,+} from "@/src/features/public-api/server/deprecations";import { applyLegacyApiOrganizationCutoff } from "@/src/features/public-api/server/legacyApiOrganizationCutoff";+import {+ isLegacyIngestionScoreOnlyOrg,+ recordLegacyIngestionScoreOnlyRejection,+} from "@/src/features/public-api/server/legacyIngestionScoreOnlyCutoff";import { type RouteAccessLevel } from "@/src/features/public-api/server/verifyProjectApiKeyAuth";import { shadowAuth } from "@/src/features/public-api/server/shadowAuth";import { type ProjectAction } from "@langfuse/shared/rbac";import { type AuthorizationContext } from "@/src/features/auth/policy/types";+const EVENTS_ONLY_UNAVAILABLE_BODY = {+ message: EVENTS_ONLY_UNAVAILABLE_MESSAGE,+};++const ORG_CUTOFF_UNAVAILABLE_BODY = {+ message: LEGACY_INGESTION_ORG_CUTOFF_MESSAGE,+};+// Next's res.json uses JSON.stringify; V8 throws this when the JSON string// exceeds the engine limit. Keep this check scoped to the response write.const isJsonStringTooLargeError = (error: unknown): error is RangeError =>@@ -125,6 +141,12 @@ export type AuthedProjectAPIRouteConfig<* events_only mode and would silently return stale or empty data.*/rejectInEventsOnlyMode?: boolean;+ /**+ * Marks a legacy trace or observation write. Organizations created on or+ * after LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF get a 404+ * pointing them to the SDKs and the OpenTelemetry endpoint.+ */+ isLegacyTraceWrite?: boolean;/** Marks the route as deprecated; withMiddlewares stamps it onto every JSON response and sets deprecation headers. */deprecation?: ApiDeprecationInfo;fn: (params: {@@ -164,10 +186,7 @@ export const createAuthedProjectAPIRoute = <routeConfig.rejectInEventsOnlyMode &&env.LANGFUSE_MIGRATION_V4_WRITE_MODE === "events_only") {- res.status(404).json({- message:- "This endpoint is not available on deployments running in Langfuse v4 events_only mode. Learn more about Langfuse v4 at: https://langfuse.com/docs/v4",- });+ res.status(404).json(EVENTS_ONLY_UNAVAILABLE_BODY);return;}@@ -273,6 +292,20 @@ export const createAuthedProjectAPIRoute = <return;}+ if (+ routeConfig.isLegacyTraceWrite &&+ isLegacyIngestionScoreOnlyOrg(auth.scope.organizationCreatedAt)+ ) {+ recordLegacyIngestionScoreOnlyRejection({+ route: routeConfig.name,+ count: 1,+ orgId: auth.scope.orgId,+ projectId: auth.scope.projectId,+ });+ res.status(404).json(ORG_CUTOFF_UNAVAILABLE_BODY);+ return;+ }+logger.debug(`Request to route ${routeConfig.name} projectId ${auth.scope.projectId}`,);diff --git a/web/src/features/public-api/server/deprecations.ts b/web/src/features/public-api/server/deprecations.tsindex 6fceb17319..c12e8ae091 100644--- a/web/src/features/public-api/server/deprecations.ts+++ b/web/src/features/public-api/server/deprecations.ts@@ -49,8 +49,28 @@ const DOCS = {otel: "https://langfuse.com/integrations/native/opentelemetry",otelMigration:"https://langfuse.com/integrations/native/opentelemetry/migration-to-v4.md",+ sdkUpgrade: "https://langfuse.com/docs/observability/sdk/upgrade-path",+ v4: "https://langfuse.com/docs/v4",+ selfHostedV4Upgrade:+ "https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4",} as const;+/** LEGACY_TRACE_WRITE_REPLACEMENT is the SDK and OpenTelemetry pointer shared by legacy trace-write rejections. */+const LEGACY_TRACE_WRITE_REPLACEMENT = `Upgrade to the latest Langfuse SDKs, which send traces via OpenTelemetry, or send traces directly to ${REPLACEMENT.otelTraces}. Scores can still be sent via ${REPLACEMENT.scoreCreate}. Docs: ${DOCS.sdkUpgrade} ${DOCS.otelMigration}`;++/** LEGACY_INGESTION_ORG_CUTOFF_MESSAGE is the rejection for an organization created at or after the legacy-ingestion cutoff. */+export const LEGACY_INGESTION_ORG_CUTOFF_MESSAGE = `This ingestion API no longer accepts trace or observation writes for this organization. ${LEGACY_TRACE_WRITE_REPLACEMENT}`;++/** EVENTS_ONLY_UNAVAILABLE_MESSAGE is the 404 for a deployment in v4 events_only mode. */+export const EVENTS_ONLY_UNAVAILABLE_MESSAGE = `This endpoint is not available on deployments running in Langfuse v4 events_only mode. ${LEGACY_TRACE_WRITE_REPLACEMENT} Learn more about Langfuse v4 at ${DOCS.v4}.`;++/** EVENTS_ONLY_INGESTION_REMEDIATION is the per-event remediation for the legacy batch endpoint in events_only mode. */+export const EVENTS_ONLY_INGESTION_REMEDIATION = [+ LEGACY_TRACE_WRITE_REPLACEMENT,+ "As a temporary migration bridge, set LANGFUSE_MIGRATION_V4_WRITE_MODE=dual on both the web and worker services and redeploy.",+ `Self-hosted upgrade guide: ${DOCS.selfHostedV4Upgrade}`,+].join(" ");+export const OBSERVATIONS_V1_DEPRECATION: ApiDeprecationInfo = {message: v3Notice(`Use ${REPLACEMENT.observationsV2} instead.`),replacement: REPLACEMENT.observationsV2,diff --git a/web/src/features/public-api/server/legacyIngestionScoreOnlyCutoff.ts b/web/src/features/public-api/server/legacyIngestionScoreOnlyCutoff.tsnew file mode 100644index 0000000000..07f2de00b9--- /dev/null+++ b/web/src/features/public-api/server/legacyIngestionScoreOnlyCutoff.ts@@ -0,0 +1,47 @@+import { logger, recordIncrement } from "@langfuse/shared/src/server";++import { env } from "@/src/env.mjs";++const LEGACY_INGESTION_NON_SCORE_REJECTED_METRIC =+ "langfuse.public_api.legacy_ingestion_non_score_rejected";++/**+ * isLegacyIngestionScoreOnlyOrg reports whether this organization takes the+ * v4 events_only ingestion path. An unset cutoff, a missing+ * organizationCreatedAt, or a timestamp that does not parse leaves ingestion+ * unchanged. Organizations created at the cutoff instant are included.+ */+export function isLegacyIngestionScoreOnlyOrg(+ organizationCreatedAt: string | null | undefined,+): boolean {+ const cutoff = env.LANGFUSE_LEGACY_INGESTION_SCORE_ONLY_ORG_CREATED_CUTOFF;+ if (!cutoff || !organizationCreatedAt) return false;++ const createdAtMs = Date.parse(organizationCreatedAt);+ const cutoffMs = Date.parse(cutoff);+ if (Number.isNaN(createdAtMs) || Number.isNaN(cutoffMs)) return false;+ return createdAtMs >= cutoffMs;+}++/** recordLegacyIngestionScoreOnlyRejection counts events the organization cutoff rejected. `route` is the only tag. */+export function recordLegacyIngestionScoreOnlyRejection(params: {+ route: string;+ count: number;+ orgId?: string;+ projectId?: string;+}): void {+ if (params.count <= 0) return;++ recordIncrement(LEGACY_INGESTION_NON_SCORE_REJECTED_METRIC, params.count, {+ route: params.route,+ });+ logger.info(+ "Rejected legacy ingestion writes for organization created at or after cutoff",+ {+ route: params.route,+ rejectedEventCount: params.count,+ orgId: params.orgId,+ projectId: params.projectId,+ },+ );+}diff --git a/web/src/pages/api/public/events.ts b/web/src/pages/api/public/events.tsindex 9cd84cd72f..6deae447ed 100644--- a/web/src/pages/api/public/events.ts+++ b/web/src/pages/api/public/events.ts@@ -22,6 +22,7 @@ export default withMiddlewares({// Writes an observation-create event that lands in the legacy observations// ClickHouse table; events_only deployments expect OTel ingestion.rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,deprecation: LEGACY_WRITES_DEPRECATION,fn: async ({ body, auth, req, res }) => {const event = {diff --git a/web/src/pages/api/public/generations.ts b/web/src/pages/api/public/generations.tsindex a12559ebfe..e82d8f0659 100644--- a/web/src/pages/api/public/generations.ts+++ b/web/src/pages/api/public/generations.ts@@ -25,6 +25,7 @@ export default withMiddlewares({// Writes an observation-create event that lands in the legacy observations// ClickHouse table; events_only deployments expect OTel ingestion.rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,deprecation: LEGACY_WRITES_DEPRECATION,fn: async ({ body, auth, req, res }) => {const { prompt, completion, ...rest } = body;@@ -69,6 +70,7 @@ export default withMiddlewares({responseSchema: PatchGenerationsV1Response,rateLimitResource: "legacy-ingestion",rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,deprecation: LEGACY_WRITES_DEPRECATION,fn: async ({ body, auth, req, res }) => {const { generationId, prompt, completion, ...rest } = body;diff --git a/web/src/pages/api/public/ingestion.ts b/web/src/pages/api/public/ingestion.tsindex 1ebf33eddd..35f60a7b0a 100644--- a/web/src/pages/api/public/ingestion.ts+++ b/web/src/pages/api/public/ingestion.ts@@ -29,7 +29,9 @@ import * as opentelemetry from "@opentelemetry/api";import { env } from "@/src/env.mjs";import {attachDeprecation,+ EVENTS_ONLY_INGESTION_REMEDIATION,INGESTION_DEPRECATION,+ LEGACY_INGESTION_ORG_CUTOFF_MESSAGE,setDeprecationHeaders,} from "@/src/features/public-api/server/deprecations";import {@@ -47,6 +49,10 @@ import {unauthorizedError,type AuthorizationContext,} from "@/src/features/auth/policy/types";+import {+ isLegacyIngestionScoreOnlyOrg,+ recordLegacyIngestionScoreOnlyRejection,+} from "@/src/features/public-api/server/legacyIngestionScoreOnlyCutoff";export const config = {api: {@@ -181,14 +187,27 @@ export default async function handler(// V4 events_only mode: refuse every non-score event because trace and// observation writes target legacy ClickHouse tables this deployment- // no longer reads. SDK logs are no longer accepted in this mode.- // Reject per-event so a mixed batch still processes its score events.+ // no longer reads. Organizations created at or after the cutoff get the+ // same allow-list. SDK logs are refused too. Reject per-event so a+ // mixed batch still processes its score events.const isEventsOnlyMode =env.LANGFUSE_MIGRATION_V4_WRITE_MODE === "events_only";+ const scoreOnlyReason = scoreOnlyReasonFor(+ isEventsOnlyMode,+ scope.organizationCreatedAt,+ );const { batchForProcessing, rejectedErrors } = filterBatchForEventsOnly(parsedSchema.data.batch,- isEventsOnlyMode,+ scoreOnlyReason,);+ if (scoreOnlyReason === "org_cutoff") {+ recordLegacyIngestionScoreOnlyRejection({+ route: "POST /api/public/ingestion",+ count: rejectedErrors.length,+ orgId: scope.orgId,+ projectId,+ });+ }const attribution = createIngestionAttribution({headers: req.headers,@@ -298,7 +317,7 @@ export default async function handler(}// Scores keep their own ClickHouse table and are the only event type accepted-// by this endpoint in V4 events_only mode.+// by this endpoint in V4 events_only mode and for cutoff organizations.const EVENTS_ONLY_ALLOWED_TYPES = new Set<string>([eventTypes.SCORE_CREATE]);const TRACE_OR_OBSERVATION_EVENT_TYPES = new Set<string>(@@ -310,20 +329,28 @@ const TRACE_OR_OBSERVATION_EVENT_TYPES = new Set<string>(),);-const EVENTS_ONLY_INGESTION_DOCS_URL =- "https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4";+/** ScoreOnlyReason is why this request may only ingest scores; it picks the rejection text. */+type ScoreOnlyReason = "events_only" | "org_cutoff";-const EVENTS_ONLY_INGESTION_REMEDIATION = [- "Upgrade the client or integration to a v4-compatible SDK or OTLP ingestion path.",- "As a temporary migration bridge, set LANGFUSE_MIGRATION_V4_WRITE_MODE=dual on both the web and worker services and redeploy.",- `Docs: ${EVENTS_ONLY_INGESTION_DOCS_URL}`,-].join(" ");+const SCORE_ONLY_REJECTION: Record<ScoreOnlyReason, string> = {+ events_only: `is not accepted by /api/public/ingestion when LANGFUSE_MIGRATION_V4_WRITE_MODE is events_only. This endpoint only accepts score events. ${EVENTS_ONLY_INGESTION_REMEDIATION}`,+ org_cutoff: `is not accepted. ${LEGACY_INGESTION_ORG_CUTOFF_MESSAGE}`,+};++function scoreOnlyReasonFor(+ isEventsOnlyMode: boolean,+ organizationCreatedAt: string | null | undefined,+): ScoreOnlyReason | null {+ if (isEventsOnlyMode) return "events_only";+ if (isLegacyIngestionScoreOnlyOrg(organizationCreatedAt)) return "org_cutoff";+ return null;+}export function filterBatchForEventsOnly(batch: unknown[],- isEventsOnlyMode: boolean,+ scoreOnlyReason: ScoreOnlyReason | null,): IngestionBatchFilter {- if (!isEventsOnlyMode) {+ if (!scoreOnlyReason) {return { batchForProcessing: batch, rejectedErrors: [] };}@@ -347,7 +374,7 @@ export function filterBatchForEventsOnly(id,status: 400,message: "Event type not accepted",- error: `Event type "${type ?? "unknown"}" is not accepted by /api/public/ingestion when LANGFUSE_MIGRATION_V4_WRITE_MODE is events_only. This endpoint only accepts score events. ${EVENTS_ONLY_INGESTION_REMEDIATION}`,+ error: `Event type "${type ?? "unknown"}" ${SCORE_ONLY_REJECTION[scoreOnlyReason]}`,});}}diff --git a/web/src/pages/api/public/spans.ts b/web/src/pages/api/public/spans.tsindex 458f0bc75f..3c5bea746e 100644--- a/web/src/pages/api/public/spans.ts+++ b/web/src/pages/api/public/spans.ts@@ -24,6 +24,7 @@ export default withMiddlewares({// Writes an observation-create event that lands in the legacy observations// ClickHouse table; events_only deployments expect OTel ingestion.rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,deprecation: LEGACY_WRITES_DEPRECATION,fn: async ({ body, auth, req, res }) => {const event = {@@ -64,6 +65,7 @@ export default withMiddlewares({bodySchema: PatchSpansV1Body,responseSchema: PatchSpansV1Response,rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,deprecation: LEGACY_WRITES_DEPRECATION,fn: async ({ body, auth, req, res }) => {const event = {diff --git a/web/src/pages/api/public/traces/index.ts b/web/src/pages/api/public/traces/index.tsindex f0e566e5f4..d78a167ea4 100644--- a/web/src/pages/api/public/traces/index.ts+++ b/web/src/pages/api/public/traces/index.ts@@ -48,6 +48,7 @@ export default withMiddlewares(// Legacy POST writes a trace-create event that lands in the legacy traces// ClickHouse table; events_only deployments expect OTel ingestion.rejectInEventsOnlyMode: true,+ isLegacyTraceWrite: true,deprecation: LEGACY_WRITES_DEPRECATION,fn: async ({ body, auth, req, res }) => {await telemetry();