🪢 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
fix(api): fill observations pages with adaptive scan windows (#19043)
Valery Meleshkin41c8918b16c5
diff --git a/.env.dev.example b/.env.dev.exampleindex 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.exampleindex 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.000Zdiff --git a/fern/apis/server/definition/observations.yml b/fern/apis/server/definition/observations.ymlindex fcd5901970..78272e9d4e 100644--- a/fern/apis/server/definition/observations.yml+++ b/fern/apis/server/definition/observations.yml@@ -15,7 +15,10 @@ service:## Cursor-based PaginationThis 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 SelectionUse 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 andresponse types in `src/features/public-api/types/*`, add server tests, andupdate 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.ymlindex 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 insubsequent 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: limitin: 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: falseschema:type: integer@@ -12532,7 +12544,13 @@ components:The `data` array contains observation objects with only the requestedfield 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: ObservationsV2Metatype: objectdescription: 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.tsindex 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 cursordiff --git a/web/src/env.mjs b/web/src/env.mjsindex 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 controlsLANGFUSE_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.tsindex 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 = zdata: 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.tsindex 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 };+}