Skip to content

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

6.4 KB
Raw Blame
import { useMemo } from "react";
import { keepPreviousData } from "@tanstack/react-query";
import {
  api,
  sendAsPostOption,
  shouldRetryResourceQuery,
} from "@/src/utils/api";
import { useLatched } from "@/src/hooks/useLatched";
import {
  adaptEventsToTraceFormat,
  type AdaptedTraceData,
  type EventsTraceObservation,
} from "@/src/features/events/lib/eventsToTraceAdapter";
import {
  filterAndValidateDbScoreList,
  ScoreDataTypeArray,
  ScoreDataTypeEnum,
  type ScoreDomain,
} from "@langfuse/shared";
import {
  type WithStringifiedMetadata,
  toDomainArrayWithStringifiedMetadata,
} from "@/src/utils/clientSideDomainTypes";
import { partition } from "lodash";

interface UseEventsTraceDataProps {
  projectId: string;
  traceId: string;
  timestamp?: Date;
  enabled?: boolean;
}

interface UseEventsTraceDataResult {
  data:
    | (AdaptedTraceData["trace"] & {
        observations: AdaptedTraceData["observations"];
        scores: WithStringifiedMetadata<ScoreDomain>[];
        corrections: ScoreDomain[];
      })
    | undefined;
  isLoading: boolean;
  error: unknown;
  /**
   * The observation cap this trace was loaded under, set ONLY when the trace hit
   * it (so the list is missing its chronological tail). The number comes from the
   * server response — never a client-side copy of the constant.
   */
  truncatedAtObservations: number | undefined;
  /** `data` is the previously loaded trace, kept on screen while this one loads. */
  isPlaceholderData: boolean;
}

/**
 * Hook to fetch trace data from the events table instead of traces table.
 * Used when v4 beta mode is enabled.
 *
 * Data flow:
 * 1. Fetch all observations for the trace via events.all (without I/O)
 * 2. Find root observation (no parentObservationId)
 * 3. Fetch root observation's I/O via events.batchIO
 * 4. Fetch scores via getScoresAndCorrectionsForTraces
 * 5. Synthesize trace object from observations
 */
export function useEventsTraceData(
  props: UseEventsTraceDataProps,
): UseEventsTraceDataResult {
  const { projectId, traceId, enabled = true } = props;

  // Step 1: Fetch all observations for this trace (without I/O for performance)
  const eventsQuery = api.events.byTraceId.useQuery(
    {
      projectId,
      traceId,
      timestamp: props.timestamp,
    },
    {
      enabled: enabled && !!traceId,
      retry: shouldRetryResourceQuery,
      staleTime: 60 * 1000, // 1 minute
      placeholderData: keepPreviousData,
    },
  );

  // Step 2: Find root observation and calculate time range for batchIO
  const observations = eventsQuery.data?.observations as
    | EventsTraceObservation[]
    | undefined;

  const rootObservation = useMemo(() => {
    if (!observations?.length) return null;
    return observations.find((o) => !o.parentObservationId);
  }, [observations]);

  // Prefer the root observation when present, otherwise fall back to the earliest one.
  const primaryObservation = useMemo(() => {
    if (!observations?.length) return null;
    if (rootObservation) return rootObservation;
    // Fallback to earliest observation
    return (
      [...observations].sort(
        (a, b) => a.startTime.getTime() - b.startTime.getTime(),
      )[0] ?? null
    );
  }, [observations, rootObservation]);

  const timeRange = useMemo(() => {
    if (!observations?.length) return null;
    const times = observations.map((o) => o.startTime.getTime());
    return {
      min: new Date(Math.min(...times)),
      max: new Date(Math.max(...times)),
    };
  }, [observations]);

  // Step 3: Fetch I/O for the primary trace observation.
  const rootIOQuery = api.events.batchIO.useQuery(
    {
      projectId,
      traceId,
      observations: primaryObservation
        ? [{ id: primaryObservation.id, traceId }]
        : [],
      minStartTime: timeRange?.min ?? new Date(),
      maxStartTime: timeRange?.max ?? new Date(),
      truncated: false,
    },
    {
      ...sendAsPostOption,
      // Not while the observations are the previous trace's: the request would
      // pair its root with the new trace id.
      enabled:
        enabled &&
        !!primaryObservation &&
        !!timeRange &&
        !!eventsQuery.data &&
        !eventsQuery.isPlaceholderData,
      staleTime: 60 * 1000,
    },
  );

  // Step 4: Fetch scores for the trace
  const scoresQuery = api.events.scoresForTrace.useQuery(
    { traceId, projectId, timestamp: props.timestamp },
    {
      enabled: enabled && !!traceId,
      staleTime: 60 * 1000,
      placeholderData: keepPreviousData,
    },
  );

  // Step 5: Transform and merge data
  const transformed = useMemo(() => {
    if (!observations?.length) return null;

    // Validate and partition scores
    const validatedScores = filterAndValidateDbScoreList({
      scores: scoresQuery.data ?? [],
      dataTypes: [...ScoreDataTypeArray],
      onParseError: (e) => {
        console.error("[useEventsTraceData] Score validation error:", e);
      },
    });

    const [corrections, scores] = partition(
      validatedScores,
      (s) => s.dataType === ScoreDataTypeEnum.CORRECTION,
    );

    const scoresDomain = toDomainArrayWithStringifiedMetadata(scores);

    const rootIO = rootIOQuery.data?.[0];

    // Adapt events to trace format
    const adapted = adaptEventsToTraceFormat({
      events: observations,
      traceId,
      rootIO: rootIO
        ? {
            input: rootIO.input,
            output: rootIO.output,
            metadata: rootIO.metadata,
          }
        : undefined,
    });

    return {
      ...adapted.trace,
      observations: adapted.observations,
      scores: scoresDomain,
      corrections,
    };
  }, [observations, traceId, rootIOQuery.data, scoresQuery.data]);

  // After a trace switch the two queries resolve independently, so the previous
  // trace stays whole (observations, I/O, scores) until both carry the new one.
  const isPlaceholderData =
    eventsQuery.isPlaceholderData || scoresQuery.isPlaceholderData;
  const live = useMemo(
    () => ({
      data: transformed ?? undefined,
      truncatedAtObservations: eventsQuery.data?.cutoffObservationsAfterMaxCount
        ? eventsQuery.data.maxObservationsPerTrace
        : undefined,
    }),
    [transformed, eventsQuery.data],
  );
  const shown = useLatched(live, isPlaceholderData);

  return {
    data: shown.data,
    isLoading: eventsQuery.isLoading || scoresQuery.isLoading,
    error: eventsQuery.error || scoresQuery.error,
    truncatedAtObservations: shown.truncatedAtObservations,
    isPlaceholderData,
  };
}