Skip to content

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

fix(ingestion): add events_only rejection guidance (#15950)

Valery Meleshkin288fc65c4f9a
diff --git a/web/src/pages/api/public/ingestion.ts b/web/src/pages/api/public/ingestion.ts
index b3ea3f096b..c03ee435de 100644
--- a/web/src/pages/api/public/ingestion.ts
+++ b/web/src/pages/api/public/ingestion.ts
@@ -151,16 +151,30 @@ export default async function handler(
// writes would land in the legacy ClickHouse tables this deployment no
// longer reads. Scores and SDK logs are unaffected and pass through.
// Reject per-event so a mixed batch still processes its score events.
+ const isEventsOnlyMode =
+ env.LANGFUSE_MIGRATION_V4_WRITE_MODE === "events_only";
const { batchForProcessing, rejectedErrors } = filterBatchForEventsOnly(
parsedSchema.data.batch,
- env.LANGFUSE_MIGRATION_V4_WRITE_MODE === "events_only",
+ isEventsOnlyMode,
);
+ const attribution = createIngestionAttribution({
+ headers: req.headers,
+ authCheck,
+ });
+
+ if (isEventsOnlyMode && rejectedErrors.length > 0) {
+ logger.warn(
+ `Rejected ${rejectedErrors.length} event(s) from the legacy /api/public/ingestion endpoint for project ${projectId} because this Langfuse v4 deployment runs in events_only mode. These events were not stored. ${EVENTS_ONLY_INGESTION_REMEDIATION}`,
+ {
+ sdkName: attribution.ingestionSdkName,
+ sdkVersion: attribution.ingestionSdkVersion,
+ },
+ );
+ }
+
const result = await processEventBatch(batchForProcessing, authCheck, {
- attribution: createIngestionAttribution({
- headers: req.headers,
- authCheck,
- }),
+ attribution,
});
if (rejectedErrors.length > 0) {
result.errors = [...result.errors, ...rejectedErrors];
@@ -236,6 +250,15 @@ const EVENTS_ONLY_ALLOWED_TYPES = new Set<string>([
eventTypes.SDK_LOG,
]);
+const EVENTS_ONLY_INGESTION_DOCS_URL =
+ "https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4";
+
+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(" ");
+
function filterBatchForEventsOnly(
batch: unknown[],
isEventsOnlyMode: boolean,
@@ -277,7 +300,7 @@ 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 and log events.`,
+ 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 and log events. ${EVENTS_ONLY_INGESTION_REMEDIATION}`,
});
}
}