🪢 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): attach _deprecation to successful legacy ingestion writes (#17261)
Max Deichmannc974e07655f0
diff --git a/fern/apis/server/definition/ingestion.yml b/fern/apis/server/definition/ingestion.ymlindex e8cca823cf..9c0d50f5af 100644--- a/fern/apis/server/definition/ingestion.yml+++ b/fern/apis/server/definition/ingestion.yml@@ -9,11 +9,11 @@ service:batch:availability:status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. Send data via the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` instead, see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."+ message: "On Langfuse Cloud, Langfuse v3 is deprecated and v4-only write mode begins on November 16, 2026. This endpoint is never shut down; it continues to accept score events. Trace and observation events fail only in v4-only write mode, not in dual or legacy mode. Always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, only then send data via the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` (for example with curl); see the [OpenTelemetry integration docs](https://langfuse.com/integrations/native/opentelemetry). Self-hosted deployments are unaffected by this date; they reject trace and observation events only in v4-only write mode, not dual or legacy."docs: |**Legacy endpoint for batch ingestion for Langfuse Observability.**- -> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`). Learn more: https://langfuse.com/integrations/native/opentelemetry+ This endpoint is never shut down. Trace and observation events are rejected only in v4-only write mode (not dual or legacy); score events continue to be accepted. Always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, only then send traces via the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for example with curl. Learn more: https://langfuse.com/integrations/native/opentelemetryWithin each batch, there can be multiple events.Each event has a type, an id, a timestamp, metadata and a body.@@ -420,6 +420,7 @@ types:properties:successes: list<IngestionSuccess>errors: list<IngestionError>+ _deprecation: optional<commons.Deprecation>OpenAICompletionUsageSchema:docs: OpenAI Usage schema from (Chat-)Completion APIsdiff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex d210ac9ee3..54d6d395a2 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -2771,22 +2771,31 @@ paths:/api/public/ingestion:post:description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. Send data via the- OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` instead, see- the [OpenTelemetry integration+ **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and v4-only+ write mode begins on November 16, 2026. This endpoint is never shut+ down; it continues to accept score events. Trace and observation events+ fail only in v4-only write mode, not in dual or legacy mode. Always+ prefer upgrading to the current Python and JS SDKs. If you use custom+ auto-instrumentation, only then send data via the OpenTelemetry endpoint+ at `POST /api/public/otel/v1/traces` (for example with curl); see the+ [OpenTelemetry integrationdocs](https://langfuse.com/integrations/native/opentelemetry).- Self-hosted deployments are unaffected by this date; the endpoint- becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse- v3 to v4 upgrade+ Self-hosted deployments are unaffected by this date; they reject trace+ and observation events only in v4-only write mode, not dual or legacy.+ See the [Langfuse v3 to v4 upgradeguide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).**Legacy endpoint for batch ingestion for Langfuse Observability.**- -> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`).- Learn more: https://langfuse.com/integrations/native/opentelemetry+ This endpoint is never shut down. Trace and observation events are+ rejected only in v4-only write mode (not dual or legacy); score events+ continue to be accepted. Always prefer upgrading to the current Python+ and JS SDKs. If you use custom auto-instrumentation, only then send+ traces via the OpenTelemetry endpoint (`POST+ /api/public/otel/v1/traces`), for example with curl. Learn more:+ https://langfuse.com/integrations/native/opentelemetryWithin each batch, there can be multiple events.@@ -14095,6 +14104,9 @@ components:type: arrayitems:$ref: '#/components/schemas/IngestionError'+ _deprecation:+ $ref: '#/components/schemas/Deprecation'+ nullable: truerequired:- successes- errorsdiff --git a/web/src/__tests__/server/deprecation-signal.servertest.ts b/web/src/__tests__/server/deprecation-signal.servertest.tsindex 7950f85d0a..94df819317 100644--- a/web/src/__tests__/server/deprecation-signal.servertest.ts+++ b/web/src/__tests__/server/deprecation-signal.servertest.ts@@ -15,6 +15,7 @@ import {import {DATASET_RUN_ITEMS_DEPRECATION,DATASET_RUNS_DEPRECATION,+ INGESTION_DEPRECATION,OBSERVATIONS_V1_DEPRECATION,SCORES_DEPRECATION,SESSIONS_DEPRECATION,@@ -209,4 +210,112 @@ describe("public API deprecation signal", () => {DATASET_RUNS_DEPRECATION,);});++ it("attaches `_deprecation` to POST /ingestion when the batch writes a trace", async () => {+ const response = await makeAPICall(+ "POST",+ "/api/public/ingestion",+ {+ batch: [+ {+ id: randomUUID(),+ type: "trace-create",+ timestamp: new Date().toISOString(),+ body: {+ id: randomUUID(),+ timestamp: new Date().toISOString(),+ },+ },+ ],+ },+ auth,+ );++ expect(response.status).toBe(207);+ expect((response.body as Record<string, unknown>)._deprecation).toEqual(+ INGESTION_DEPRECATION,+ );+ expect(INGESTION_DEPRECATION.replacement).toBe(+ "POST /api/public/otel/v1/traces",+ );+ expect(INGESTION_DEPRECATION.message).toContain(+ "Always prefer upgrading to the current Python and JS SDKs",+ );+ expect(INGESTION_DEPRECATION.message).toContain(+ "custom auto-instrumentation",+ );+ expect(INGESTION_DEPRECATION.message).toContain("curl");+ expect(INGESTION_DEPRECATION.message).toContain(+ "GET /api/public/v2/observations",+ );+ expect(INGESTION_DEPRECATION.message).toContain(+ "GET /api/public/v2/metrics",+ );+ });++ it("attaches `_deprecation` to POST /ingestion when a mixed batch includes an observation", async () => {+ const response = await makeAPICall(+ "POST",+ "/api/public/ingestion",+ {+ batch: [+ {+ id: randomUUID(),+ type: "score-create",+ timestamp: new Date().toISOString(),+ body: {+ id: randomUUID(),+ name: "score-name",+ traceId: randomUUID(),+ value: 1,+ },+ },+ {+ id: randomUUID(),+ type: "span-create",+ timestamp: new Date().toISOString(),+ body: {+ id: randomUUID(),+ traceId: randomUUID(),+ startTime: new Date().toISOString(),+ },+ },+ ],+ },+ auth,+ );++ expect(response.status).toBe(207);+ expect((response.body as Record<string, unknown>)._deprecation).toEqual(+ INGESTION_DEPRECATION,+ );+ });++ it("omits `_deprecation` from POST /ingestion when the batch is only scores", async () => {+ const response = await makeAPICall(+ "POST",+ "/api/public/ingestion",+ {+ batch: [+ {+ id: randomUUID(),+ type: "score-create",+ timestamp: new Date().toISOString(),+ body: {+ id: randomUUID(),+ name: "score-name",+ traceId: randomUUID(),+ value: 1,+ },+ },+ ],+ },+ auth,+ );++ expect(response.status).toBe(207);+ expect(+ (response.body as Record<string, unknown>)._deprecation,+ ).toBeUndefined();+ });});diff --git a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts b/web/src/__tests__/server/unit/openapi-deprecations.servertest.tsindex 04f70cdbb8..61dfc71b5d 100644--- a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts+++ b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts@@ -14,6 +14,7 @@ import {import {DATASET_RUN_ITEMS_DEPRECATION,DATASET_RUNS_DEPRECATION,+ INGESTION_DEPRECATION,METRICS_DEPRECATION,OBSERVATIONS_V1_DEPRECATION,SCORES_DEPRECATION,@@ -135,6 +136,16 @@ describe("OpenAPI deprecations", () => {definitionDirectory,)) {const operation = `${method.toUpperCase()} ${endpointPath}`;+ const isIngestion =+ method === "post" && endpointPath === "/api/public/ingestion";++ // Ingestion is not removed: v4-only write mode rejects traces, scores stay.+ if (isIngestion) {+ expect(message, operation).toContain(V3_SUNSET_HUMAN);+ expect(message, operation).not.toContain("will be removed");+ expect(message, operation).not.toContain("becomes unavailable");+ continue;+ }expect(message, operation).toContain(`will be removed on ${V3_SUNSET_HUMAN}.`,@@ -177,6 +188,7 @@ describe("OpenAPI deprecations", () => {METRICS_DEPRECATION,DATASET_RUN_ITEMS_DEPRECATION,DATASET_RUNS_DEPRECATION,+ INGESTION_DEPRECATION,];for (const family of families) {@@ -184,6 +196,36 @@ describe("OpenAPI deprecations", () => {}});+ it("tells legacy ingestion callers to prefer Python and JS SDKs over curl", () => {+ expect(INGESTION_DEPRECATION.message).toContain(+ "Always prefer upgrading to the current Python and JS SDKs",+ );+ expect(INGESTION_DEPRECATION.message).toContain(+ "custom auto-instrumentation",+ );+ expect(INGESTION_DEPRECATION.message).toContain("curl");++ const ingestion = getFernDeprecatedOperations(definitionDirectory).find(+ ({ method, endpointPath }) =>+ method === "post" && endpointPath === "/api/public/ingestion",+ );+ expect(ingestion?.message).toContain(+ "Always prefer upgrading to the current Python and JS SDKs",+ );+ expect(ingestion?.message).toContain("custom auto-instrumentation");+ expect(ingestion?.message).toContain("curl");+ expect(INGESTION_DEPRECATION.message).toContain("never shut down");+ expect(INGESTION_DEPRECATION.message).toContain("score events");+ expect(INGESTION_DEPRECATION.message).toContain("v4-only write mode");+ expect(INGESTION_DEPRECATION.message).toContain(+ "not in dual or legacy mode",+ );+ expect(ingestion?.message).toContain("never shut down");+ expect(ingestion?.message).toContain("score events");+ expect(ingestion?.message).toContain("v4-only write mode");+ expect(ingestion?.message).toContain("not in dual or legacy mode");+ });+it("supports deprecated endpoints at a service base path", () => {withDefinition({diff --git a/web/src/features/public-api/server/deprecations.ts b/web/src/features/public-api/server/deprecations.tsindex bd0ab3f0d3..5f9167d1a0 100644--- a/web/src/features/public-api/server/deprecations.ts+++ b/web/src/features/public-api/server/deprecations.ts@@ -42,6 +42,8 @@ const DOCS = {metricsV2: "https://langfuse.com/docs/metrics/features/metrics-api",compatibility: "https://langfuse.com/docs/compatibility",otel: "https://langfuse.com/integrations/native/opentelemetry",+ otelMigration:+ "https://langfuse.com/integrations/native/opentelemetry/migration-to-v4.md",} as const;export const OBSERVATIONS_V1_DEPRECATION: ApiDeprecationInfo = {@@ -99,6 +101,17 @@ export const DATASET_RUNS_DEPRECATION: ApiDeprecationInfo = {sunsetAt: V3_SUNSET_DATE,};+// Legacy batch writes of traces/observations → OTLP. This route is never+// removed: scores (and sdk-log) stay accepted. Trace/observation events are+// rejected only in v4-only write mode, not dual or legacy — so this family+// does not use V3_NOTICE ("endpoint will be removed").+export const INGESTION_DEPRECATION: ApiDeprecationInfo = {+ message: `On Langfuse Cloud, Langfuse v3 is deprecated and v4-only write mode begins on ${V3_SUNSET_HUMAN}. ${V3_DELAY_NOTICE} This endpoint is never shut down; it continues to accept score events. Trace and observation events fail only in v4-only write mode, not in dual or legacy mode. Always prefer upgrading to the current Python and JS SDKs. If you use custom auto-instrumentation, only then write traces and observations via ${REPLACEMENT.otelTraces} (for example with curl). Retrieve the data via ${REPLACEMENT.observationsV2} and ${REPLACEMENT.metricsV2}.`,+ replacement: REPLACEMENT.otelTraces,+ docsUrl: DOCS.otelMigration,+ sunsetAt: V3_SUNSET_DATE,+};+// Stamp a deprecation signal onto a JSON response body as the top-level// `_deprecation` key. Non-object bodies (arrays, null, primitives) pass through// unchanged so array/primitive responses are never corrupted.diff --git a/web/src/pages/api/public/ingestion.ts b/web/src/pages/api/public/ingestion.tsindex 618af7df63..802a0f3f70 100644--- a/web/src/pages/api/public/ingestion.ts+++ b/web/src/pages/api/public/ingestion.ts@@ -27,6 +27,10 @@ import { ApiAuthService } from "@/src/features/public-api/server/apiAuth";import { RateLimitService } from "@/src/features/public-api/server/RateLimitService";import * as opentelemetry from "@opentelemetry/api";import { env } from "@/src/env.mjs";+import {+ attachDeprecation,+ INGESTION_DEPRECATION,+} from "@/src/features/public-api/server/deprecations";import {SDK_NAME_ATTRIBUTE,SDK_VERSION_ATTRIBUTE,@@ -194,7 +198,17 @@ export default async function handler(if (rejectedErrors.length > 0) {result.errors = [...result.errors, ...rejectedErrors];}- return res.status(207).json(result);++ // Cloud-only: a 207 with every event 201 is how agents conclude the+ // legacy write path is healthy. Stamp when the original batch asked+ // to write a trace or observation, including events_only rejections.+ const deprecation =+ env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION &&+ batchContainsTraceOrObservationEvent(parsedSchema.data.batch)+ ? INGESTION_DEPRECATION+ : undefined;++ return res.status(207).json(attachDeprecation(result, deprecation));} catch (error) {if (!(error instanceof BaseError && error.isUserError())) {markProjectIngestFailure(projectId, {@@ -265,6 +279,15 @@ const EVENTS_ONLY_ALLOWED_TYPES = new Set<string>([eventTypes.SDK_LOG,]);+const TRACE_OR_OBSERVATION_EVENT_TYPES = new Set<string>(+ Object.values(eventTypes).filter(+ (type) =>+ type !== eventTypes.SCORE_CREATE &&+ type !== eventTypes.SDK_LOG &&+ type !== eventTypes.DATASET_RUN_ITEM_CREATE,+ ),+);+const EVENTS_ONLY_INGESTION_DOCS_URL ="https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4";@@ -322,3 +345,18 @@ function filterBatchForEventsOnly(return { batchForProcessing, rejectedErrors };}++function eventTypeOf(event: unknown): string | null {+ if (typeof event !== "object" || event === null) {+ return null;+ }+ const type = (event as { type?: unknown }).type;+ return typeof type === "string" ? type : null;+}++function batchContainsTraceOrObservationEvent(batch: unknown[]): boolean {+ return batch.some((event) => {+ const type = eventTypeOf(event);+ return type !== null && TRACE_OR_OBSERVATION_EVENT_TYPES.has(type);+ });+}