Skip to content

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

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.yml
index 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.yml
index 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.ObservationsViewSingle
getMany:
availability:
diff --git a/packages/shared/src/features/comments/types.ts b/packages/shared/src/features/comments/types.ts
index 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 = z
content: 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.ts
index 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 skew
diff --git a/packages/shared/src/server/repositories/observations.ts b/packages/shared/src/server/repositories/observations.ts
index 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 observations
WHERE 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.yml
index 6e928007a1..d210ac9ee3 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -3017,9 +3017,10 @@ paths:
in: query
description: >-
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: false
schema:
type: string
@@ -9210,9 +9211,10 @@ components:
nullable: true
description: >-
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
- objectType
diff --git a/web/src/__tests__/server/comments-api.servertest.ts b/web/src/__tests__/server/comments-api.servertest.ts
index 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.ts
index 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.ts
index 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-deprecated
commentTarget = await getObservationById({ id: objectId, projectId });
diff --git a/web/src/pages/api/public/observations/[observationId].ts b/web/src/pages/api/public/observations/[observationId].ts
index 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(