Skip to content

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

feat(api): limit legacy ingestion to scores for new organizations (#19042)

Max Deichmann348afb05ab23
diff --git a/.env.dev.example b/.env.dev.example
index 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.example
index 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,bar
diff --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.ts
index 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.ts
index 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.mjs
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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();