🪢 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
feat(public-api): optional startTime on GET /observations/{id} (#17193)
Niklas Semmler13edd39b110e
diff --git a/fern/apis/server/definition/legacy/observations-v1.yml b/fern/apis/server/definition/legacy/observations-v1.ymlindex eb7221650f..b024d16bf0 100644--- a/fern/apis/server/definition/legacy/observations-v1.yml+++ b/fern/apis/server/definition/legacy/observations-v1.yml@@ -17,6 +17,12 @@ service:observationId:type: stringdocs: The unique langfuse identifier of an observation, can be an event, span or generation+ request:+ name: GetObservationRequest+ 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.response: commons.ObservationsViewSinglegetMany:availability:diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex 819726ea60..c33d68d897 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -3013,6 +3013,18 @@ paths:required: trueschema:type: string+ - name: startTime+ 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.+ required: false+ schema:+ type: string+ format: date-time+ nullable: trueresponses:'200':description: ''diff --git a/web/src/__tests__/server/observation-api.servertest.ts b/web/src/__tests__/server/observation-api.servertest.tsindex bddb83bf06..edc2eeb45c 100644--- a/web/src/__tests__/server/observation-api.servertest.ts+++ b/web/src/__tests__/server/observation-api.servertest.ts@@ -7,7 +7,10 @@ import {createObservationsCh,createOrgProjectAndApiKey,} from "@langfuse/shared/src/server";-import { makeZodVerifiedAPICall } from "@/src/__tests__/test-utils";+import {+ makeAPICall,+ makeZodVerifiedAPICall,+} from "@/src/__tests__/test-utils";import {GetObservationV1Response,GetObservationsV1Response,@@ -167,6 +170,70 @@ describe("/api/public/observations API Endpoint", () => {});});+ it("should GET an observation when startTime matches its UTC day", async () => {+ const observationId = uuidv4();+ const traceId = uuidv4();+ const startTime = new Date("2024-03-15T08:30:00.000Z").getTime();++ const observation = createObservationData(useEventsTable, {+ id: observationId,+ project_id: projectId,+ trace_id: traceId,+ type: "GENERATION",+ start_time: startTime * timeMultiplier,+ event_ts: startTime * timeMultiplier,+ end_time: startTime * timeMultiplier,+ });++ await insertObservations(useEventsTable, [observation]);++ const getEventRes = await makeZodVerifiedAPICall(+ GetObservationV1Response,+ "GET",+ `/api/public/observations/${observationId}?startTime=2024-03-15T23:59:59.000Z&useEventsTable=${useEventsTable}`,+ );++ expect(getEventRes.body).toMatchObject({+ id: observationId,+ traceId,+ type: "GENERATION",+ });+ });++ it("should 404 when startTime is on a different UTC day", async () => {+ const observationId = uuidv4();+ const traceId = uuidv4();+ const startTime = new Date("2024-03-15T08:30:00.000Z").getTime();++ const observation = createObservationData(useEventsTable, {+ id: observationId,+ project_id: projectId,+ trace_id: traceId,+ type: "GENERATION",+ start_time: startTime * timeMultiplier,+ event_ts: startTime * timeMultiplier,+ end_time: startTime * timeMultiplier,+ });++ await insertObservations(useEventsTable, [observation]);++ const res = await makeAPICall(+ "GET",+ `/api/public/observations/${observationId}?startTime=2024-03-16T00:00:00.000Z&useEventsTable=${useEventsTable}`,+ );++ expect(res.status).toBe(404);+ });++ it("should 400 when startTime lacks a timezone offset", async () => {+ const res = await makeAPICall(+ "GET",+ `/api/public/observations/${uuidv4()}?startTime=2024-03-15T08:30:00&useEventsTable=${useEventsTable}`,+ );++ expect(res.status).toBe(400);+ });+it.each([["AGENT", "agent-observation"],["TOOL", "tool-observation"],diff --git a/web/src/__tests__/server/unit/get-observation-v1-query.servertest.ts b/web/src/__tests__/server/unit/get-observation-v1-query.servertest.tsnew file mode 100644index 0000000000..1dbf026b81--- /dev/null+++ b/web/src/__tests__/server/unit/get-observation-v1-query.servertest.ts@@ -0,0 +1,28 @@+import { GetObservationV1Query } from "@/src/features/public-api/types/observations";++describe("GetObservationV1Query", () => {+ it("parses without startTime (backwards compatible)", () => {+ const result = GetObservationV1Query.safeParse({+ observationId: "obs-1",+ });+ expect(result.success).toBe(true);+ expect(result.data?.startTime).toBeUndefined();+ });++ it("accepts an ISO datetime with a timezone offset", () => {+ const result = GetObservationV1Query.safeParse({+ observationId: "obs-1",+ startTime: "2024-03-15T08:30:00.000Z",+ });+ expect(result.success).toBe(true);+ expect(result.data?.startTime).toBe("2024-03-15T08:30:00.000Z");+ });++ it("rejects a datetime without a timezone offset", () => {+ const result = GetObservationV1Query.safeParse({+ observationId: "obs-1",+ startTime: "2024-03-15T08:30:00",+ });+ expect(result.success).toBe(false);+ });+});diff --git a/web/src/features/public-api/types/observations.ts b/web/src/features/public-api/types/observations.tsindex 120612bbe9..cbe8083fac 100644--- a/web/src/features/public-api/types/observations.ts+++ b/web/src/features/public-api/types/observations.ts@@ -239,6 +239,10 @@ export const GetObservationsV1Response = z// GET /observations/{observationId}export const GetObservationV1Query = z.object({observationId: z.string(),+ // Optional timestamp on the observation's start (ISO 8601 with offset).+ // When provided, it bounds the lookup to that UTC day, making the query+ // dramatically cheaper. Omit it for the default full lookup.+ startTime: stringDateTime,useEventsTable: useEventsTableSchema,});// `_deprecation` at the response level, not on the shared `APIObservation`diff --git a/web/src/pages/api/public/observations/[observationId].ts b/web/src/pages/api/public/observations/[observationId].tsindex f40b4bffb4..3f3213004b 100644--- a/web/src/pages/api/public/observations/[observationId].ts+++ b/web/src/pages/api/public/observations/[observationId].ts@@ -31,17 +31,23 @@ export default withMiddlewares(rejectInEventsOnlyMode: true,deprecation: OBSERVATIONS_V1_DEPRECATION,fn: async ({ query, auth }) => {+ const startTime = query.startTime+ ? 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-deprecatedawait getObservationById({id: query.observationId,projectId: auth.scope.projectId,fetchWithInputOutput: true,+ startTime,preferredClickhouseService: "ReadOnly",});