Skip to content

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

fix(api): fill observations pages with adaptive scan windows (#19043)

Valery Meleshkin41c8918b16c5
diff --git a/.env.dev.example b/.env.dev.example
index bf62943476..514938517c 100644
--- a/.env.dev.example
+++ b/.env.dev.example
@@ -425,6 +425,8 @@ LANGFUSE_MIGRATION_V4_WRITE_MODE=dual
# Self-hosted `dual` deployments must set this to `true` to offer users the V4
# preview toggle; with `dual` + `false` the preview stays unavailable to users.
LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true
+# Set to false to disable adaptive scan windows for observations v2 requests.
+# LANGFUSE_OBSERVATIONS_V2_ADAPTIVE_SCAN_ENABLED=true
# OTel ingestion behaviour: `dual_write` (SDK-version dispatch) or `direct`.
LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=dual_write
# Cloud-only rollout boundary (ISO date) for automatic direct OTel writes:
diff --git a/.env.prod.example b/.env.prod.example
index 6c000f8b19..8d2b6761e4 100644
--- a/.env.prod.example
+++ b/.env.prod.example
@@ -80,6 +80,10 @@ OTEL_SERVICE_NAME="langfuse"
# Enable experimental features, optional
# LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=false
+# Observations v2 adaptive scanning, enabled by default.
+# Set to false to query the full requested range without adaptive scan windows.
+# LANGFUSE_OBSERVATIONS_V2_ADAPTIVE_SCAN_ENABLED=true
+
# Reject deprecated GET APIs for Cloud organizations created on or after the cutoff date, optional (default: false)
# LANGFUSE_API_ORGANIZATION_CUTOFF_ENABLED=false
# LANGFUSE_API_ORGANIZATION_CUTOFF_DATE=2026-09-16T00:00:00.000Z
diff --git a/fern/apis/server/definition/observations.yml b/fern/apis/server/definition/observations.yml
index fcd5901970..78272e9d4e 100644
--- a/fern/apis/server/definition/observations.yml
+++ b/fern/apis/server/definition/observations.yml
@@ -15,7 +15,10 @@ service:
## Cursor-based Pagination
This endpoint uses cursor-based pagination for efficient traversal of large datasets.
The cursor is returned in the response metadata and should be passed in subsequent requests
- to retrieve the next page of results.
+ to retrieve the next page of results. The `limit` parameter is a maximum: a page may contain
+ fewer items than the requested limit, including zero items, while `meta.cursor` is present.
+ Continue requesting pages until `meta.cursor` is absent.
+ Requests without a lower start-time bound may search only from January 1, 2020.
## Field Selection
Use the `fields` parameter to control which observation fields are returned:
@@ -56,7 +59,7 @@ service:
Example: "key1,key2"
limit:
type: optional<integer>
- docs: Number of items to return per page. Maximum 1000, default 50.
+ docs: Maximum number of items to return per page. A page may contain fewer items, including zero items, while meta.cursor is present. Maximum 1000, default 50.
cursor:
type: optional<string>
docs: Base64-encoded cursor for pagination. Use the cursor from the previous response to get the next page.
@@ -224,7 +227,9 @@ types:
Response containing observations with field-group-based filtering and cursor-based pagination.
The `data` array contains observation objects with only the requested field groups included.
- Use the `cursor` in `meta` to retrieve the next page of results.
+ Use the `cursor` in `meta` to retrieve the next page of results. The array may contain fewer
+ than the requested `limit` items, or be empty, while a cursor is present. Continue until the
+ cursor is absent.
properties:
data:
type: list<commons.ObservationV2>
@@ -235,3 +240,7 @@ types:
docs: Metadata for cursor-based pagination.
extends:
- pagination.CursorMetaResponse
+ properties:
+ comment:
+ type: optional<string>
+ docs: Present when an empty page has a cursor; continue requesting pages until the cursor is absent.
diff --git a/packages/shared/src/server/queries/clickhouse-sql/filter-utils.ts b/packages/shared/src/server/queries/clickhouse-sql/filter-utils.ts
index 4629baeea4..629bdddd2f 100644
--- a/packages/shared/src/server/queries/clickhouse-sql/filter-utils.ts
+++ b/packages/shared/src/server/queries/clickhouse-sql/filter-utils.ts
@@ -1,5 +1,27 @@
import { convertDateToClickhouseDateTime } from "../../clickhouse/client";
-import { DateTimeFilter, type FilterList } from "./clickhouse-filter";
+import {
+ DateTimeFilter,
+ type Filter,
+ type FilterList,
+} from "./clickhouse-filter";
+
+/** Match a datetime field across table variants and optional SQL aliases. */
+export function isTimeFilter(
+ filter: Filter,
+ tableName: "events_proto" | "traces" = "events_proto",
+ fieldName: "start_time" | "timestamp" = "start_time",
+ prefix?: "e" | "t",
+): filter is DateTimeFilter {
+ const field = filter.field.replaceAll('"', "");
+ const expectedField = prefix ? `${prefix}.${fieldName}` : fieldName;
+ return (
+ filter instanceof DateTimeFilter &&
+ (tableName === "events_proto"
+ ? filter.clickhouseTable.startsWith("events_")
+ : filter.clickhouseTable === tableName) &&
+ (field === expectedField || (!prefix && field.endsWith(`.${fieldName}`)))
+ );
+}
/**
* Internal helper: extract and convert time filter from FilterList
@@ -11,20 +33,11 @@ export function extractTimeFilter(
fieldName: "start_time" | "timestamp" = "start_time",
prefix?: "e" | "t",
): string | null {
- const timeFilter = filter.find((filterItem) => {
- // For events tables, match any events_* prefix (events_proto, events_core, events_full)
- const normalizedField = filterItem.field.replaceAll('"', "");
- const expectedField = prefix ? `${prefix}.${fieldName}` : fieldName;
-
- return (
- (tableName === "events_proto"
- ? filterItem.clickhouseTable.startsWith("events_")
- : filterItem.clickhouseTable === tableName) &&
- (normalizedField === expectedField ||
- (!prefix && normalizedField.endsWith(`.${fieldName}`))) &&
- (filterItem.operator === ">=" || filterItem.operator === ">")
- );
- });
+ const timeFilter = filter.find(
+ (item) =>
+ isTimeFilter(item, tableName, fieldName, prefix) &&
+ (item.operator === ">=" || item.operator === ">"),
+ );
return timeFilter
? convertDateToClickhouseDateTime((timeFilter as DateTimeFilter).value)
diff --git a/packages/shared/src/server/repositories/events.test.ts b/packages/shared/src/server/repositories/events.test.ts
index 0be3b4ca53..a018033047 100644
--- a/packages/shared/src/server/repositories/events.test.ts
+++ b/packages/shared/src/server/repositories/events.test.ts
@@ -1,21 +1,51 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
const mockQueryClickhouse = vi.hoisted(() => vi.fn());
+const mockQueryClickhouseWithProgress = vi.hoisted(() => vi.fn());
let charCounter = 0;
-vi.mock("./clickhouse", () => ({
- queryClickhouse: mockQueryClickhouse,
- commandClickhouse: vi.fn(),
- queryClickhouseStream: vi.fn(),
- queryClickhouseStreamRawText: vi.fn(),
- queryClickhouseExecRaw: vi.fn(),
- parseClickhouseUTCDateTimeFormat: vi.fn(),
- BLOB_EXPORT_PARQUET_CLICKHOUSE_SETTINGS: {},
- // Return unique names per call so filter parameter variables don't collide
- clickhouseCompliantRandomCharacters: vi.fn(() => `x${++charCounter}`),
-}));
-
-import { getObservationsV2FromEventsTableForPublicApi } from "./events";
+vi.mock("./clickhouse", async () => {
+ const { isRow, isProgressRow, isException } =
+ await vi.importActual<typeof import("@clickhouse/client")>(
+ "@clickhouse/client",
+ );
+
+ return {
+ ClickHouseResourceError: class extends Error {
+ constructor(
+ public readonly errorType: string,
+ error: Error,
+ ) {
+ super(error.message);
+ }
+ static wrapIfResourceError(error: Error) {
+ return error;
+ }
+ },
+ ClickHouseQueryAbortedError: class extends Error {},
+ queryClickhouse: mockQueryClickhouse,
+ queryClickhouseWithProgress: mockQueryClickhouseWithProgress,
+ isRow,
+ isProgressRow,
+ isException,
+ commandClickhouse: vi.fn(),
+ queryClickhouseStream: vi.fn(),
+ queryClickhouseStreamRawText: vi.fn(),
+ queryClickhouseExecRaw: vi.fn(),
+ parseClickhouseUTCDateTimeFormat: vi.fn(
+ (value: string) => new Date(value.replace(" ", "T") + "Z"),
+ ),
+ BLOB_EXPORT_PARQUET_CLICKHOUSE_SETTINGS: {},
+ // Return unique names per call so filter parameter variables don't collide
+ clickhouseCompliantRandomCharacters: vi.fn(() => `x${++charCounter}`),
+ };
+});
+
+import {
+ getObservationsV2FromEventsTableForPublicApi,
+ getObservationsV2PageFromEventsTableForPublicApi,
+} from "./events";
+import { ClickHouseQueryAbortedError } from "./clickhouse";
import { type EventsTableFilterState } from "../../types";
const inputContainsFilter: EventsTableFilterState = [
@@ -27,15 +57,64 @@ const captureQuery = () => {
return (call?.[0] as { query: string }).query;
};
+const scanBounds = ({
+ query,
+ params,
+}: {
+ query: string;
+ params: Record<string, string>;
+}) =>
+ Object.fromEntries(
+ [...query.matchAll(/e\.start_time (>=|<=?) \{(\w+):/g)].map(
+ ([, operator, name]) => [operator === ">=" ? "from" : "to", params[name]],
+ ),
+ );
+
const baseOpts = { projectId: "proj-1", page: 1, limit: 50 } as const;
+const boundedOpts = {
+ ...baseOpts,
+ fields: ["core" as const],
+ fromStartTime: "2026-10-01T00:00:00.000Z",
+ toStartTime: "2026-10-19T00:00:00.000Z",
+};
+const observation = (id: string, startTime: string) => ({
+ id,
+ trace_id: "trace-1",
+ project_id: "proj-1",
+ start_time: startTime,
+ type: "SPAN",
+});
+
+const rowEvent = <T>(row: T) => ({ row });
+const progressEvent = (readRows: number, readBytes = 0) => ({
+ progress: {
+ read_rows: String(readRows),
+ read_bytes: String(readBytes),
+ elapsed_ns: "0",
+ },
+});
+const mockProgressQuery = (...events: unknown[]) => {
+ mockQueryClickhouseWithProgress.mockImplementationOnce(async function* () {
+ for (const event of events) yield event;
+ });
+};
+const mockProgressError = (error: Error) => {
+ mockQueryClickhouseWithProgress.mockImplementationOnce(async function* () {
+ yield progressEvent(0);
+ throw error;
+ });
+};
describe("getObservationsV2FromEventsTableForPublicApi query shape", () => {
beforeEach(() => {
charCounter = 0;
vi.clearAllMocks();
+ mockQueryClickhouseWithProgress.mockReset();
mockQueryClickhouse.mockResolvedValue([]);
});
+ afterEach(() => vi.restoreAllMocks());
+
it("skips the io-lane split when a content filter forces base onto events_full", async () => {
await getObservationsV2FromEventsTableForPublicApi(
{
@@ -70,4 +149,346 @@ describe("getObservationsV2FromEventsTableForPublicApi query shape", () => {
expect(query).toContain("FROM base");
expect(query).toContain("_io_start_time");
});
+
+ it("walks past empty windows, keeps the lookahead, and resumes with a row cursor", async () => {
+ mockProgressQuery(
+ rowEvent(observation("newer", "2026-10-12 00:00:00.000")),
+ );
+ mockProgressQuery(progressEvent(2_500_000));
+ mockProgressQuery(
+ rowEvent(observation("older", "2026-10-04 00:00:00.000")),
+ rowEvent(observation("lookahead", "2026-10-02 00:00:00.000")),
+ );
+
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...boundedOpts,
+ fields: ["core"],
+ limit: 2,
+ });
+
+ expect(page.items.map((row) => row.id)).toEqual(["newer", "older"]);
+ expect(page.cursor).toEqual({
+ lastStartTimeTo: new Date("2026-10-04T00:00:00.000Z"),
+ lastTraceId: "trace-1",
+ lastId: "older",
+ });
+ const calls = mockQueryClickhouseWithProgress.mock.calls.map(
+ ([opts]) => opts,
+ );
+ expect(calls.map((opts) => scanBounds(opts).from)).toEqual([
+ "2026-10-12 00:00:00.000",
+ "2026-10-05 00:00:00.000",
+ "2026-10-01 00:00:00.000",
+ ]);
+ expect(calls.map((opts) => opts.params.limit)).toEqual([3, 2, 2]);
+ });
+
+ it("returns no cursor once the effective structured time range is exhausted", async () => {
+ mockProgressQuery();
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...boundedOpts,
+ fields: ["core", "io"],
+ advancedFilters: [
+ {
+ type: "datetime",
+ column: "startTime",
+ operator: ">=",
+ value: new Date("2019-10-10T00:00:00Z"),
+ },
+ {
+ type: "datetime",
+ column: "startTime",
+ operator: "<=",
+ value: new Date("2019-10-11T00:00:00Z"),
+ },
+ ],
+ });
+
+ expect(page).toEqual({ items: [], cursor: undefined });
+ expect(mockQueryClickhouseWithProgress).toHaveBeenCalledTimes(1);
+ const call = mockQueryClickhouseWithProgress.mock.calls[0][0];
+ expect(scanBounds(call)).toEqual({
+ from: "2019-10-10 00:00:00.000",
+ to: "2019-10-11 00:00:00.000",
+ });
+ expect(
+ [
+ ...call.query.matchAll(
+ /e\.start_time (>=|<=?) \{\w+: (DateTime64\([^)]+\))\}/g,
+ ),
+ ]
+ .slice(-2)
+ .map((match) => match.slice(1)),
+ ).toEqual([
+ [">=", "DateTime64(3, 'UTC')"],
+ ["<=", "DateTime64(3, 'UTC')"],
+ ]);
+ expect(call.query).toContain("FROM base");
+ });
+
+ it.each([45_000, 46_000])(
+ "stops at the shared deadline: %i ms elapsed",
+ async (elapsed) => {
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ mockQueryClickhouseWithProgress.mockImplementationOnce(
+ async function* () {
+ clock.mockReturnValue(elapsed);
+ yield rowEvent(observation("newer", "2026-10-13 00:00:00.000"));
+ },
+ );
+
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...boundedOpts,
+ fields: ["core"],
+ });
+
+ expect(page.items.map((row) => row.id)).toEqual(["newer"]);
+ expect(page.cursor?.lastStartTimeTo).toEqual(
+ new Date("2026-10-12T00:00:00Z"),
+ );
+ expect(mockQueryClickhouseWithProgress).toHaveBeenCalledTimes(1);
+ },
+ );
+
+ it.each([30_000, 42_000, 44_999])(
+ "keeps filling the page before the deadline: %i ms elapsed",
+ async (elapsed) => {
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ mockQueryClickhouseWithProgress.mockImplementationOnce(
+ async function* () {
+ clock.mockReturnValue(elapsed);
+ yield progressEvent(0);
+ },
+ );
+ mockProgressQuery(
+ rowEvent(observation("older", "2026-10-11 00:00:00.000")),
+ rowEvent(observation("lookahead", "2026-10-10 00:00:00.000")),
+ );
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...boundedOpts,
+ limit: 1,
+ });
+ expect(page.items.map((row) => row.id)).toEqual(["older"]);
+ expect(page.cursor?.lastId).toBe("older");
+ const calls = mockQueryClickhouseWithProgress.mock.calls;
+ expect(calls).toHaveLength(2);
+ expect(calls[1][0].clickhouseSettings.max_execution_time).toBe(
+ (45_000 - elapsed) / 1_000,
+ );
+ },
+ );
+
+ it("resumes the interrupted window from the last completed boundary", async () => {
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ mockQueryClickhouseWithProgress.mockImplementationOnce(async function* () {
+ clock.mockReturnValue(5_000);
+ yield progressEvent(0);
+ });
+ mockQueryClickhouseWithProgress.mockImplementationOnce(async function* () {
+ yield rowEvent(observation("unfinished", "2026-10-11 00:00:00.000"));
+ clock.mockReturnValue(45_000);
+ throw new ClickHouseQueryAbortedError();
+ });
+ const page =
+ await getObservationsV2PageFromEventsTableForPublicApi(boundedOpts);
+ expect(page.items).toEqual([]);
+ expect(page.cursor?.lastStartTimeTo).toEqual(
+ new Date("2026-10-12T00:00:00Z"),
+ );
+ expect(mockQueryClickhouseWithProgress).toHaveBeenCalledTimes(2);
+ expect(
+ mockQueryClickhouseWithProgress.mock.calls[1][0].clickhouseSettings
+ .max_execution_time,
+ ).toBe(40);
+
+ mockProgressQuery(
+ rowEvent(observation("unfinished", "2026-10-11 00:00:00.000")),
+ );
+ mockProgressQuery();
+ const resumed = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...boundedOpts,
+ cursor: page.cursor,
+ });
+ expect(resumed.items.map((row) => row.id)).toEqual(["unfinished"]);
+ expect(resumed.cursor).toBeUndefined();
+ expect(
+ scanBounds(mockQueryClickhouseWithProgress.mock.calls[2][0]).to,
+ ).toBe("2026-10-12 00:00:00.000");
+ });
+
+ it("includes backfilled and future observations when no lower bound is supplied", async () => {
+ vi.spyOn(performance, "now").mockReturnValue(0);
+ vi.spyOn(Date, "now").mockReturnValue(Date.parse("2026-10-19T00:00:00Z"));
+ mockProgressQuery(
+ rowEvent(observation("future", "2026-10-20 00:00:00.000")),
+ progressEvent(1, 100),
+ );
+ mockProgressQuery(
+ rowEvent(observation("backfilled", "2020-01-01 00:00:00.000")),
+ );
+
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...baseOpts,
+ fields: ["core"],
+ });
+
+ expect(page.items.map((row) => row.id)).toEqual(["future", "backfilled"]);
+ expect(page.cursor).toBeUndefined();
+ const calls = mockQueryClickhouseWithProgress.mock.calls;
+ expect(calls).toHaveLength(2);
+ expect(scanBounds(calls[0][0])).toEqual({
+ from: "2026-10-12 00:00:00.000",
+ });
+ expect(scanBounds(calls[1][0]).from).toBe("2020-01-01 00:00:00.000");
+ });
+
+ it("finishes without querying ClickHouse when the upper bound precedes the default floor", async () => {
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...baseOpts,
+ toStartTime: "2019-12-31T00:00:00Z",
+ });
+ expect(page).toEqual({ items: [], cursor: undefined });
+ expect(mockQueryClickhouseWithProgress).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ {
+ name: "byte estimate",
+ scanned: 100_000,
+ bytes: 1e9,
+ elapsed: 0,
+ days: 196,
+ },
+ {
+ name: "client wall time",
+ scanned: 100_000,
+ bytes: 1e9,
+ elapsed: 10_000,
+ days: 22.4,
+ },
+ {
+ name: "per-query row target",
+ scanned: 2_000_000,
+ bytes: 1e9,
+ elapsed: 1_000,
+ days: 17.5,
+ },
+ {
+ name: "shrinking an expensive window",
+ scanned: 100_000,
+ bytes: 20e9,
+ elapsed: 30_000,
+ days: 2.8,
+ },
+ {
+ name: "empty window without progress",
+ scanned: undefined,
+ bytes: 0,
+ elapsed: 0,
+ days: 28,
+ },
+ {
+ name: "missing statistics with data",
+ scanned: undefined,
+ bytes: 0,
+ elapsed: 1_000,
+ days: 7,
+ hasRow: true,
+ },
+ ])(
+ "sizes the next future window using $name",
+ async ({ scanned, bytes, elapsed, days, hasRow }) => {
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ mockQueryClickhouseWithProgress.mockImplementationOnce(
+ async function* () {
+ clock.mockReturnValue(elapsed);
+ if (scanned !== undefined) yield progressEvent(scanned, bytes);
+ if (hasRow)
+ yield rowEvent(observation("newest", "2099-12-26 00:00:00.000"));
+ },
+ );
+ mockQueryClickhouseWithProgress.mockImplementationOnce(
+ async function* () {
+ clock.mockReturnValue(45_000);
+ yield rowEvent(observation("future", "2099-12-24 00:00:00.000"));
+ },
+ );
+ const page = await getObservationsV2PageFromEventsTableForPublicApi({
+ ...boundedOpts,
+ fromStartTime: "1970-01-01T00:00:00Z",
+ toStartTime: "2100-01-01T00:00:00Z",
+ });
+ expect(page.items.map((row) => row.id)).toEqual(
+ hasRow ? ["newest", "future"] : ["future"],
+ );
+ const calls = mockQueryClickhouseWithProgress.mock.calls;
+ expect(calls).toHaveLength(2);
+ const upper = Date.parse("2099-12-25T00:00:00Z");
+ const lower = new Date(upper - days * 86_400_000);
+ expect(scanBounds(calls[0][0]).from).toBe("2099-12-25 00:00:00.000");
+ expect(scanBounds(calls[1][0]).from).toBe(
+ lower.toISOString().replace("T", " ").replace("Z", ""),
+ );
+ expect(scanBounds(calls[1][0]).to).toBe("2099-12-25 00:00:00.000");
+ expect(page.cursor?.lastStartTimeTo).toEqual(lower);
+ },
+ );
+
+ it("recalibrates after crossing empty history into a byte-heavy window", async () => {
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ mockProgressQuery(progressEvent(0));
+ mockQueryClickhouseWithProgress.mockImplementationOnce(async function* () {
+ clock.mockReturnValue(12_000);
+ yield progressEvent(1_000_000, 40e9);
+ });
+ mockQueryClickhouseWithProgress.mockImplementationOnce(async function* () {
+ clock.mockReturnValue(45_000);
+ yield progressEvent(0);
+ });
+ await getObservationsV2PageFromEventsTableForPublicApi({
+ ...baseOpts,
+ traceId: "trace-1",
+ fromStartTime: "1970-01-01T00:00:00Z",
+ toStartTime: "2026-10-19T00:00:00Z",
+ });
+ const scans = mockQueryClickhouseWithProgress.mock.calls;
+ expect(scans).toHaveLength(3);
+ expect(
+ scans.map(
+ ([opts]) =>
+ (Date.parse(scanBounds(opts).to.replace(" ", "T") + "Z") -
+ Date.parse(scanBounds(opts).from.replace(" ", "T") + "Z")) /
+ 86_400_000,
+ ),
+ ).toEqual([7, 28, 14]);
+ });
+
+ it.each([
+ {
+ name: "typed cancellation",
+ setup: () => mockProgressError(new ClickHouseQueryAbortedError()),
+ assert: (error: unknown) =>
+ expect(error).toMatchObject({ errorType: "TIMEOUT" }),
+ },
+ {
+ name: "exception event",
+ setup: () => mockProgressQuery({ exception: "Syntax error" }),
+ assert: (error: unknown) =>
+ expect(error).toMatchObject({ message: "Syntax error" }),
+ },
+ ])(
+ "fails without inventing a continuation when no window completes: $name",
+ async ({ setup, assert }) => {
+ setup();
+ let caught: unknown;
+ try {
+ await getObservationsV2PageFromEventsTableForPublicApi(boundedOpts);
+ } catch (error) {
+ caught = error;
+ }
+ expect(caught).toBeDefined();
+ assert(caught);
+ expect(mockQueryClickhouseWithProgress).toHaveBeenCalledTimes(1);
+ },
+ );
});
diff --git a/packages/shared/src/server/repositories/events.ts b/packages/shared/src/server/repositories/events.ts
index 6d1968b779..8a0f39b1b5 100644
--- a/packages/shared/src/server/repositories/events.ts
+++ b/packages/shared/src/server/repositories/events.ts
@@ -28,7 +28,7 @@ import {
convertDateToClickhouseDateTime,
PreferredClickhouseService,
} from "../clickhouse/client";
-import { recordDistribution } from "../instrumentation";
+import { instrumentAsync, recordDistribution } from "../instrumentation";
import { logger } from "../logger";
import { AI_GATEWAY_SERVICE_NAME } from "../../features/ai-gateway/constants";
import { compileClickhouseQuery } from "../query-ast/compile";
@@ -89,6 +89,8 @@ import {
ObservationPriceFields,
} from "../queries";
import { createFilterFromFilterState } from "../queries/clickhouse-sql/factory";
+import { DateTimeFilter } from "../queries/clickhouse-sql/clickhouse-filter";
+import { isTimeFilter } from "../queries/clickhouse-sql/filter-utils";
import {
planScoreFilterPushdown,
resolveScoreDataRequirement,
@@ -123,6 +125,12 @@ import {
queryClickhouseStreamRawText,
queryClickhouseExecRaw,
BLOB_EXPORT_PARQUET_CLICKHOUSE_SETTINGS,
+ ClickHouseResourceError,
+ ClickHouseQueryAbortedError,
+ queryClickhouseWithProgress,
+ isProgressRow,
+ isRow,
+ isException,
} from "./clickhouse";
import {
EventsObservationRecordReadType,
@@ -203,6 +211,16 @@ const SESSION_TRACE_FIELDS = [
"user_id",
] as const;
+const OBSERVATIONS_DEFAULT_FROM_MS = Date.parse("2020-01-01T00:00:00Z");
+const OBSERVATIONS_SCAN_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const OBSERVATIONS_SCAN_BUDGET_MS = 45_000;
+const OBSERVATIONS_QUERY_ROW_TARGET = 5_000_000;
+const OBSERVATIONS_QUERY_OVERHEAD_MS = 3_000;
+const OBSERVATIONS_MS_PER_GB = 1_500;
+
+/** xxHash32('CUR00254FG5s') = 0; with id '', the tuple excludes all boundary rows. */
+const OBSERVATIONS_TIME_CURSOR_TRACE_ID = "CUR00254FG5s";
+
/** The `input`/`output` pair an I/O select reads from one relation. */
type IoColumns = { input: string; output: string };
@@ -1656,6 +1674,7 @@ function buildObservationsQueryComponents(
queryWithParams: { query: string; params: Record<string, any> };
}>;
filtersNeedFullTable: boolean;
+ observationsFilter: FilterList;
} {
const { projectId, advancedFilters, ...filterParams } = opts;
@@ -1711,7 +1730,12 @@ function buildObservationsQueryComponents(
)
.where(appliedFilter);
- return { queryBuilder, externalCTEs, filtersNeedFullTable };
+ return {
+ queryBuilder,
+ externalCTEs,
+ filtersNeedFullTable,
+ observationsFilter,
+ };
}
function buildObservationsQueryBase(
@@ -1878,6 +1902,328 @@ export const getObservationsFromEventsTableForPublicApi = async (
return observations;
};
+export const getObservationsV2FromEventsTableForPublicApi = async (
+ opts: PublicApiObservationsQuery,
+ options: BuildObservationsQueryComponentsOptions = {},
+): Promise<Array<EventsObservationPublic>> => {
+ const builder = buildObservationsV2Query(opts, options);
+
+ const records =
+ await getObservationsRowsFromBuilder<EventsObservationQueryResult>(
+ opts.projectId,
+ builder,
+ {},
+ options.clickhouseSettings,
+ );
+
+ return await enrichObservationsWithModelData(
+ records,
+ opts.projectId,
+ false, // V2 API: IO fields are always returned as raw strings
+ opts.fields ?? ["core", "basic"],
+ );
+};
+
+/** Assemble a page from completed windows, including empty continuations. */
+export const getObservationsV2PageFromEventsTableForPublicApi = async (
+ opts: PublicApiObservationsQuery,
+): Promise<{
+ items: EventsObservationPublic[];
+ cursor: PublicApiObservationsQuery["cursor"];
+}> =>
+ instrumentAsync({ name: "observations-v2-scan" }, async (span) => {
+ if (opts.limit === 0) return { items: [], cursor: undefined };
+ const scan = createObservationsScan(opts.projectId);
+ try {
+ const bounds = extractObservationsStartTimeBounds(opts);
+ const from = bounds.from ?? OBSERVATIONS_DEFAULT_FROM_MS;
+ if (bounds.to !== undefined && from > bounds.to) {
+ return { items: [], cursor: undefined };
+ }
+ const page = await scanObservationWindows(opts, from, bounds.to, scan);
+ span.setAttribute("observations.scan.windows", page.windows);
+ return {
+ items: await enrichObservationsWithModelData(
+ page.records.slice(0, opts.limit),
+ opts.projectId,
+ false,
+ opts.fields ?? ["core", "basic"],
+ ),
+ cursor: page.cursor,
+ };
+ } finally {
+ span.setAttributes(scan.getAttributes());
+ }
+ });
+
+function extractObservationsStartTimeBounds(opts: PublicApiObservationsQuery) {
+ const { observationsFilter } = buildObservationsQueryComponents(opts);
+ let from: number | undefined;
+ let to = opts.cursor?.lastStartTimeTo.getTime();
+ observationsFilter.forEach((filter) => {
+ if (!isTimeFilter(filter)) return;
+ const value = filter.value.getTime();
+ if (filter.operator === ">" || filter.operator === ">=") {
+ from = Math.max(from ?? value, value);
+ } else if (filter.operator === "<" || filter.operator === "<=") {
+ to = Math.min(to ?? value, value);
+ }
+ });
+ return { from, to };
+}
+
+async function scanObservationWindows(
+ opts: PublicApiObservationsQuery,
+ from: number,
+ to: number | undefined,
+ scan: ObservationsScan,
+) {
+ let records: EventsObservationQueryResult[] = [];
+ let cursor: PublicApiObservationsQuery["cursor"];
+ let windows = 0;
+ let window: { durationMs: number; estimatedMs?: number } | undefined = {
+ durationMs: OBSERVATIONS_SCAN_WINDOW_MS,
+ };
+ // An omitted upper bound stays open on the first query for future timestamps.
+ let upper = to ?? Math.max(Date.now(), from);
+ while (window !== undefined) {
+ const windowStarted = performance.now();
+ const lower = Math.max(from, upper - window.durationMs);
+ const result = await queryObservationWindow(
+ opts,
+ records.length,
+ {
+ from: new Date(lower),
+ to: to === undefined ? undefined : new Date(upper),
+ inclusiveTo: windows === 0,
+ estimatedMs: window.estimatedMs,
+ },
+ scan,
+ windows,
+ );
+ if (result === undefined) break;
+ windows++;
+ records = records.concat(result.rows);
+ if (records.length > opts.limit) {
+ cursor = observationRowCursor(records[opts.limit - 1]);
+ break;
+ }
+ if (lower === from) {
+ cursor = undefined;
+ break;
+ }
+ cursor = observationTimeCursor(lower);
+ window = planNextObservationsWindow(
+ upper - lower,
+ lower - from,
+ result,
+ performance.now() - windowStarted,
+ scan.remainingMs(),
+ );
+ upper = lower;
+ to = lower;
+ }
+ return { records, cursor, windows };
+}
+
+async function queryObservationWindow(
+ opts: PublicApiObservationsQuery,
+ collected: number,
+ window: {
+ from: Date;
+ to?: Date;
+ inclusiveTo: boolean;
+ estimatedMs?: number;
+ },
+ scan: ObservationsScan,
+ completedWindows: number,
+) {
+ return instrumentAsync(
+ { name: "observations-v2-scan-window" },
+ async (span) => {
+ const started = performance.now();
+ if (window.estimatedMs !== undefined) {
+ span.setAttribute("observations.scan.estimated_ms", window.estimatedMs);
+ }
+ try {
+ const result = await scan.query<EventsObservationQueryResult>(
+ buildObservationsV2Query(
+ { ...opts, limit: opts.limit - collected },
+ {},
+ window,
+ ),
+ );
+ span.setAttribute("observations.scan.completed", true);
+ span.setAttribute("observations.scan.read_bytes", result.readBytes);
+ if (result.readRows !== undefined)
+ span.setAttribute("observations.scan.read_rows", result.readRows);
+ return result;
+ } catch (error) {
+ // Only completed windows may advance the cursor on timeout.
+ if (
+ completedWindows > 0 &&
+ error instanceof ClickHouseResourceError &&
+ error.errorType === "TIMEOUT"
+ ) {
+ return undefined;
+ }
+ throw error;
+ } finally {
+ span.setAttribute(
+ "observations.scan.elapsed_ms",
+ performance.now() - started,
+ );
+ }
+ },
+ );
+}
+
+function observationRowCursor(last: EventsObservationQueryResult) {
+ return {
+ lastStartTimeTo: parseClickhouseUTCDateTimeFormat(last.start_time),
+ lastTraceId: last.trace_id ?? "",
+ lastId: last.id,
+ };
+}
+
+function observationTimeCursor(lower: number) {
+ return {
+ lastStartTimeTo: new Date(lower),
+ lastTraceId: OBSERVATIONS_TIME_CURSOR_TRACE_ID,
+ lastId: "",
+ };
+}
+
+function planNextObservationsWindow(
+ windowMs: number,
+ remainingRangeMs: number,
+ last: { readRows: number | undefined; readBytes: number },
+ elapsedMs: number,
+ remainingMs: number,
+) {
+ if (remainingMs <= 0) return undefined;
+
+ // Client wall time includes retries and stream consumption; GB is decimal.
+ const costMs = Math.max(
+ elapsedMs,
+ (last.readBytes / 1e9) * OBSERVATIONS_MS_PER_GB,
+ );
+ const availableMs = remainingMs - OBSERVATIONS_QUERY_OVERHEAD_MS;
+ // Near the deadline, do not shrink the interval just to reserve overhead.
+ let timeMultiplier = 1;
+ if (availableMs > 0) {
+ timeMultiplier = costMs > 0 ? availableMs / costMs : Infinity;
+ }
+ const rowMultiplier =
+ last.readRows !== undefined && last.readRows > 0
+ ? OBSERVATIONS_QUERY_ROW_TARGET / last.readRows
+ : Infinity;
+ // Missing statistics or empty scans cannot justify unrestricted growth.
+ let growthLimit = Infinity;
+ if (last.readRows === undefined) growthLimit = 1;
+ else if (last.readRows === 0 && last.readBytes === 0) growthLimit = 4;
+
+ const durationMs = Math.min(
+ remainingRangeMs,
+ Math.max(
+ 1,
+ Math.floor(
+ windowMs * Math.min(timeMultiplier, rowMultiplier, growthLimit),
+ ),
+ ),
+ );
+ return {
+ durationMs,
+ estimatedMs:
+ OBSERVATIONS_QUERY_OVERHEAD_MS + (durationMs / windowMs) * costMs,
+ };
+}
+
+/** Own the deadline and cumulative work counters for all queries in one page. */
+function createObservationsScan(projectId: string) {
+ const started = performance.now();
+ const abortSignal = AbortSignal.timeout(OBSERVATIONS_SCAN_BUDGET_MS);
+ let readRows = 0;
+ let readBytes = 0;
+ const remainingMs = () =>
+ OBSERVATIONS_SCAN_BUDGET_MS - (performance.now() - started);
+ const query = async <T>(builder: QueryWithParams) => {
+ let queryRows: number | undefined;
+ let queryBytes = 0;
+ try {
+ const rows = await runObservationsScanQuery<T>(
+ builder,
+ projectId,
+ abortSignal,
+ remainingMs(),
+ (scanned, bytes) => {
+ // Streaming progress is cumulative, including work from retried attempts.
+ readRows += scanned - (queryRows ?? 0);
+ readBytes += bytes - queryBytes;
+ queryRows = scanned;
+ queryBytes = bytes;
+ },
+ );
+ // Completed empty streams omit zero progress; nonzero reads flush on completion.
+ return {
+ rows,
+ readRows: queryRows ?? (rows.length === 0 ? 0 : undefined),
+ readBytes: queryBytes,
+ };
+ } catch (error) {
+ if (error instanceof ClickHouseQueryAbortedError) {
+ throw new ClickHouseResourceError("TIMEOUT", error);
+ }
+ throw error;
+ }
+ };
+ return {
+ query,
+ remainingMs,
+ getAttributes: () => ({
+ "observations.scan.read_rows": readRows,
+ "observations.scan.read_bytes": readBytes,
+ "observations.scan.elapsed_ms": performance.now() - started,
+ }),
+ };
+}
+
+async function runObservationsScanQuery<T>(
+ builder: QueryWithParams,
+ projectId: string,
+ abortSignal: AbortSignal,
+ remainingMs: number,
+ onProgress: (readRows: number, readBytes: number) => void,
+): Promise<T[]> {
+ const rows: T[] = [];
+ for await (const item of queryClickhouseWithProgress<T>({
+ ...builder.buildWithParams(),
+ tags: { projectId },
+ preferredClickhouseService: "EventsReadOnly",
+ abortSignal,
+ clickhouseConfigs: { request_timeout: OBSERVATIONS_SCAN_BUDGET_MS },
+ clickhouseSettings: {
+ read_in_order_use_buffering: 0,
+ max_execution_time: Math.max(0.001, remainingMs / 1000),
+ timeout_overflow_mode: "throw",
+ timeout_before_checking_execution_speed: 0,
+ cancel_http_readonly_queries_on_client_close: 1,
+ },
+ })) {
+ if (isRow<T>(item)) rows.push(item.row);
+ if (isProgressRow(item))
+ onProgress(
+ Number(item.progress.read_rows),
+ Number(item.progress.read_bytes),
+ );
+ if (isException(item))
+ throw ClickHouseResourceError.wrapIfResourceError(
+ new Error(item.exception),
+ );
+ }
+ return rows;
+}
+
/**
* V2 API: Get observations list from events table for public API
* Returns partial observations based on requested field groups
@@ -1888,10 +2234,11 @@ export const getObservationsFromEventsTableForPublicApi = async (
* - io CTE: fetches full IO/metadata from events_full for matched rows only
* This avoids expensive full-table scans on events_full.
*/
-export const getObservationsV2FromEventsTableForPublicApi = async (
+function buildObservationsV2Query(
opts: PublicApiObservationsQuery,
options: BuildObservationsQueryComponentsOptions = {},
-): Promise<Array<EventsObservationPublic>> => {
+ window?: { from: Date; to?: Date; inclusiveTo: boolean },
+): QueryWithParams {
const { projectId, expandMetadataKeys } = opts;
// Determine which field groups to include
@@ -1915,6 +2262,26 @@ export const getObservationsV2FromEventsTableForPublicApi = async (
options,
);
+ // Apply scan bounds after merging user filters so structured filters cannot
+ // override them. The same bounded base feeds the full-payload lookup.
+ if (window) {
+ for (const [value, operator] of [
+ [window.from, ">="],
+ [window.to, window.inclusiveTo ? "<=" : "<"],
+ ] as const) {
+ if (!value) continue;
+ baseBuilder.where(
+ new DateTimeFilter({
+ clickhouseTable: "events_core",
+ field: "start_time",
+ tablePrefix: "e",
+ operator,
+ value,
+ }).apply(),
+ );
+ }
+ }
+
// The io lane only pays off when base reads the cheap truncated table
// (events_core) and the split defers the heavy input/output/metadata columns
// to a page-size lookup on events_full. When a filter touches input/output,
@@ -1975,21 +2342,10 @@ export const getObservationsV2FromEventsTableForPublicApi = async (
break;
}
- const records =
- await getObservationsRowsFromBuilder<EventsObservationQueryResult>(
- projectId,
- builder,
- {},
- options.clickhouseSettings,
- );
+ return builder;
+}
- return await enrichObservationsWithModelData(
- records,
- projectId,
- false, // V2 API: IO fields are always returned as raw strings
- requestedFields,
- );
-};
+type ObservationsScan = ReturnType<typeof createObservationsScan>;
/**
* Get count of observations from events table for public API.
diff --git a/web/AGENTS.md b/web/AGENTS.md
index e9be4c9f1f..3284aa09ab 100644
--- a/web/AGENTS.md
+++ b/web/AGENTS.md
@@ -218,6 +218,9 @@ Sentry instrumentation skill first and decide whether it should capture at all
`src/features/public-api/server/withMiddlewares.ts`, define strict request and
response types in `src/features/public-api/types/*`, add server tests, and
update Fern sources when the contract changes.
+- Observations v2 pages can be short or empty while `meta.cursor` exists because
+ the endpoint bounds scan work. End pagination only when the cursor is absent;
+ never derive completion from the number of returned rows.
- Public eval endpoints should keep the split between reusable `evaluators`
and ingestion-scoped `evaluation-rules`; do not leak `EvalTemplate` or
`JobConfiguration` naming into the public contract.
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index fd3f0aa27d..e24cb9e53b 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -3511,7 +3511,16 @@ paths:
The cursor is returned in the response metadata and should be passed in
subsequent requests
- to retrieve the next page of results.
+ to retrieve the next page of results. The `limit` parameter is a
+ maximum: a page may contain
+
+ fewer items than the requested limit, including zero items, while
+ `meta.cursor` is present.
+
+ Continue requesting pages until `meta.cursor` is absent.
+
+ Requests without a lower start-time bound may search only from January
+ 1, 2020.
## Field Selection
@@ -3585,7 +3594,10 @@ paths:
nullable: true
- name: limit
in: query
- description: Number of items to return per page. Maximum 1000, default 50.
+ description: >-
+ Maximum number of items to return per page. A page may contain fewer
+ items, including zero items, while meta.cursor is present. Maximum
+ 1000, default 50.
required: false
schema:
type: integer
@@ -12532,7 +12544,13 @@ components:
The `data` array contains observation objects with only the requested
field groups included.
- Use the `cursor` in `meta` to retrieve the next page of results.
+ Use the `cursor` in `meta` to retrieve the next page of results. The
+ array may contain fewer
+
+ than the requested `limit` items, or be empty, while a cursor is
+ present. Continue until the
+
+ cursor is absent.
properties:
data:
type: array
@@ -12550,7 +12568,13 @@ components:
title: ObservationsV2Meta
type: object
description: Metadata for cursor-based pagination.
- properties: {}
+ properties:
+ comment:
+ type: string
+ nullable: true
+ description: >-
+ Present when an empty page has a cursor; continue requesting pages
+ until the cursor is absent.
allOf:
- $ref: '#/components/schemas/utilsCursorMetaResponse'
OtelResourceSpan:
diff --git a/web/src/__tests__/server/observations-api-v2.servertest.ts b/web/src/__tests__/server/observations-api-v2.servertest.ts
index 97f55eacc1..fa1744d780 100644
--- a/web/src/__tests__/server/observations-api-v2.servertest.ts
+++ b/web/src/__tests__/server/observations-api-v2.servertest.ts
@@ -2,13 +2,17 @@ import {
createEvent as createEventBase,
createEventsCh,
createOrgProjectAndApiKey,
+ EventsQueryBuilder,
queryClickhouse,
} from "@langfuse/shared/src/server";
import {
makeAPICall,
makeZodVerifiedAPICall,
} from "@/src/__tests__/test-utils";
-import { GetObservationsV2Response } from "@/src/features/public-api/types/observations";
+import {
+ GetObservationsV2Response,
+ encodeCursor,
+} from "@/src/features/public-api/types/observations";
import { randomUUID } from "crypto";
import { env } from "@/src/env.mjs";
import waitForExpect from "wait-for-expect";
@@ -1745,6 +1749,112 @@ describe("/api/public/v2/observations API Endpoint", () => {
});
maybe("Cursor-based pagination", () => {
+ it("paginates across empty scan windows without repeating boundary rows", async () => {
+ const traceId = randomUUID();
+ const ids = [randomUUID(), randomUUID(), randomUUID()];
+ const upper = new Date();
+ upper.setUTCHours(0, 0, 0, 0);
+ const daysBefore = (days: number) =>
+ new Date(upper.getTime() - days * 24 * 60 * 60 * 1000);
+ const timestamps = [7, 15, 17].map(daysBefore);
+ await createEventsCh(
+ ids.map((id, index) =>
+ createEvent({
+ id,
+ span_id: id,
+ project_id: projectId,
+ trace_id: traceId,
+ type: "SPAN",
+ start_time: timestamps[index].getTime() * 1000,
+ }),
+ ),
+ );
+
+ const url = `/api/public/v2/observations?traceId=${traceId}&fields=core&limit=2&fromStartTime=${daysBefore(18).toISOString()}&toStartTime=${upper.toISOString()}`;
+ const first = await getObservations(url);
+ expect(first.status).toBe(200);
+ expect(first.body.data.map((row) => row.id)).toEqual(ids.slice(0, 2));
+ expect(first.body.meta.cursor).toBeDefined();
+ const second = await getObservations(
+ `${url}&cursor=${encodeURIComponent(first.body.meta.cursor!)}`,
+ );
+ expect(second.body.data.map((row) => row.id)).toEqual(ids.slice(2));
+ expect(second.body.meta.cursor).toBeUndefined();
+
+ const boundaryCursor = encodeCursor({
+ lastStartTimeTo: timestamps[0],
+ lastTraceId: "CUR00254FG5s",
+ lastId: "",
+ });
+ const afterEmptyWindow = await getObservations(
+ `${url}&cursor=${encodeURIComponent(boundaryCursor)}`,
+ );
+ expect(afterEmptyWindow.body.data.map((row) => row.id)).toEqual(
+ ids.slice(1),
+ );
+ expect(afterEmptyWindow.body.meta.cursor).toBeUndefined();
+
+ const [{ hash }] = await queryClickhouse<{ hash: number }>({
+ query: "SELECT xxHash32({traceId: String}) AS hash",
+ params: { traceId: "CUR00254FG5s" },
+ });
+ expect(hash).toBe(0);
+ });
+
+ it("scans sparse future windows without clamping customer timestamps", async () => {
+ const traceId = randomUUID();
+ const olderId = randomUUID();
+ const futureId = randomUUID();
+ const from = new Date("2026-10-01T00:00:00.000Z");
+ const to = new Date("2100-02-01T00:00:00.000Z");
+ const older = new Date("2026-10-15T00:00:00.000Z");
+ const future = new Date("2099-12-15T00:00:00.000Z");
+
+ await createEventsCh([
+ createEvent({
+ id: olderId,
+ span_id: olderId,
+ project_id: projectId,
+ trace_id: traceId,
+ type: "SPAN",
+ start_time: older.getTime() * 1000,
+ }),
+ createEvent({
+ id: futureId,
+ span_id: futureId,
+ project_id: projectId,
+ trace_id: traceId,
+ type: "SPAN",
+ start_time: future.getTime() * 1000,
+ }),
+ ]);
+
+ const countQuery = new EventsQueryBuilder({ projectId })
+ .selectRaw("count() AS count")
+ .whereRaw("e.trace_id = {traceId: String}", { traceId })
+ .buildWithParams();
+
+ await waitForExpect(
+ async () => {
+ const result = await queryClickhouse<{ count: string }>(countQuery);
+ expect(Number(result[0]?.count)).toBeGreaterThanOrEqual(2);
+ },
+ 5000,
+ 10,
+ );
+
+ const response = await getObservations(
+ `/api/public/v2/observations?traceId=${traceId}&fields=core&limit=10&fromStartTime=${from.toISOString()}&toStartTime=${to.toISOString()}`,
+ );
+
+ expect(response.status).toBe(200);
+ expect(response.body.data.map((row) => row.id)).toEqual([
+ futureId,
+ olderId,
+ ]);
+ expect(response.body.meta.cursor).toBeUndefined();
+ });
+
it("should apply LIMIT to query even on first request (no cursor)", async () => {
// This test verifies the bug fix - the v2 API should respect limit
// even on the first request without a cursor
diff --git a/web/src/env.mjs b/web/src/env.mjs
index ac543cd0cd..0a1b0cf39b 100644
--- a/web/src/env.mjs
+++ b/web/src/env.mjs
@@ -767,6 +767,11 @@ export const env = createEnv({
.enum(["true", "false"])
.default("false"),
+ // Use adaptive scan windows when filling observations v2 pages.
+ LANGFUSE_OBSERVATIONS_V2_ADAPTIVE_SCAN_ENABLED: z
+ .enum(["true", "false"])
+ .default("true"),
+
// Temporary kill-switch for the observations v2 subquery-IN rewrite.
LANGFUSE_OBSERVATIONS_V2_SUBQUERY_REWRITE: z
.enum(["true", "false"])
@@ -1354,6 +1359,8 @@ export const env = createEnv({
// Legacy tracing search controls
LANGFUSE_DISABLE_LEGACY_TRACING_IO_SEARCH:
process.env.LANGFUSE_DISABLE_LEGACY_TRACING_IO_SEARCH,
+ LANGFUSE_OBSERVATIONS_V2_ADAPTIVE_SCAN_ENABLED:
+ process.env.LANGFUSE_OBSERVATIONS_V2_ADAPTIVE_SCAN_ENABLED,
LANGFUSE_OBSERVATIONS_V2_SUBQUERY_REWRITE:
process.env.LANGFUSE_OBSERVATIONS_V2_SUBQUERY_REWRITE,
LANGFUSE_OBSERVATIONS_V2_SHADOW_QUERY:
diff --git a/web/src/features/public-api/types/observations.ts b/web/src/features/public-api/types/observations.ts
index 2e1ea6f2a6..ce16a3072c 100644
--- a/web/src/features/public-api/types/observations.ts
+++ b/web/src/features/public-api/types/observations.ts
@@ -434,6 +434,7 @@ export const GetObservationsV2Response = z
data: z.array(APIObservationV2),
meta: z.object({
cursor: EncodedObservationsCursorV2String.optional(),
+ comment: z.string().optional(),
}),
})
.strict();
diff --git a/web/src/pages/api/public/v2/observations/index.ts b/web/src/pages/api/public/v2/observations/index.ts
index 6e934e8430..abea923dc4 100644
--- a/web/src/pages/api/public/v2/observations/index.ts
+++ b/web/src/pages/api/public/v2/observations/index.ts
@@ -1,4 +1,7 @@
-import { getObservationsV2FromEventsTableForPublicApi } from "@langfuse/shared/src/server";
+import {
+ getObservationsV2FromEventsTableForPublicApi,
+ getObservationsV2PageFromEventsTableForPublicApi,
+} from "@langfuse/shared/src/server";
import { LangfuseNotFoundError } from "@langfuse/shared";
import { withMiddlewares } from "@/src/features/public-api/server/withMiddlewares";
@@ -76,18 +79,12 @@ export default withMiddlewares({
expandMetadataKeys,
};
- // Fetch observations from events table with field groups applied at query time
- const items =
- await getObservationsV2FromEventsTableForPublicApi(filterProps);
-
- // Determine if there are more results (we fetched limit+1)
- const hasMore = items.length > query.limit;
- const dataToReturn = hasMore ? items.slice(0, query.limit) : items;
+ const { items, cursor } = await getObservationsPage(filterProps);
// Normalize for the wire format:
// - empty parent_observation_id -> null (v1 parity)
// - Decimal price fields -> string (preserves original v2 wire format; v1 emits numbers via .toNumber())
- const transformedItems = dataToReturn.map((item) => ({
+ const transformedItems = items.map((item) => ({
...item,
parentObservationId:
item.parentObservationId === "" ? null : item.parentObservationId,
@@ -97,23 +94,39 @@ export default withMiddlewares({
totalPrice: item.totalPrice?.toString() ?? null,
}));
- // Generate cursor if there are more results
- const lastItemIdx = dataToReturn.length - 1;
- const meta =
- hasMore && dataToReturn.length > 0
+ return {
+ data: transformedItems,
+ meta: cursor
? {
- cursor: encodeCursor({
- lastStartTimeTo: dataToReturn[lastItemIdx].startTime,
- lastTraceId: dataToReturn[lastItemIdx].traceId ?? "",
- lastId: dataToReturn[lastItemIdx].id,
+ cursor: encodeCursor(cursor),
+ ...(transformedItems.length === 0 && {
+ comment:
+ "This empty page does not indicate completion. Continue requesting pages using meta.cursor.",
}),
}
- : {};
-
- return {
- data: transformedItems,
- meta,
+ : {},
};
},
}),
});
+
+async function getObservationsPage(
+ opts: Parameters<typeof getObservationsV2PageFromEventsTableForPublicApi>[0],
+): ReturnType<typeof getObservationsV2PageFromEventsTableForPublicApi> {
+ if (env.LANGFUSE_OBSERVATIONS_V2_ADAPTIVE_SCAN_ENABLED === "true") {
+ return getObservationsV2PageFromEventsTableForPublicApi(opts);
+ }
+
+ const records = await getObservationsV2FromEventsTableForPublicApi(opts);
+ const items = records.slice(0, opts.limit);
+ const last = items.at(-1);
+ const cursor =
+ records.length > opts.limit && last
+ ? {
+ lastStartTimeTo: last.startTime,
+ lastTraceId: last.traceId ?? "",
+ lastId: last.id,
+ }
+ : undefined;
+ return { items, cursor };
+}