🪢 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
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.ymlindex 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.tsindex 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 = 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.+ 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.ymlindex 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 theorganization that owns the project, otherwise an error will bethrown.+ 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- objectTypediff --git a/web/src/__tests__/server/comments-api.servertest.ts b/web/src/__tests__/server/comments-api.servertest.tsindex 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 thingstry {diff --git a/web/src/features/comments/CommentDrawerController.tsx b/web/src/features/comments/CommentDrawerController.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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}