Skip to content

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

perf(comments): bound observation reference lookups by start_time (#17195)

Niklas Semmler9d08464e89fb
diff --git a/fern/apis/server/definition/comments.yml b/fern/apis/server/definition/comments.yml
index 0378536456..6b461a5dee 100644
--- a/fern/apis/server/definition/comments.yml
+++ b/fern/apis/server/definition/comments.yml
@@ -62,6 +62,9 @@ types:
authorUserId:
type: optional<string>
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.
CreateCommentResponse:
properties:
id:
diff --git a/packages/shared/src/features/comments/types.ts b/packages/shared/src/features/comments/types.ts
index a83f358be2..1fa111156e 100644
--- a/packages/shared/src/features/comments/types.ts
+++ b/packages/shared/src/features/comments/types.ts
@@ -27,6 +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.
+ objectStartTime: z.coerce.date().nullish(),
// Optional inline positioning (parallel arrays)
dataField: z.enum(COMMENT_DATA_FIELDS).nullish(),
path: z.array(jsonPathSchema).nullish(),
diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.yml
index c33d68d897..6e928007a1 100644
--- a/web/public/generated/api/openapi.yml
+++ b/web/public/generated/api/openapi.yml
@@ -9204,6 +9204,15 @@ components:
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: string
+ format: date-time
+ 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.
required:
- projectId
- objectType
diff --git a/web/src/__tests__/server/comments-api.servertest.ts b/web/src/__tests__/server/comments-api.servertest.ts
index af793ca5a7..01c795e1e4 100644
--- a/web/src/__tests__/server/comments-api.servertest.ts
+++ b/web/src/__tests__/server/comments-api.servertest.ts
@@ -15,6 +15,8 @@ import {
createTracesCh,
createObservation,
createTrace,
+ createEvent,
+ createEventsCh,
} from "@langfuse/shared/src/server";
const seedProjectId = "7a88fb47-b4e2-43b8-a06c-a5ce950dc53a";
@@ -98,6 +100,121 @@ describe("Create and get comments", () => {
});
});
+ it("should create an observation comment when objectStartTime bounds the lookup", async () => {
+ const startTime = new Date("2024-05-15T12:00: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({
+ id: observationId,
+ span_id: observationId,
+ project_id: seedProjectId,
+ start_time: startTime,
+ type: "GENERATION",
+ }),
+ ]),
+ createObservationsCh([
+ createObservation({
+ id: observationId,
+ project_id: seedProjectId,
+ start_time: startTime,
+ type: "GENERATION",
+ }),
+ ]),
+ ]);
+
+ const commentResponse = await makeZodVerifiedAPICall(
+ PostCommentsV1Response,
+ "POST",
+ "/api/public/comments",
+ {
+ content: "bounded observation comment",
+ objectId: observationId,
+ objectType: "OBSERVATION",
+ projectId: seedProjectId,
+ objectStartTime: startTime.toISOString(),
+ authorUserId: orgMemberUserId,
+ },
+ );
+
+ const { id: commentId } = commentResponse.body;
+
+ const response = await makeZodVerifiedAPICall(
+ GetCommentV1Response,
+ "GET",
+ `/api/public/comments/${commentId}`,
+ );
+
+ expect(response.status).toBe(200);
+ expect(response.body).toMatchObject({
+ id: commentId,
+ projectId: seedProjectId,
+ objectId: observationId,
+ objectType: "OBSERVATION",
+ content: "bounded observation comment",
+ });
+ });
+
+ 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");
+ const observationId = randomUUID();
+ await Promise.all([
+ createEventsCh([
+ createEvent({
+ id: observationId,
+ span_id: observationId,
+ project_id: seedProjectId,
+ start_time: actualStartTime,
+ type: "GENERATION",
+ }),
+ ]),
+ createObservationsCh([
+ createObservation({
+ id: observationId,
+ project_id: seedProjectId,
+ start_time: actualStartTime,
+ type: "GENERATION",
+ }),
+ ]),
+ ]);
+
+ const commentResponse = await makeZodVerifiedAPICall(
+ PostCommentsV1Response,
+ "POST",
+ "/api/public/comments",
+ {
+ content: "wrong-hint observation comment",
+ objectId: observationId,
+ objectType: "OBSERVATION",
+ projectId: seedProjectId,
+ objectStartTime: wrongStartTime.toISOString(),
+ authorUserId: orgMemberUserId,
+ },
+ );
+
+ const { id: commentId } = commentResponse.body;
+
+ const response = await makeZodVerifiedAPICall(
+ GetCommentV1Response,
+ "GET",
+ `/api/public/comments/${commentId}`,
+ );
+
+ expect(response.status).toBe(200);
+ expect(response.body).toMatchObject({
+ id: commentId,
+ projectId: seedProjectId,
+ objectId: observationId,
+ objectType: "OBSERVATION",
+ content: "wrong-hint observation comment",
+ });
+ });
+
it("should fail to create comment if reference object does not exist", async () => {
expect.assertions(2); // Ensure that we confirm two things
try {
diff --git a/web/src/features/comments/CommentDrawerController.tsx b/web/src/features/comments/CommentDrawerController.tsx
index 93cd91bada..2efe451d3c 100644
--- a/web/src/features/comments/CommentDrawerController.tsx
+++ b/web/src/features/comments/CommentDrawerController.tsx
@@ -16,6 +16,7 @@ type CommentDrawerContentProps = {
projectId: string;
objectId: string;
objectType: CommentObjectType;
+ objectStartTime?: Date | null;
isOpen: boolean;
pendingSelection?: SelectionData | null;
onSelectionUsed?: () => void;
@@ -27,6 +28,7 @@ function CommentDrawerContent({
projectId,
objectId,
objectType,
+ objectStartTime,
isOpen,
pendingSelection,
onSelectionUsed,
@@ -63,6 +65,7 @@ function CommentDrawerContent({
projectId={projectId}
objectId={objectId}
objectType={objectType}
+ objectStartTime={objectStartTime}
onMentionDropdownChange={onMentionDropdownChange}
isDrawerOpen={isOpen}
pendingSelection={pendingSelection}
@@ -79,6 +82,7 @@ export type CommentDrawerControllerProps = {
projectId: string;
objectId: string;
objectType: CommentObjectType;
+ objectStartTime?: Date | null;
count?: number;
pendingSelection?: SelectionData | null;
onSelectionUsed?: () => void;
@@ -96,6 +100,7 @@ export function CommentDrawerController({
projectId,
objectId,
objectType,
+ objectStartTime,
count,
pendingSelection,
onSelectionUsed,
@@ -184,6 +189,7 @@ export function CommentDrawerController({
projectId={projectId}
objectId={objectId}
objectType={objectType}
+ objectStartTime={objectStartTime}
isOpen={isOpen}
pendingSelection={pendingSelection}
onSelectionUsed={onSelectionUsed}
diff --git a/web/src/features/comments/CommentList.tsx b/web/src/features/comments/CommentList.tsx
index ff7d10970f..9a0b0f692f 100644
--- a/web/src/features/comments/CommentList.tsx
+++ b/web/src/features/comments/CommentList.tsx
@@ -80,6 +80,7 @@ export function CommentList({
projectId,
objectId,
objectType,
+ objectStartTime,
cardView = false,
className,
onDraftChange,
@@ -92,6 +93,7 @@ export function CommentList({
projectId: string;
objectId: string;
objectType: CommentObjectType;
+ objectStartTime?: Date | null;
cardView?: boolean;
className?: string;
onDraftChange?: (hasDraft: boolean) => void;
@@ -422,6 +424,7 @@ export function CommentList({
function onSubmit(values: z.infer<typeof CreateCommentData>) {
createCommentMutation.mutateAsync({
...values,
+ objectStartTime: objectStartTime ?? undefined,
dataField: pendingSelection?.dataField,
path: pendingSelection?.path,
rangeStart: pendingSelection?.rangeStart,
diff --git a/web/src/features/comments/validateCommentReferenceObject.ts b/web/src/features/comments/validateCommentReferenceObject.ts
index ad25bd436f..26000d57a2 100644
--- a/web/src/features/comments/validateCommentReferenceObject.ts
+++ b/web/src/features/comments/validateCommentReferenceObject.ts
@@ -1,4 +1,8 @@
-import { CommentObjectType, type CreateCommentData } from "@langfuse/shared";
+import {
+ CommentObjectType,
+ type CreateCommentData,
+ LangfuseNotFoundError,
+} from "@langfuse/shared";
import { type z } from "zod";
import {
getObservationById,
@@ -13,16 +17,30 @@ export const validateCommentReferenceObject = async ({
ctx: any;
input: z.infer<typeof CreateCommentData>;
}): Promise<{ errorMessage?: string }> => {
- const { objectId, objectType, projectId } = input;
+ const { objectId, objectType, projectId, objectStartTime } = input;
let commentTarget;
switch (objectType) {
case CommentObjectType.OBSERVATION: {
- // eslint-disable-next-line @typescript-eslint/no-deprecated
- commentTarget = await getObservationById({
- id: objectId,
- projectId,
- });
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-deprecated
+ 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.
+ 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 });
+ }
break;
}
case CommentObjectType.TRACE: {
diff --git a/web/src/features/public-api/types/comments.ts b/web/src/features/public-api/types/comments.ts
index 6aa39b851a..7845c8eef6 100644
--- a/web/src/features/public-api/types/comments.ts
+++ b/web/src/features/public-api/types/comments.ts
@@ -37,6 +37,7 @@ export const PostCommentsV1Body = z
})
.extend({
authorUserId: z.string().nullish(),
+ objectStartTime: z.coerce.date().nullish(),
})
.strict();
export const PostCommentsV1Response = z.object({ id: z.string() }).strict();
diff --git a/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx b/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx
index dc27bd5d8a..d1c8700751 100644
--- a/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx
+++ b/web/src/features/traces/components/ObservationDetailView/components/ObservationDetailViewHeader/ObservationDetailViewHeader.tsx
@@ -466,6 +466,7 @@ export const ObservationDetailViewHeader = memo(
projectId={projectId}
objectId={observation.id}
objectType="OBSERVATION"
+ objectStartTime={observation.startTime}
count={commentCount}
pendingSelection={pendingSelection}
onSelectionUsed={onSelectionUsed}
@@ -681,6 +682,7 @@ export const ObservationDetailViewHeader = memo(
projectId={projectId}
objectId={observation.id}
objectType="OBSERVATION"
+ objectStartTime={observation.startTime}
count={commentCount}
pendingSelection={pendingSelection}
onSelectionUsed={onSelectionUsed}