🪢 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(observations): make start-time lookup inputs a best-effort performance hint (#17202)
Niklas Semmlerc35eeaf23f5f
diff --git a/fern/apis/server/definition/comments.yml b/fern/apis/server/definition/comments.ymlindex 6b461a5dee..72e105290e 100644--- a/fern/apis/server/definition/comments.yml+++ b/fern/apis/server/definition/comments.yml@@ -64,7 +64,7 @@ types:docs: The id of the user who created the comment. Must be a member of the organization that owns the project, otherwise an error will be thrown.objectStartTime:type: optional<datetime>- docs: The start time of the referenced object (for observations, the observation's start time). When provided, Langfuse validates the reference more efficiently by narrowing the lookup to that time range.+ docs: The start time of the referenced object (for observations, the observation's start time). Optional performance hint - when provided, Langfuse narrows the lookup to validate the reference faster. It only affects speed - an incorrect or omitted value never changes the result.CreateCommentResponse:properties:id:diff --git a/fern/apis/server/definition/legacy/observations-v1.yml b/fern/apis/server/definition/legacy/observations-v1.ymlindex b024d16bf0..646556ce61 100644--- a/fern/apis/server/definition/legacy/observations-v1.yml+++ b/fern/apis/server/definition/legacy/observations-v1.yml@@ -22,7 +22,7 @@ service:query-parameters:startTime:type: optional<datetime>- docs: The start time of the observation (ISO 8601 with offset, e.g. 2024-01-01T00:00:00Z). When provided, the lookup is restricted to the observation's start day, which makes the request substantially faster. Omit it to look up the observation without a time bound.+ docs: The start time of the observation (ISO 8601 with offset, e.g. 2024-01-01T00:00:00Z). Optional performance hint - when provided, Langfuse narrows the lookup to make the request substantially faster. It only affects speed - an incorrect or omitted value never changes the result.response: commons.ObservationsViewSinglegetMany:availability:diff --git a/packages/shared/src/features/comments/types.ts b/packages/shared/src/features/comments/types.tsindex 1fa111156e..e0f22d0a6b 100644--- a/packages/shared/src/features/comments/types.ts+++ b/packages/shared/src/features/comments/types.ts@@ -27,9 +27,10 @@ export const CreateCommentData = zcontent: z.string().trim().min(1).max(MAX_COMMENT_LENGTH),objectId: z.string(),objectType: z.enum(COMMENT_OBJECT_TYPES),- // Optional start time of the referenced object (e.g. an observation's- // start_time). When present it bounds the reference-existence lookup to a- // narrow time range so ClickHouse can prune partitions/parts.+ // Optional performance hint: the referenced object's start time (e.g. an+ // observation's start_time). When present it bounds the reference-existence+ // lookup to its minute so ClickHouse can prune parts/partitions; on a miss+ // the lookup retries unbounded, so the hint never changes the result.objectStartTime: z.coerce.date().nullish(),// Optional inline positioning (parallel arrays)dataField: z.enum(COMMENT_DATA_FIELDS).nullish(),diff --git a/packages/shared/src/server/repositories/events.ts b/packages/shared/src/server/repositories/events.tsindex fda517cd3e..c640db7469 100644--- a/packages/shared/src/server/repositories/events.ts+++ b/packages/shared/src/server/repositories/events.ts@@ -1017,10 +1017,17 @@ async function getObservationByIdFromEventsTableInternal({),).whereRaw("span_id = {id: String}", { id })+ // Matched at minute resolution: minute is the finest the events_full primary+ // key (project_id, toStartOfMinute(start_time), ...) can prune on, and+ // flooring absorbs sub-minute precision differences in the caller-supplied+ // start time..when(Boolean(startTime), (b) =>- b.whereRaw("toDate(start_time) = toDate({startTime: DateTime64(3)})", {- startTime: convertDateToClickhouseDateTime(startTime!),- }),+ b.whereRaw(+ "toStartOfMinute(start_time) = toStartOfMinute({startTime: DateTime64(3)})",+ {+ startTime: convertDateToClickhouseDateTime(startTime!),+ },+ ),)// Lower-bound start_time on an anchor (e.g. the parent trace's timestamp) so// the lookup can prune events_full parts/partitions. Subtract the skewdiff --git a/packages/shared/src/server/repositories/observations.ts b/packages/shared/src/server/repositories/observations.tsindex 0be5d6076f..1f6e92b570 100644--- a/packages/shared/src/server/repositories/observations.ts+++ b/packages/shared/src/server/repositories/observations.ts@@ -500,7 +500,8 @@ const getObservationByIdInternal = async ({FROM observationsWHERE id = {id: String}AND project_id = {projectId: String}- ${startTime ? `AND toDate(start_time) = toDate({startTime: DateTime64(3)})` : ""}+ ${/* Matched at minute resolution: minute is the finest the primary key can prune on, and flooring absorbs sub-minute precision differences in the caller-supplied start time. */ ""}+ ${startTime ? `AND toStartOfMinute(start_time) = toStartOfMinute({startTime: DateTime64(3)})` : ""}${startTimeLowerBound ? `AND start_time >= {startTimeLowerBound: DateTime64(3)} - ${OBSERVATIONS_TO_TRACE_INTERVAL}` : ""}${type ? `AND type = {type: String}` : ""}${traceId ? `AND trace_id = {traceId: String}` : ""}diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex 6e928007a1..d210ac9ee3 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -3017,9 +3017,10 @@ paths:in: querydescription: >-The start time of the observation (ISO 8601 with offset, e.g.- 2024-01-01T00:00:00Z). When provided, the lookup is restricted to- the observation's start day, which makes the request substantially- faster. Omit it to look up the observation without a time bound.+ 2024-01-01T00:00:00Z). Optional performance hint - when provided,+ Langfuse narrows the lookup to make the request substantially+ faster. It only affects speed - an incorrect or omitted value never+ changes the result.required: falseschema:type: string@@ -9210,9 +9211,10 @@ components:nullable: truedescription: >-The start time of the referenced object (for observations, the- observation's start time). When provided, Langfuse validates the- reference more efficiently by narrowing the lookup to that time- range.+ observation's start time). Optional performance hint - when+ provided, Langfuse narrows the lookup to validate the reference+ faster. It only affects speed - an incorrect or omitted value never+ changes the result.required:- projectId- objectTypediff --git a/web/src/__tests__/server/comments-api.servertest.ts b/web/src/__tests__/server/comments-api.servertest.tsindex 01c795e1e4..774b7f695b 100644--- a/web/src/__tests__/server/comments-api.servertest.ts+++ b/web/src/__tests__/server/comments-api.servertest.ts@@ -100,8 +100,11 @@ describe("Create and get comments", () => {});});- it("should create an observation comment when objectStartTime bounds the lookup", async () => {+ it("should create an observation comment when objectStartTime is in the observation's minute", async () => {const startTime = new Date("2024-05-15T12:00:00.000Z");+ // Same minute, different second: the lookup floors to the minute, so this+ // still resolves the observation.+ const sameMinuteStartTime = new Date("2024-05-15T12:00:45.000Z");const observationId = randomUUID();// Seed both tables so the lookup resolves regardless of the v4 write-mode// routing the test environment happens to use.@@ -134,7 +137,7 @@ describe("Create and get comments", () => {objectId: observationId,objectType: "OBSERVATION",projectId: seedProjectId,- objectStartTime: startTime.toISOString(),+ objectStartTime: sameMinuteStartTime.toISOString(),authorUserId: orgMemberUserId,},);@@ -159,10 +162,12 @@ describe("Create and get comments", () => {it("should still create an observation comment when objectStartTime is a wrong/stale hint", async () => {const actualStartTime = new Date("2024-05-15T12:00:00.000Z");- // A day the observation does NOT live on: the bounded lookup misses and- // must fall back to an unbounded lookup instead of surfacing a false 404.- const wrongStartTime = new Date("2024-05-20T12:00:00.000Z");+ // A different minute than the observation: the bounded lookup misses, but the+ // hint falls back to an unbounded lookup, so the comment is still created.+ const wrongStartTime = new Date("2024-05-15T12:02:00.000Z");const observationId = randomUUID();+ // Seed both tables so the lookup resolves regardless of the v4 write-mode+ // routing the test environment happens to use.await Promise.all([createEventsCh([createEvent({diff --git a/web/src/__tests__/server/observation-api.servertest.ts b/web/src/__tests__/server/observation-api.servertest.tsindex edc2eeb45c..a195ef6e92 100644--- a/web/src/__tests__/server/observation-api.servertest.ts+++ b/web/src/__tests__/server/observation-api.servertest.ts@@ -170,7 +170,7 @@ describe("/api/public/observations API Endpoint", () => {});});- it("should GET an observation when startTime matches its UTC day", async () => {+ it("should GET an observation when the startTime hint matches", async () => {const observationId = uuidv4();const traceId = uuidv4();const startTime = new Date("2024-03-15T08:30:00.000Z").getTime();@@ -190,7 +190,7 @@ describe("/api/public/observations API Endpoint", () => {const getEventRes = await makeZodVerifiedAPICall(GetObservationV1Response,"GET",- `/api/public/observations/${observationId}?startTime=2024-03-15T23:59:59.000Z&useEventsTable=${useEventsTable}`,+ `/api/public/observations/${observationId}?startTime=2024-03-15T08:30:00.000Z&useEventsTable=${useEventsTable}`,);expect(getEventRes.body).toMatchObject({@@ -200,7 +200,7 @@ describe("/api/public/observations API Endpoint", () => {});});- it("should 404 when startTime is on a different UTC day", async () => {+ it("should still GET an observation when the startTime hint is wrong", async () => {const observationId = uuidv4();const traceId = uuidv4();const startTime = new Date("2024-03-15T08:30:00.000Z").getTime();@@ -217,12 +217,20 @@ describe("/api/public/observations API Endpoint", () => {await insertObservations(useEventsTable, [observation]);- const res = await makeAPICall(+ // A different day than the observation: the bounded lookup misses, but+ // the hint falls back to an unbounded lookup, so the observation is+ // still returned.+ const getEventRes = await makeZodVerifiedAPICall(+ GetObservationV1Response,"GET",`/api/public/observations/${observationId}?startTime=2024-03-16T00:00:00.000Z&useEventsTable=${useEventsTable}`,);- expect(res.status).toBe(404);+ expect(getEventRes.body).toMatchObject({+ id: observationId,+ traceId,+ type: "GENERATION",+ });});it("should 400 when startTime lacks a timezone offset", async () => {diff --git a/web/src/features/comments/validateCommentReferenceObject.ts b/web/src/features/comments/validateCommentReferenceObject.tsindex 26000d57a2..aa7cd82524 100644--- a/web/src/features/comments/validateCommentReferenceObject.ts+++ b/web/src/features/comments/validateCommentReferenceObject.ts@@ -27,16 +27,13 @@ export const validateCommentReferenceObject = async ({commentTarget = await getObservationById({id: objectId,projectId,- // Bounds the events_full lookup to the observation's day so ClickHouse- // can prune partitions/parts; absent, the lookup falls back to a scan.+ // objectStartTime is a performance hint: it bounds the lookup to its+ // minute so ClickHouse can prune parts/partitions. On a miss we retry+ // unbounded below, so a wrong or stale hint only ever costs speed,+ // never correctness.startTime: objectStartTime ?? undefined,});} catch (e) {- // objectStartTime is a client-supplied hint on the public API; a wrong- // or stale value bounds the lookup to the wrong day, so getObservationById- // throws NotFound for an observation that does exist. Retry once- // unbounded so the hint can only ever speed up a hit, never turn into a- // false "not found". A genuine miss re-throws from the unbounded lookup.if (!(e instanceof LangfuseNotFoundError) || !objectStartTime) throw e;// eslint-disable-next-line @typescript-eslint/no-deprecatedcommentTarget = await getObservationById({ id: objectId, projectId });diff --git a/web/src/pages/api/public/observations/[observationId].ts b/web/src/pages/api/public/observations/[observationId].tsindex 3f3213004b..2a5422c22b 100644--- a/web/src/pages/api/public/observations/[observationId].ts+++ b/web/src/pages/api/public/observations/[observationId].ts@@ -35,21 +35,33 @@ export default withMiddlewares(? new Date(query.startTime): undefined;- const clickhouseObservation = query.useEventsTable- ? await getObservationByIdFromEventsTable({- id: query.observationId,- projectId: auth.scope.projectId,- fetchWithInputOutput: true,- startTime,- })- : // eslint-disable-next-line @typescript-eslint/no-deprecated- await getObservationById({- id: query.observationId,- projectId: auth.scope.projectId,- fetchWithInputOutput: true,- startTime,- preferredClickhouseService: "ReadOnly",- });+ const lookupObservation = (withStartTime: boolean) =>+ query.useEventsTable+ ? getObservationByIdFromEventsTable({+ id: query.observationId,+ projectId: auth.scope.projectId,+ fetchWithInputOutput: true,+ startTime: withStartTime ? startTime : undefined,+ })+ : // eslint-disable-next-line @typescript-eslint/no-deprecated+ getObservationById({+ id: query.observationId,+ projectId: auth.scope.projectId,+ fetchWithInputOutput: true,+ startTime: withStartTime ? startTime : undefined,+ preferredClickhouseService: "ReadOnly",+ });++ // startTime is a performance hint: it bounds the lookup to its minute so+ // ClickHouse can prune parts/partitions. On a miss we retry unbounded,+ // so a wrong or stale hint only ever costs speed, never correctness.+ let clickhouseObservation;+ try {+ clickhouseObservation = await lookupObservation(true);+ } catch (e) {+ if (!(e instanceof LangfuseNotFoundError) || !startTime) throw e;+ clickhouseObservation = await lookupObservation(false);+ }if (!clickhouseObservation) {throw new LangfuseNotFoundError(