Skip to content

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

8.1 KB
Raw Blame
/**
 * TraceDataContext - Provides read-only trace data and derived structures.
 *
 * Purpose:
 * - Provides trace, observations, scores from props
 * - Computes and memoizes tree structure, nodeMap, and searchItems
 *
 * Not responsible for:
 * - Data fetching (done by parent via API hooks)
 * - UI state (selection, collapsed nodes) - see SelectionContext
 * - Display preferences - see ViewPreferencesContext
 */
import type { TraceSearchListItem } from "@/src/features/traces/types/traceSearchListItem";

import { createContext, useContext, useMemo, type ReactNode } from "react";
import {
  type TraceDomain,
  type ScoreDomain,
  ObservationLevel,
} from "@langfuse/shared";
import { type ObservationReturnTypeWithMetadata } from "@/src/server/api/routers/traces";
import { type WithStringifiedMetadata } from "@/src/utils/clientSideDomainTypes";
import { type TreeNode } from "../types/treeNode";
import {
  buildTraceUiData,
  dedupeObservationsById,
  getObservationLevels,
  removeHiddenNodes,
} from "../fns/treeBuilding";
import { type TraceMetricEmphasis } from "@/src/features/traces/fns/metricEmphasis";
import { useViewPreferences } from "./ViewPreferencesProvider";
import { useMergedScores } from "@/src/features/scores/lib/useMergedScores";
import { traceLevelScoreOwnerIds } from "@/src/features/traces/fns/nodeScores";

type TraceType = Omit<
  WithStringifiedMetadata<TraceDomain>,
  "input" | "output"
> & {
  input: string | null;
  output: string | null;
  /** Server-derived, in seconds. */
  latency?: number;
};

interface TraceDataContextValue {
  trace: TraceType;
  observations: ObservationReturnTypeWithMetadata[];
  serverScores: WithStringifiedMetadata<ScoreDomain>[];
  mergedScores: WithStringifiedMetadata<ScoreDomain>[];
  corrections: ScoreDomain[];
  roots: TreeNode[];
  /** Node ids that own the trace's trace-level scores. Derived from the
   * STRUCTURAL roots, never the level-filtered ones — hiding a root promotes its
   * children into `roots`, and a promoted child is not a stand-in for the trace. */
  traceLevelScoreOwnerIds: Set<string>;
  nodeMap: Map<string, TreeNode>;
  /** Trace-wide cost/duration totals for metric emphasis. Derived from the
   * UNFILTERED tree so level filtering cannot change which rows read bold. */
  metricEmphasis: TraceMetricEmphasis;
  searchItems: TraceSearchListItem[];
  hiddenObservationsCount: number;
  /**
   * Observation that was merged in from a by-id fetch because it sits outside the
   * loaded (capped) list. Its ancestors are unknown, so treeBuilding places it at
   * root level — the views MUST mark it, or a deeply nested observation silently
   * reads as top-level.
   */
  detachedObservationId: string | null;
  /**
   * True when that observation renders at root level WITHOUT being a root: its
   * own parent fell past the cap too, so treeBuilding could not resolve the
   * reference and nulled it. The three cases collapse to this one question —
   * a loaded parent nests correctly, and a genuinely parentless row IS a root —
   * but they must not be conflated: reading "no parent" as "parent is loaded"
   * is what made the UI claim a position it did not have.
   */
  detachedObservationIsMisplaced: boolean;
  /** Observation cap this trace was loaded under, when it hit it. */
  truncatedAtObservations?: number;
  /** This is the previous trace, kept on screen while the next one loads. */
  isPlaceholderData: boolean;
  comments: Map<string, number>;
}

const TraceDataContext = createContext<TraceDataContextValue | null>(null);

export function useTraceData(): TraceDataContextValue {
  const context = useContext(TraceDataContext);
  if (!context) {
    throw new Error("useTraceData must be used within a TraceDataProvider");
  }
  return context;
}

interface TraceDataProviderProps {
  trace: TraceType;
  observations: ObservationReturnTypeWithMetadata[];
  serverScores: WithStringifiedMetadata<ScoreDomain>[];
  corrections: ScoreDomain[];
  comments: Map<string, number>;
  detachedObservationId?: string | null;
  detachedObservationIsMisplaced?: boolean;
  truncatedAtObservations?: number;
  isPlaceholderData?: boolean;
  children: ReactNode;
}

/**
 * TraceDataProvider must be rendered within ViewPreferencesProvider.
 * It consumes minObservationLevel directly from ViewPreferencesContext.
 */
export function TraceDataProvider({
  trace,
  observations: rawObservations,
  serverScores,
  corrections,
  comments,
  detachedObservationId = null,
  detachedObservationIsMisplaced = false,
  truncatedAtObservations,
  isPlaceholderData = false,
  children,
}: TraceDataProviderProps) {
  const { minObservationLevel } = useViewPreferences();

  // Collapse duplicate/colliding observation ids to one row per id up front, so
  // the SAME de-duped set feeds the tree builder AND every consumer that resolves
  // a row from `observations` (notably the detail panel's `observations.find`).
  // Without this the tree picks the earliest-startTime row while the panel's
  // `.find` returns the first row in the raw array — on corrupt traces those can
  // differ, so the timeline and the opened detail panel could silently show
  // different data. No-op (same reference) for well-formed traces.
  const observations = useMemo(
    () => dedupeObservationsById(rawObservations),
    [rawObservations],
  );

  // Build full tree (no level filtering) — only rebuilds when data changes
  const uiData = useMemo(() => {
    return buildTraceUiData(trace, observations);
  }, [trace, observations]);

  // Apply level filtering as a cheap post-processing step
  const { filteredRoots, filteredSearchItems, hiddenObservationsCount } =
    useMemo(() => {
      const allowedLevels = getObservationLevels(minObservationLevel);
      const isAllLevels = allowedLevels.includes(ObservationLevel.DEBUG);

      if (isAllLevels) {
        return {
          filteredRoots: uiData.roots,
          filteredSearchItems: uiData.searchItems,
          hiddenObservationsCount: 0,
        };
      }

      const allowedSet = new Set<string>(allowedLevels);
      const isHidden = (node: TreeNode) =>
        node.type !== "TRACE" && !!node.level && !allowedSet.has(node.level);

      const filteredRoots = removeHiddenNodes(uiData.roots, isHidden);
      const filteredSearchItems = uiData.searchItems.filter(
        (item) => !isHidden(item.node),
      );
      const hiddenObservationsCount =
        uiData.searchItems.length - filteredSearchItems.length;

      return { filteredRoots, filteredSearchItems, hiddenObservationsCount };
    }, [uiData, minObservationLevel]);

  const traceLevelScoreOwnerIdSet = useMemo(
    () =>
      traceLevelScoreOwnerIds(
        uiData.roots,
        // Only a misplaced row is an impostor among the roots; a genuine root
        // that happened to fall past the cap is still a root.
        detachedObservationIsMisplaced ? detachedObservationId : null,
      ),
    [uiData.roots, detachedObservationId, detachedObservationIsMisplaced],
  );

  // Merge scores with optimistic cache
  const mergedScores = useMergedScores(
    serverScores,
    {
      type: "trace",
      traceId: trace.id,
    },
    "target-and-child-scores",
  );

  const value = useMemo<TraceDataContextValue>(
    () => ({
      trace,
      observations,
      serverScores: serverScores,
      mergedScores,
      corrections,
      roots: filteredRoots,
      traceLevelScoreOwnerIds: traceLevelScoreOwnerIdSet,
      nodeMap: uiData.nodeMap,
      metricEmphasis: uiData.metricEmphasis,
      searchItems: filteredSearchItems,
      hiddenObservationsCount,
      detachedObservationId,
      detachedObservationIsMisplaced,
      truncatedAtObservations,
      isPlaceholderData,
      comments,
    }),
    [
      trace,
      observations,
      serverScores,
      mergedScores,
      corrections,
      filteredRoots,
      traceLevelScoreOwnerIdSet,
      filteredSearchItems,
      hiddenObservationsCount,
      detachedObservationId,
      detachedObservationIsMisplaced,
      truncatedAtObservations,
      isPlaceholderData,
      uiData.nodeMap,
      uiData.metricEmphasis,
      comments,
    ],
  );

  return (
    <TraceDataContext.Provider value={value}>
      {children}
    </TraceDataContext.Provider>
  );
}