Skip to content

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

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.yml
index 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/opentelemetry
Within 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 APIs
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index 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 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. 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 upgrade
guide](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/opentelemetry
Within each batch, there can be multiple events.
@@ -14095,6 +14104,9 @@ components:
type: array
items:
$ref: '#/components/schemas/IngestionError'
+ _deprecation:
+ $ref: '#/components/schemas/Deprecation'
+ nullable: true
required:
- successes
- errors
diff --git a/web/src/__tests__/server/deprecation-signal.servertest.ts b/web/src/__tests__/server/deprecation-signal.servertest.ts
index 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.ts
index 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.ts
index 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.ts
index 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);
+ });
+}