🪢 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
/* eslint-disable no-nested-ternary, @repo/component-file-structure, @typescript-eslint/no-use-before-define */
import { GroupedScoreBadges } from "@/src/components/GroupedScoreBadges";
import { JsonSkeleton } from "@/src/components/ui/CodeJsonViewer";
import { Card } from "@/src/components/ui/card";
import { type RouterOutputs, api } from "@/src/utils/api";
import Link from "next/link";
import React from "react";
import { ItemBadge } from "@/src/components/ItemBadge";
import { deepParseJson, type FilterState } from "@langfuse/shared";
import { SessionObservationIO } from "@/src/features/sessions/SessionObservationIO";
import { useObservationCorrections } from "@/src/features/sessions/useObservationCorrections";
import { FilterX } from "@langfuse/icons";
import { SESSION_DETAIL_VIEW_TRIGGER_ID } from "@/src/features/sessions/session-detail-presets";
import { SessionTraceActionButtons } from "@/src/features/sessions/SessionTraceActionButtons";
import {
getVisibleSessionObservations,
SESSION_CARD_OBSERVATIONS_NOTICE_COUNT,
} from "@/src/features/sessions/sessionVisibleObservations";
import {
hasRenderableConversationMessages,
isOnlyJsonMessage,
} from "@/src/features/traces/fns/chatMessageUtils";
import type { IOPreviewContentMode } from "@/src/features/traces/components/IOPreview/IOPreview";
import { useChatMLParser } from "@/src/features/traces/hooks/useChatMLParser";
export type TraceEventsSurface = "card" | "modern";
type SessionObservation =
RouterOutputs["sessions"]["observationsForTraceFromEvents"][number];
const ModernSessionObservation = ({
observation,
projectId,
sessionId,
traceId,
environment,
showCorrections,
outputCorrection,
contentMode,
showSystemPrompt,
onOpenInTraceView,
}: {
observation: SessionObservation;
projectId: string;
sessionId: string;
traceId: string;
environment?: string;
showCorrections: boolean;
outputCorrection?: React.ComponentProps<
typeof SessionObservationIO
>["outputCorrection"];
contentMode: IOPreviewContentMode;
showSystemPrompt?: boolean;
onOpenInTraceView: (observationId: string) => void;
}) => {
const parsed = React.useMemo(
() => ({
input: deepParseJson(observation.input, {
maxSize: 300_000,
maxDepth: 2,
}),
output: deepParseJson(observation.output, {
maxSize: 300_000,
maxDepth: 2,
}),
metadata: deepParseJson(observation.metadata, {
maxSize: 100_000,
maxDepth: 2,
}),
}),
[observation.input, observation.output, observation.metadata],
);
const chatMLParserResult = useChatMLParser(
observation.input ?? undefined,
observation.output ?? undefined,
observation.metadata ?? undefined,
observation.name ?? undefined,
parsed.input,
parsed.output,
parsed.metadata,
);
const isConversation =
chatMLParserResult.canDisplayAsChat &&
(contentMode === "conversation"
? hasRenderableConversationMessages(
chatMLParserResult.allMessages,
showSystemPrompt,
)
: !chatMLParserResult.allMessages.every(isOnlyJsonMessage));
return (
<div
data-session-observation-id={observation.id}
className={
isConversation
? "flex flex-col gap-2"
: "bg-muted/20 flex flex-col gap-2 rounded-md border p-3"
}
>
{!isConversation ? <ObservationHeader observation={observation} /> : null}
<SessionObservationIO
observation={observation}
projectId={projectId}
sessionId={sessionId}
traceId={traceId}
environment={environment}
showCorrections={showCorrections}
outputCorrection={outputCorrection}
onOpenInTraceView={onOpenInTraceView}
contentMode={isConversation ? contentMode : "all"}
showSystemPrompt={showSystemPrompt}
currentView={isConversation ? "pretty" : undefined}
parsedInput={parsed.input}
parsedOutput={parsed.output}
parsedMetadata={parsed.metadata}
chatMLParserResult={chatMLParserResult}
/>
</div>
);
};
const ObservationHeader = ({
observation,
}: {
observation: SessionObservation;
}) => (
<div className="text-muted-foreground flex flex-wrap items-center gap-2 text-xs">
<span className="min-w-0 wrap-break-word">
{observation.name ?? "Observation"}
</span>
<span className="-mr-1">•</span>
<span className="inline-flex items-center gap-1">
<ItemBadge type={observation.type ?? "EVENT"} isSmall />
<span>
{String(observation.type ?? "EVENT")
.toLowerCase()
.replace(/_/g, " ")}
</span>
</span>
<span>•</span>
<span>{observation.startTime.toLocaleString()}</span>
</div>
);
// Opens the session-detail "View" drawer by activating its trigger — the empty
// notice's action routes through the one shared View control (no per-card state).
const openSessionViewMenu = () => {
if (typeof document === "undefined") return;
const trigger = document.getElementById(SESSION_DETAIL_VIEW_TRIGGER_ID);
if (trigger instanceof HTMLElement) trigger.click();
};
/**
* LFE-10520 — replaces the silent "No observations match the current filter."
* empty state. When the selected view (the single source of truth) matches
* nothing in a trace, this says so explicitly instead of rendering a blank
* card. It is purely informational: to see the trace's content the user
* switches the view above — there is no per-card state.
*/
const ViewMismatchNotice = ({ viewLabel }: { viewLabel: string | null }) => (
<div className="flex flex-col items-start gap-1.5 rounded-md border border-dashed border-amber-500/50 bg-amber-500/5 p-3">
<div className="flex items-center gap-2 text-xs font-bold text-amber-700 dark:text-amber-500">
<FilterX size="base" />
{viewLabel
? `No observation matches the "${viewLabel}" view in this trace`
: "No observation matches the current filter in this trace"}
</div>
<p className="text-muted-foreground text-xs">
Its content is hidden by the current view, not missing.{" "}
<button
type="button"
onClick={openSessionViewMenu}
className="text-primary underline underline-offset-2 hover:no-underline"
>
Switch the view
</button>{" "}
to see it.
</p>
</div>
);
export const TraceEventsSkeleton = () => {
return (
<Card className="border-border shadow-none">
<div className="flex h-64 items-center justify-center p-4">
<JsonSkeleton className="h-full w-full" numRows={8} />
</div>
</Card>
);
};
type LazyTraceEventsRowProps = {
trace: RouterOutputs["sessions"]["tracesFromEvents"][number];
projectId: string;
sessionId: string;
openPeek: (id: string, row: any) => void;
index: number;
traceCommentCounts: Map<string, number> | undefined;
showCorrections: boolean;
filterState: FilterState;
/** Selected view's display name, for the empty-state notice (null = custom). */
viewLabel: string | null;
hideTracePanel?: boolean;
surface?: TraceEventsSurface;
contentMode?: IOPreviewContentMode;
showSystemPrompt?: boolean;
};
const areLazyTraceEventsRowPropsEqual = (
previous: LazyTraceEventsRowProps,
next: LazyTraceEventsRowProps,
) =>
previous.trace === next.trace &&
previous.projectId === next.projectId &&
previous.sessionId === next.sessionId &&
previous.openPeek === next.openPeek &&
previous.index === next.index &&
previous.traceCommentCounts === next.traceCommentCounts &&
previous.showCorrections === next.showCorrections &&
previous.filterState === next.filterState &&
previous.viewLabel === next.viewLabel &&
previous.hideTracePanel === next.hideTracePanel &&
previous.surface === next.surface &&
previous.contentMode === next.contentMode &&
previous.showSystemPrompt === next.showSystemPrompt;
export const TraceEventsRow = React.memo(
({
trace,
projectId,
sessionId,
openPeek,
traceCommentCounts,
showCorrections,
filterState,
viewLabel,
hideTracePanel = false,
surface = "card",
contentMode = "all",
showSystemPrompt,
}: {
trace: RouterOutputs["sessions"]["tracesFromEvents"][number];
projectId: string;
sessionId: string;
openPeek: (id: string, row: any) => void;
traceCommentCounts: Map<string, number> | undefined;
showCorrections: boolean;
filterState: FilterState;
viewLabel: string | null;
hideTracePanel?: boolean;
surface?: TraceEventsSurface;
contentMode?: IOPreviewContentMode;
showSystemPrompt?: boolean;
}) => {
const observationsQuery =
api.sessions.observationsForTraceFromEvents.useQuery(
{
projectId,
sessionId,
traceId: trace.id,
filter: filterState,
},
{
enabled: typeof trace.id === "string",
trpc: { context: { skipBatch: true } },
staleTime: 60 * 1000,
},
);
// What each card shows is determined by the selected view (LFE-10520): the
// server applies the view's FilterState (incl. the "with I/O" view's
// Has-Input-or-Output filter). The only client-side shaping is dropping the
// synthetic trace-level row (id `t-<traceId>`, the canonical synthetic-span
// id — see handleEventPropagationJob). It is identified by id, NOT an empty
// parent: OTel/internal-tracing roots also have an empty parent but are real
// observations. It is dropped when redundant — empty, or a real observation
// already shows its (non-empty) input OR output — so a chat turn (the
// GENERATION carries the same assistant output) and the common auto-derived
// case render one card, not two. It is KEPT only when it carries
// trace-level I/O that no observation shows (a v3-migrated trace can set
// trace I/O apart from any observation; dropping it would lose content and
// blind the annotation queue, which hides the trace panel).
// `observationsForTraceFromEvents` returns a BARE ARRAY of observations.
// #15124 briefly wrapped it as `{ observations, hasMoreObservations }`,
// which crashed in-flight old clients that call `.find` on the response
// directly during a rollout (LFE-10958 regression). Read it defensively so
// BOTH shapes are safe: this new client can also briefly hit a not-yet-
// updated server that still returns the envelope, so an Array method must
// never run on a non-array value.
type ObservationsResponse =
RouterOutputs["sessions"]["observationsForTraceFromEvents"];
const observationsData = observationsQuery.data as
| ObservationsResponse
| { observations?: ObservationsResponse }
| undefined;
// Opens the trace peek AT the observation (the session page's peek config
// mirrors row.observationId into the ?observation= param; the annotation
// queue's openPeek opens the trace page in a new tab instead).
const openObservationInTraceView = React.useCallback(
(observationId: string) => {
openPeek(trace.id, { ...trace, observationId });
},
[openPeek, trace],
);
const visibleObservationState = React.useMemo(
() => getVisibleSessionObservations(observationsData, trace.id),
[observationsData, trace.id],
);
const { visibleObservations, hasMoreObservations } =
visibleObservationState;
const correctionsByObservation = useObservationCorrections({
projectId,
traceId: trace.id,
showCorrections,
visibleObservations,
});
const Frame = surface === "card" ? Card : "div";
const showTracePanel = surface === "card" && !hideTracePanel;
return (
<Frame
className={
surface === "card" ? "border-border shadow-none" : "bg-background"
}
>
<div
className={
!showTracePanel
? "grid min-w-0"
: "grid md:grid-cols-[1fr_1px_358px] lg:grid-cols-[1fr_1px_30rem]"
}
>
<div
className={
surface === "card"
? "overflow-hidden py-4 pr-4 pl-4"
: "min-w-0 px-6 pb-10"
}
>
{surface === "modern" ? (
<div className="bg-background/95 sticky top-0 z-10 -mx-6 mb-5 flex min-w-0 items-center justify-between gap-3 px-6 py-3 backdrop-blur">
<button
type="button"
aria-label={`Open trace ${trace.name ?? "Trace"} (${trace.id})`}
className="group focus-visible:ring-ring flex min-w-0 items-center gap-2 rounded-sm text-left focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
onClick={() => openPeek(trace.id, trace)}
>
<ItemBadge type="TRACE" isSmall />
<span
className="truncate text-sm font-bold"
title={trace.name ?? "Trace"}
>
{trace.name ?? "Trace"}
</span>
<span
className="text-muted-foreground min-w-0 truncate font-mono text-xs group-hover:underline"
title={trace.id}
>
{trace.id}
</span>
</button>
<time className="text-muted-foreground shrink-0 text-xs">
{trace.timestamp.toLocaleString()}
</time>
</div>
) : null}
{observationsQuery.isLoading ? (
<JsonSkeleton className="h-full w-full" numRows={8} />
) : observationsQuery.isError ? (
<div className="text-destructive p-2 text-xs">
Failed to load observations.
</div>
) : visibleObservations && visibleObservations.length > 0 ? (
<div className="flex flex-col gap-4">
{visibleObservations.map((observation) => {
if (surface === "modern") {
return (
<ModernSessionObservation
key={observation.id}
observation={observation}
projectId={projectId}
sessionId={sessionId}
traceId={trace.id}
environment={
observation.environment ??
trace.environment ??
undefined
}
showCorrections={showCorrections}
outputCorrection={correctionsByObservation.get(
observation.id,
)}
contentMode={contentMode}
showSystemPrompt={showSystemPrompt}
onOpenInTraceView={openObservationInTraceView}
/>
);
}
return (
<div key={observation.id} className="flex flex-col gap-2">
<ObservationHeader observation={observation} />
<SessionObservationIO
observation={observation}
projectId={projectId}
sessionId={sessionId}
traceId={trace.id}
environment={
observation.environment ??
trace.environment ??
undefined
}
showCorrections={showCorrections}
outputCorrection={correctionsByObservation.get(
observation.id,
)}
onOpenInTraceView={openObservationInTraceView}
contentMode={contentMode}
showSystemPrompt={showSystemPrompt}
/>
</div>
);
})}
{hasMoreObservations && (
<p className="text-muted-foreground text-xs">
Only the first {SESSION_CARD_OBSERVATIONS_NOTICE_COUNT}{" "}
observations are shown here.{" "}
<button
type="button"
onClick={() => openPeek(trace.id, trace)}
className="text-primary underline underline-offset-2 hover:no-underline"
>
Open the trace
</button>{" "}
to see all of them.
</p>
)}
</div>
) : visibleObservations?.length === 0 &&
filterState.length === 0 ? (
// No filter and the trace genuinely has no observations.
<div className="text-muted-foreground p-2 text-xs">
This trace has no observations.
</div>
) : (
// The selected view/filter matched nothing (or hid the only
// observations, e.g. "with I/O" on a trace with none) — say so.
<ViewMismatchNotice viewLabel={viewLabel} />
)}
</div>
{showTracePanel && (
<>
<div className="bg-border hidden md:block"></div>
<div className="flex flex-col border-t py-4 pr-4 pl-4 md:border-0">
<div className="mb-4 flex flex-col gap-2">
<Link
href={`/project/${projectId}/traces/${trace.id}`}
className="hover:bg-accent flex items-start gap-2 rounded-lg border p-2 transition-colors"
onClick={(e) => {
if (!e.metaKey && !e.ctrlKey && !e.shiftKey) {
e.preventDefault();
openPeek(trace.id, trace);
}
}}
>
<ItemBadge type="TRACE" isSmall />
{/* min-w-0 + wrap-break-word: an unbroken long trace
name must wrap inside the panel, not escape the card */}
<div className="flex min-w-0 flex-col">
<span className="text-xs font-bold wrap-break-word">
{trace.name ?? "Trace"} ({trace.id}) ↗
</span>
<span className="text-muted-foreground text-xs">
{trace.timestamp.toLocaleString()}
</span>
</div>
</Link>
<SessionTraceActionButtons
isV4={true}
projectId={projectId}
traceId={trace.id}
timestamp={new Date(trace.timestamp)}
environment={trace.environment}
scores={trace.scores}
traceCommentCounts={traceCommentCounts}
/>
</div>
<div className="flex-1">
<p className="mb-1 font-bold">Scores</p>
<div className="flex flex-wrap content-start items-start gap-1">
<GroupedScoreBadges scores={trace.scores} />
</div>
</div>
</div>
</>
)}
</div>
</Frame>
);
},
);
TraceEventsRow.displayName = "TraceEventsRow";
const LazyTraceEventsRowInner = (props: LazyTraceEventsRowProps) => {
const { index, ...cardProps } = props;
const [shouldLoad, setShouldLoad] = React.useState(false);
const internalRef = React.useRef<HTMLDivElement>(null);
React.useEffect(() => {
if (!internalRef.current || shouldLoad) return;
return observe(internalRef.current, () => setShouldLoad(true));
}, [shouldLoad]);
const setRowRef = React.useCallback((node: HTMLDivElement | null) => {
internalRef.current = node;
}, []);
return (
<div ref={setRowRef} className="pb-3" data-session-row-index={index}>
{shouldLoad ? <TraceEventsRow {...cardProps} /> : <TraceEventsSkeleton />}
</div>
);
};
LazyTraceEventsRowInner.displayName = "LazyTraceEventsRowInner";
export const LazyTraceEventsRow = React.memo(
LazyTraceEventsRowInner,
areLazyTraceEventsRowPropsEqual,
);
LazyTraceEventsRow.displayName = "LazyTraceEventsRow";
const listeners = new Map<Element, () => void>();
let sharedObserver: IntersectionObserver;
function observe(element: Element, callback: () => void) {
if (!sharedObserver) {
sharedObserver = new IntersectionObserver(
(entries) => {
entries.forEach((entry) => {
if (entry.isIntersecting) {
const cb = listeners.get(entry.target);
cb?.();
}
});
},
{ rootMargin: "400px" },
);
}
listeners.set(element, callback);
sharedObserver.observe(element);
return () => {
listeners.delete(element);
sharedObserver.unobserve(element);
};
}