Skip to content

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

feat(modern-session): display arbitrary metadata (#16063)

Nimar1eb99bd31bd0
diff --git a/web/src/components/SingleLineOverflowList.tsx b/web/src/components/SingleLineOverflowList.tsx
index 3c3536f246..ed01d38878 100644
--- a/web/src/components/SingleLineOverflowList.tsx
+++ b/web/src/components/SingleLineOverflowList.tsx
@@ -6,7 +6,8 @@ import { type ReactNode, useEffect, useRef, useState } from "react";
* remeasures when its width, item widths, or overflow-control width changes.
* `additionalOverflowCount` reserves the control for paginated or virtualized
* entries that should not be mounted in the measurement row. Item and overflow
- * presentation remain entirely caller-defined.
+ * presentation remain entirely caller-defined. `trailingContent` stays pinned
+ * immediately after the overflow control and participates in width measurement.
*/
export function SingleLineOverflowList<TItem>({
items,
@@ -14,6 +15,7 @@ export function SingleLineOverflowList<TItem>({
getKey,
renderItem,
renderOverflow,
+ trailingContent,
}: {
items: readonly TItem[];
additionalOverflowCount: number;
@@ -23,9 +25,11 @@ export function SingleLineOverflowList<TItem>({
hiddenItems: readonly TItem[];
overflowItemCount: number;
}) => ReactNode;
+ trailingContent?: ReactNode;
}) {
const measurementRowRef = useRef<HTMLDivElement>(null);
const overflowRef = useRef<HTMLDivElement>(null);
+ const trailingContentRef = useRef<HTMLDivElement>(null);
const [hiddenKeys, setHiddenKeys] = useState<string[]>([]);
const itemKeys = items.map(getKey);
const itemKeySignature = itemKeys.join("\u0000");
@@ -33,6 +37,8 @@ export function SingleLineOverflowList<TItem>({
const visibleItems = items.filter((item) => !hiddenKeySet.has(getKey(item)));
const hiddenItems = items.filter((item) => hiddenKeySet.has(getKey(item)));
const overflowItemCount = hiddenItems.length + additionalOverflowCount;
+ const hasTrailingContent =
+ trailingContent !== null && trailingContent !== undefined;
useEffect(() => {
const measurementRow = measurementRowRef.current;
@@ -44,17 +50,23 @@ export function SingleLineOverflowList<TItem>({
const contentWidth = lastItem
? lastItem.offsetLeft + lastItem.offsetWidth
: 0;
- const hasOverflow =
- additionalOverflowCount > 0 ||
- contentWidth > measurementRow.clientWidth - 1;
const gap = Number.parseFloat(
window.getComputedStyle(measurementRow).columnGap,
);
+ const normalizedGap = Number.isFinite(gap) ? gap : 0;
+ const trailingContentWidth = trailingContentRef.current?.offsetWidth ?? 0;
+ const availableWidthBeforeOverflow =
+ measurementRow.clientWidth -
+ trailingContentWidth -
+ (trailingContentWidth > 0 ? normalizedGap : 0);
+ const hasOverflow =
+ additionalOverflowCount > 0 ||
+ contentWidth > availableWidthBeforeOverflow - 1;
const availableWidth = hasOverflow
- ? measurementRow.clientWidth -
+ ? availableWidthBeforeOverflow -
(overflowRef.current?.offsetWidth ?? 0) -
- (Number.isFinite(gap) ? gap : 0)
- : measurementRow.clientWidth;
+ normalizedGap
+ : availableWidthBeforeOverflow;
const nextHiddenKeys = itemElements.flatMap((element) => {
const key = element.dataset.overflowItemKey;
return key &&
@@ -82,9 +94,17 @@ export function SingleLineOverflowList<TItem>({
if (overflowRef.current) {
resizeObserver.observe(overflowRef.current);
}
+ if (trailingContentRef.current) {
+ resizeObserver.observe(trailingContentRef.current);
+ }
return () => resizeObserver.disconnect();
- }, [additionalOverflowCount, itemKeySignature, overflowItemCount]);
+ }, [
+ additionalOverflowCount,
+ hasTrailingContent,
+ itemKeySignature,
+ overflowItemCount,
+ ]);
return (
<div className="relative flex min-w-0 flex-1 items-center gap-2 overflow-hidden">
@@ -125,6 +145,11 @@ export function SingleLineOverflowList<TItem>({
{renderOverflow({ hiddenItems, overflowItemCount })}
</div>
) : null}
+ {hasTrailingContent ? (
+ <div ref={trailingContentRef} className="flex shrink-0 items-center">
+ {trailingContent}
+ </div>
+ ) : null}
</div>
);
}
diff --git a/web/src/components/session/ModernSessionHeader.stories.tsx b/web/src/components/session/ModernSessionHeader.stories.tsx
index d57d5da57f..e831ffda91 100644
--- a/web/src/components/session/ModernSessionHeader.stories.tsx
+++ b/web/src/components/session/ModernSessionHeader.stories.tsx
@@ -1,5 +1,5 @@
-import { type ComponentProps } from "react";
-import { expect, userEvent, waitFor, within } from "storybook/test";
+import { type ComponentProps, useState } from "react";
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
import preview from "../../../.storybook/preview";
import { ModernSessionHeader } from "@/src/components/session/ModernSessionHeader";
@@ -45,9 +45,27 @@ const defaultArgs = {
totalCost: 0.084291,
environment: "production",
+ metadataJsonPaths: {
+ paths: [],
+ source: { state: "idle" },
+ onEditorOpenChange: fn(),
+ onSave: fn(),
+ onRemove: fn(),
+ },
scores,
} satisfies ComponentProps<typeof ModernSessionHeader>;
+const minimalArgs = {
+ ...defaultArgs,
+ traces: { state: "loading" },
+ tokensIn: 0,
+ tokensOut: 0,
+ totalTokens: 0,
+ environment: null,
+ users: [],
+ scores: [],
+} satisfies ComponentProps<typeof ModernSessionHeader>;
+
const meta = preview.meta({
component: ModernSessionHeader,
parameters: { layout: "fullscreen", a11y: { test: "error" } },
@@ -58,16 +76,7 @@ export default meta;
export const Default = meta.story({ args: defaultArgs });
export const Minimal = meta.story({
- args: {
- ...defaultArgs,
- traces: { state: "loading" },
- tokensIn: 0,
- tokensOut: 0,
- totalTokens: 0,
- environment: null,
- users: [],
- scores: [],
- },
+ args: minimalArgs,
});
export const Overflow = meta.story({
@@ -77,11 +86,38 @@ export const Overflow = meta.story({
},
});
+export const ConfiguredMetadata = meta.story({
+ args: {
+ ...minimalArgs,
+ metadataJsonPaths: {
+ ...defaultArgs.metadataJsonPaths,
+ paths: ["$.langfuse_user_email", "$.cloud_region"],
+ source: {
+ state: "ready",
+ metadata: {
+ langfuse_user_email: "[email protected]",
+ cloud_region: "EU",
+ },
+ metadataTruncated: false,
+ },
+ },
+ },
+});
+
export const TestSearchesHiddenPills = meta.story({
name: "(Test) Searches hidden pills",
args: {
...defaultArgs,
scores: overflowScores,
+ metadataJsonPaths: {
+ ...defaultArgs.metadataJsonPaths,
+ paths: ["$.cloud_region"],
+ source: {
+ state: "ready",
+ metadata: { cloud_region: "EU" },
+ metadataTruncated: false,
+ },
+ },
},
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
@@ -112,6 +148,14 @@ export const TestSearchesHiddenPills = meta.story({
(lastVisiblePillRect.top + lastVisiblePillRect.height / 2),
),
).toBeLessThanOrEqual(0.5);
+ const trailingButton = canvas.getByRole("button", {
+ name: "Add metadata JSONPath",
+ });
+ const trailingGap =
+ trailingButton.getBoundingClientRect().left -
+ overflowButton.getBoundingClientRect().right;
+ await expect(trailingGap).toBeGreaterThanOrEqual(0);
+ await expect(trailingGap).toBeLessThanOrEqual(8);
await userEvent.click(overflowButton);
@@ -122,10 +166,10 @@ export const TestSearchesHiddenPills = meta.story({
const dialog = body.getByRole("dialog");
await expect(within(dialog).queryByText(/traces/i)).not.toBeInTheDocument();
- await userEvent.type(searchInput, "Quality 16");
- await expect(within(dialog).getByText("Quality 16")).toBeInTheDocument();
+ await userEvent.type(searchInput, "cloud_region");
+ await expect(within(dialog).getByText("cloud_region")).toBeInTheDocument();
await expect(
- within(dialog).queryByText("Quality 1"),
+ within(dialog).queryByText("Quality 16"),
).not.toBeInTheDocument();
},
});
@@ -179,3 +223,86 @@ export const TestBoundsManyUsers = meta.story({
).toBeInTheDocument();
},
});
+
+export const TestConfiguresMultipleMetadataPaths = meta.story({
+ name: "(Test) Configures multiple metadata paths",
+ args: {
+ ...minimalArgs,
+ metadataJsonPaths: {
+ ...defaultArgs.metadataJsonPaths,
+ source: {
+ state: "ready",
+ metadata: {
+ email: "[email protected]",
+ cloud_region: "EU",
+ },
+ metadataTruncated: false,
+ },
+ },
+ },
+ render: function Render(args) {
+ const [paths, setPaths] = useState<readonly string[]>([]);
+ return (
+ <ModernSessionHeader
+ {...args}
+ metadataJsonPaths={{
+ ...args.metadataJsonPaths,
+ paths,
+ onSave: (path) => setPaths((current) => [...current, path]),
+ onRemove: (path) =>
+ setPaths((current) => current.filter((item) => item !== path)),
+ }}
+ />
+ );
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const body = within(canvasElement.ownerDocument.body);
+ const openEditor = () =>
+ userEvent.click(
+ canvas.getByRole("button", { name: "Add metadata JSONPath" }),
+ );
+
+ await openEditor();
+ let input = body.getByLabelText("Metadata JSONPath");
+ let save = body.getByRole("button", { name: "Save" });
+ await expect(
+ body.getByText("Enter a JSONPath to preview metadata."),
+ ).toBeInTheDocument();
+ await expect(
+ body.queryByText("JSONPath must start with $."),
+ ).not.toBeInTheDocument();
+ await userEvent.type(input, "$.email");
+ await userEvent.click(save);
+
+ await openEditor();
+ input = body.getByLabelText("Metadata JSONPath");
+ save = body.getByRole("button", { name: "Save" });
+ await userEvent.type(input, "$.email");
+ await expect(
+ body.getByText("This JSONPath is already shown."),
+ ).toBeInTheDocument();
+ await expect(save).toBeDisabled();
+
+ await userEvent.clear(input);
+ await userEvent.type(input, "$.cloud_region");
+ await userEvent.click(save);
+ const getVisibleText = (text: string) =>
+ canvas
+ .getAllByText(text)
+ .find((element) => element.closest("[data-overflow-visible-item]"));
+ await expect(getVisibleText("email")).toBeInTheDocument();
+ await expect(getVisibleText("cloud_region")).toBeInTheDocument();
+ await expect(getVisibleText("EU")).toBeInTheDocument();
+
+ const email = getVisibleText("email")!;
+ await userEvent.hover(email);
+ await userEvent.click(
+ canvas.getByRole("button", {
+ name: "Remove metadata JSONPath $.email",
+ }),
+ );
+ await expect(canvas.queryByText("email")).not.toBeInTheDocument();
+ await expect(getVisibleText("cloud_region")).toBeInTheDocument();
+ },
+});
diff --git a/web/src/components/session/ModernSessionHeader.tsx b/web/src/components/session/ModernSessionHeader.tsx
index b64d2ade25..38d596610e 100644
--- a/web/src/components/session/ModernSessionHeader.tsx
+++ b/web/src/components/session/ModernSessionHeader.tsx
@@ -1,14 +1,22 @@
import { percentile, type ScoreDomain } from "@langfuse/shared";
-import { ArrowUpRight, Search } from "lucide-react";
-import { type ReactNode, useState } from "react";
+import { ArrowUpRight, Plus, Search, X } from "lucide-react";
+import { type ReactNode, type SyntheticEvent, useState } from "react";
import { SingleLineOverflowList } from "@/src/components/SingleLineOverflowList";
import { ModernSessionHeaderPill } from "@/src/components/session/ModernSessionHeaderPill";
+import {
+ getMetadataJsonPathLabel,
+ resolveMetadataJsonPath,
+ type FirstVisibleObservationMetadataState,
+ type SessionMetadataJsonPathState,
+} from "@/src/components/session/sessionMetadataJsonPath";
import {
INITIAL_SESSION_USERS_DISPLAY_COUNT,
SESSION_USERS_PER_PAGE,
} from "@/src/components/session/sessionUsers";
import { Input } from "@/src/components/ui/input";
+import { Button } from "@/src/components/ui/button";
+import { Label } from "@/src/components/ui/label";
import {
Popover,
PopoverContent,
@@ -17,6 +25,7 @@ import {
import { formatIntervalSeconds } from "@/src/utils/dates";
import { type WithStringifiedMetadata } from "@/src/utils/clientSideDomainTypes";
import { numberFormatter, usdFormatter } from "@/src/utils/numbers";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
type ModernSessionHeaderProps = {
projectId: string;
@@ -36,6 +45,7 @@ type ModernSessionHeaderProps = {
totalCost: number;
environment: string | null;
users: readonly string[];
+ metadataJsonPaths: SessionMetadataJsonPathState;
scores: ReadonlyArray<
Pick<
WithStringifiedMetadata<ScoreDomain>,
@@ -64,7 +74,6 @@ const UserChip = ({ projectId, user }: { projectId: string; user: string }) => (
<ModernSessionHeaderPill
variant="link"
href={`/project/${projectId}/users/${encodeURIComponent(user)}`}
- title={user}
>
user{" "}
<span
@@ -77,6 +86,170 @@ const UserChip = ({ projectId, user }: { projectId: string; user: string }) => (
</ModernSessionHeaderPill>
);
+const resolveAgainstSource = (
+ source: FirstVisibleObservationMetadataState,
+ path: string,
+) => {
+ if (source.state === "ready") {
+ return resolveMetadataJsonPath(source.metadata, path);
+ }
+
+ const syntax = resolveMetadataJsonPath({}, path);
+ if (syntax.state === "invalid") return syntax;
+ return source;
+};
+
+const getConfiguredMetadataDisplay = (
+ path: string,
+ source: FirstVisibleObservationMetadataState,
+) => {
+ const resolution = resolveAgainstSource(source, path);
+ return {
+ path,
+ label: getMetadataJsonPathLabel(path),
+ displayValue:
+ resolution.state === "match"
+ ? resolution.displayValue
+ : resolution.state === "loading" || resolution.state === "idle"
+ ? "…"
+ : "—",
+ };
+};
+
+const MetadataJsonPathPill = ({
+ display,
+ onRemove,
+}: {
+ display: ReturnType<typeof getConfiguredMetadataDisplay>;
+ onRemove: (path: string) => void;
+}) => (
+ <span className="group flex items-center">
+ <ModernSessionHeaderPill variant="display">
+ <span className="max-w-40 truncate" title={display.path}>
+ {display.label}
+ </span>
+ <span
+ className="text-foreground max-w-56 truncate"
+ title={display.displayValue}
+ >
+ {display.displayValue}
+ </span>
+ <span className="-ml-1.5 inline-flex w-0 overflow-hidden transition-[width,margin] group-focus-within:ml-0 group-focus-within:w-4 group-hover:ml-0 group-hover:w-4">
+ <button
+ type="button"
+ aria-label={`Remove metadata JSONPath ${display.path}`}
+ title="Remove metadata JSONPath"
+ className="hover:bg-muted focus-visible:ring-ring inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-sm opacity-0 transition-opacity group-focus-within:opacity-100 group-hover:opacity-100 focus-visible:ring-1 focus-visible:outline-none"
+ onClick={() => onRemove(display.path)}
+ >
+ <X className="h-3 w-3" />
+ </button>
+ </span>
+ </ModernSessionHeaderPill>
+ </span>
+);
+
+const MetadataJsonPathEditorContent = ({
+ metadataJsonPaths,
+ onClose,
+ onSave,
+}: {
+ metadataJsonPaths: SessionMetadataJsonPathState;
+ onClose: () => void;
+ onSave: (path: string) => void;
+}) => {
+ const [draftPath, setDraftPath] = useState("");
+ const normalizedDraftPath = draftPath.trim();
+ const draftResolution = resolveAgainstSource(
+ metadataJsonPaths.source,
+ draftPath,
+ );
+ const draftIsDuplicate =
+ metadataJsonPaths.paths.includes(normalizedDraftPath);
+ const draftIsValid =
+ normalizedDraftPath.length > 0 &&
+ draftResolution.state !== "invalid" &&
+ !draftIsDuplicate;
+
+ const handleSubmit = (event: SyntheticEvent<HTMLFormElement>) => {
+ event.preventDefault();
+ if (!draftIsValid) return;
+ onSave(normalizedDraftPath);
+ onClose();
+ };
+
+ return (
+ <PopoverContent
+ align="end"
+ className="w-96"
+ aria-label="Add metadata JSONPath"
+ >
+ <form className="flex flex-col gap-3" onSubmit={handleSubmit}>
+ <div className="flex flex-col gap-1.5">
+ <Label htmlFor="session-metadata-jsonpath">Metadata JSONPath</Label>
+ <Input
+ id="session-metadata-jsonpath"
+ value={draftPath}
+ onChange={(event) => setDraftPath(event.target.value)}
+ placeholder="$.langfuse_user_email"
+ autoComplete="off"
+ spellCheck={false}
+ />
+ </div>
+ <div className="bg-muted/40 flex min-h-14 flex-col gap-1 rounded-md border p-2 text-xs">
+ <span className="text-muted-foreground font-bold">Preview</span>
+ {normalizedDraftPath.length === 0 ? (
+ <span className="text-muted-foreground">
+ Enter a JSONPath to preview metadata.
+ </span>
+ ) : draftIsDuplicate ? (
+ <span className="text-muted-foreground">
+ This JSONPath is already shown.
+ </span>
+ ) : draftResolution.state === "match" ? (
+ <span className="font-mono break-all">
+ {draftResolution.displayValue}
+ </span>
+ ) : draftResolution.state === "invalid" ? (
+ <span className="text-destructive">{draftResolution.message}</span>
+ ) : draftResolution.state === "loading" ||
+ draftResolution.state === "idle" ? (
+ <span className="text-muted-foreground">
+ Loading first visible observation…
+ </span>
+ ) : draftResolution.state === "error" ? (
+ <span className="text-destructive">
+ Could not load the first visible observation.
+ </span>
+ ) : draftResolution.state === "empty" ? (
+ <span className="text-muted-foreground">
+ No observation matches the current view.
+ </span>
+ ) : (
+ <span className="text-muted-foreground">
+ No match on the first visible observation.
+ </span>
+ )}
+ {metadataJsonPaths.source.state === "ready" &&
+ metadataJsonPaths.source.metadataTruncated ? (
+ <span className="text-amber-600 dark:text-amber-500">
+ Metadata is truncated in this session preview.
+ </span>
+ ) : null}
+ </div>
+ <div className="flex items-center justify-end gap-2">
+ <Button type="button" variant="ghost" size="sm" onClick={onClose}>
+ Cancel
+ </Button>
+ <Button type="submit" size="sm" disabled={!draftIsValid}>
+ Save
+ </Button>
+ </div>
+ </form>
+ </PopoverContent>
+ );
+};
+
export function ModernSessionHeader({
projectId,
countTraces,
@@ -87,12 +260,35 @@ export function ModernSessionHeader({
totalCost,
environment,
users,
+ metadataJsonPaths,
scores,
}: ModernSessionHeaderProps) {
+ const capture = usePostHogClientCapture();
const [search, setSearch] = useState("");
const [visibleUserCount, setVisibleUserCount] = useState(
SESSION_USERS_PER_PAGE,
);
+ const [isMetadataEditorOpen, setIsMetadataEditorOpen] = useState(false);
+ const handleMetadataEditorOpenChange = (open: boolean) => {
+ setIsMetadataEditorOpen(open);
+ metadataJsonPaths.onEditorOpenChange(open);
+ };
+ const saveMetadataJsonPath = (path: string) => {
+ metadataJsonPaths.onSave(path);
+ capture("session_detail:metadata_jsonpath_config_changed", {
+ action: "add",
+ configuredPathCount: metadataJsonPaths.paths.length + 1,
+ isV4: true,
+ });
+ };
+ const removeMetadataJsonPath = (path: string) => {
+ metadataJsonPaths.onRemove(path);
+ capture("session_detail:metadata_jsonpath_config_changed", {
+ action: "remove",
+ configuredPathCount: Math.max(metadataJsonPaths.paths.length - 1, 0),
+ isV4: true,
+ });
+ };
const latencies =
traces.state === "loaded"
? traces.data.flatMap((trace) =>
@@ -238,6 +434,23 @@ export function ModernSessionHeader({
});
const remainingUsers = users.slice(INITIAL_SESSION_USERS_DISPLAY_COUNT);
+ metadataJsonPaths.paths.forEach((path) => {
+ const display = getConfiguredMetadataDisplay(
+ path,
+ metadataJsonPaths.source,
+ );
+ pills.push({
+ key: `metadata-${path}`,
+ searchText: `metadata ${display.path} ${display.label} ${display.displayValue}`,
+ content: (
+ <MetadataJsonPathPill
+ display={display}
+ onRemove={removeMetadataJsonPath}
+ />
+ ),
+ });
+ });
+
return (
<div className="bg-header border-b px-4 py-2">
<SingleLineOverflowList
@@ -245,6 +458,28 @@ export function ModernSessionHeader({
additionalOverflowCount={remainingUsers.length}
getKey={(pill) => pill.key}
renderItem={(pill) => pill.content}
+ trailingContent={
+ <Popover
+ open={isMetadataEditorOpen}
+ onOpenChange={handleMetadataEditorOpenChange}
+ >
+ <PopoverTrigger asChild>
+ <ModernSessionHeaderPill
+ variant="button"
+ ariaLabel="Add metadata JSONPath"
+ >
+ <Plus className="h-3 w-3" />
+ </ModernSessionHeaderPill>
+ </PopoverTrigger>
+ {isMetadataEditorOpen ? (
+ <MetadataJsonPathEditorContent
+ metadataJsonPaths={metadataJsonPaths}
+ onClose={() => handleMetadataEditorOpenChange(false)}
+ onSave={saveMetadataJsonPath}
+ />
+ ) : null}
+ </Popover>
+ }
renderOverflow={({ hiddenItems: hiddenPills, overflowItemCount }) => {
const normalizedSearch = search.trim().toLocaleLowerCase();
const filteredPills = normalizedSearch
diff --git a/web/src/components/session/ModernSessionHeaderPill.tsx b/web/src/components/session/ModernSessionHeaderPill.tsx
index ade924c466..4c44276457 100644
--- a/web/src/components/session/ModernSessionHeaderPill.tsx
+++ b/web/src/components/session/ModernSessionHeaderPill.tsx
@@ -14,7 +14,6 @@ type ModernSessionHeaderPillProps = {
| {
variant: "link";
href: ComponentPropsWithoutRef<typeof Link>["href"];
- title: string;
}
| ({
variant: "button";
@@ -49,7 +48,6 @@ export function ModernSessionHeaderPill(props: ModernSessionHeaderPillProps) {
return (
<Link
href={props.href}
- title={props.title}
data-session-header-pill="true"
className={`${PILL_CLASS_NAME} hover:border-link hover:text-link group max-w-[280px] min-w-0 gap-1.5`}
>
diff --git a/web/src/components/session/SessionMetadataJsonPathControl.tsx b/web/src/components/session/SessionMetadataJsonPathControl.tsx
new file mode 100644
index 0000000000..486a94bb72
--- /dev/null
+++ b/web/src/components/session/SessionMetadataJsonPathControl.tsx
@@ -0,0 +1,183 @@
+import { type FilterState } from "@langfuse/shared";
+import {
+ hashKey,
+ type QueryCache,
+ useQueryClient,
+} from "@tanstack/react-query";
+import { getQueryKey } from "@trpc/react-query";
+import {
+ type ReactNode,
+ useCallback,
+ useState,
+ useSyncExternalStore,
+} from "react";
+
+import {
+ metadataJsonPathsStorageKey,
+ parseStoredMetadataJsonPaths,
+ type SessionMetadataJsonPathState,
+} from "@/src/components/session/sessionMetadataJsonPath";
+import { getVisibleSessionObservations } from "@/src/components/session/sessionVisibleObservations";
+import useLocalStorage from "@/src/components/useLocalStorage";
+import { api, type RouterOutputs } from "@/src/utils/api";
+
+type SessionMetadataJsonPathControlProps = {
+ projectId: string;
+ sessionId: string;
+ traces:
+ | { state: "loading" }
+ | { state: "loaded"; data: readonly { id: string }[] };
+ filterState: FilterState;
+ children: (state: SessionMetadataJsonPathState) => ReactNode;
+};
+
+const EMPTY_STORED_PATHS: readonly string[] = [];
+const EMPTY_CACHE_SNAPSHOT = () => "";
+
+const getQueryCacheSnapshot = (
+ queryCache: QueryCache,
+ queryHashSignature: string,
+) => {
+ if (!queryHashSignature) return "";
+
+ return queryHashSignature
+ .split("\u0000")
+ .map((queryHash) => {
+ const state = queryCache.get(queryHash)?.state;
+ return state
+ ? `${state.status}:${state.fetchStatus}:${state.dataUpdateCount}:${state.errorUpdateCount}`
+ : "missing";
+ })
+ .join("\u0000");
+};
+
+const useQueryCacheEntries = (queryHashSignature: string) => {
+ const queryCache = useQueryClient().getQueryCache();
+ const subscribe = useCallback(
+ (onStoreChange: () => void) => {
+ const queryHashes = new Set(queryHashSignature.split("\u0000"));
+ return queryCache.subscribe((event) => {
+ if (queryHashes.has(event.query.queryHash)) onStoreChange();
+ });
+ },
+ [queryCache, queryHashSignature],
+ );
+ const getSnapshot = useCallback(
+ () => getQueryCacheSnapshot(queryCache, queryHashSignature),
+ [queryCache, queryHashSignature],
+ );
+
+ useSyncExternalStore(subscribe, getSnapshot, EMPTY_CACHE_SNAPSHOT);
+ return queryCache;
+};
+
+const getFirstCachedObservation = ({
+ queryCache,
+ queryHashes,
+ traceIds,
+}: {
+ queryCache: QueryCache;
+ queryHashes: readonly string[];
+ traceIds: readonly string[];
+}) => {
+ type Observation =
+ RouterOutputs["sessions"]["observationsForTraceFromEvents"][number];
+ type ObservationResponse =
+ | RouterOutputs["sessions"]["observationsForTraceFromEvents"]
+ | {
+ observations?: RouterOutputs["sessions"]["observationsForTraceFromEvents"];
+ };
+ let firstObservation: Observation | undefined;
+ let hasResolvedQuery = false;
+ let isFetching = false;
+ let isError = false;
+
+ queryHashes.forEach((queryHash, index) => {
+ const queryState = queryCache.get(queryHash)?.state;
+ const response = queryState?.data as ObservationResponse | undefined;
+ hasResolvedQuery ||= response !== undefined;
+ isFetching ||= queryState?.fetchStatus === "fetching";
+ isError ||= queryState?.status === "error";
+ firstObservation ??= getVisibleSessionObservations(
+ response,
+ traceIds[index] ?? "",
+ ).visibleObservations?.[0];
+ });
+
+ return { firstObservation, hasResolvedQuery, isFetching, isError };
+};
+
+export function SessionMetadataJsonPathControl({
+ projectId,
+ sessionId,
+ traces,
+ filterState,
+ children,
+}: SessionMetadataJsonPathControlProps) {
+ const [rawPaths, setRawPaths] = useLocalStorage<unknown>(
+ metadataJsonPathsStorageKey(projectId),
+ EMPTY_STORED_PATHS,
+ );
+ const paths = parseStoredMetadataJsonPaths(rawPaths);
+ const [isEditorOpen, setIsEditorOpen] = useState(false);
+ const shouldObserveMetadata = paths.length > 0 || isEditorOpen;
+ const loadedTraces = traces.state === "loaded" ? traces.data : [];
+ const observationInputs = shouldObserveMetadata
+ ? loadedTraces.map((trace) => ({
+ projectId,
+ sessionId,
+ traceId: trace.id,
+ filter: filterState,
+ }))
+ : [];
+ const observationQueryHashes = observationInputs.map((input) =>
+ hashKey(
+ getQueryKey(api.sessions.observationsForTraceFromEvents, input, "query"),
+ ),
+ );
+ const queryCache = useQueryCacheEntries(
+ observationQueryHashes.join("\u0000"),
+ );
+ const { firstObservation, hasResolvedQuery, isFetching, isError } =
+ getFirstCachedObservation({
+ queryCache,
+ queryHashes: observationQueryHashes,
+ traceIds: loadedTraces.map((trace) => trace.id),
+ });
+ const source = !shouldObserveMetadata
+ ? ({ state: "idle" } as const)
+ : traces.state === "loading"
+ ? ({ state: "loading" } as const)
+ : firstObservation
+ ? ({
+ state: "ready",
+ metadata: firstObservation.metadata,
+ metadataTruncated: firstObservation.metadataTruncated,
+ } as const)
+ : isFetching
+ ? ({ state: "loading" } as const)
+ : isError && !hasResolvedQuery
+ ? ({ state: "error" } as const)
+ : hasResolvedQuery || loadedTraces.length === 0
+ ? ({ state: "empty" } as const)
+ : ({ state: "loading" } as const);
+
+ return children({
+ paths,
+ source,
+ onEditorOpenChange: setIsEditorOpen,
+ onSave: (path) => {
+ setRawPaths((current: unknown) => {
+ const currentPaths = parseStoredMetadataJsonPaths(current);
+ return currentPaths.includes(path)
+ ? currentPaths
+ : [...currentPaths, path];
+ });
+ },
+ onRemove: (path) => {
+ setRawPaths((current: unknown) =>
+ parseStoredMetadataJsonPaths(current).filter((item) => item !== path),
+ );
+ },
+ });
+}
diff --git a/web/src/components/session/TraceEventsRow.tsx b/web/src/components/session/TraceEventsRow.tsx
index 84be5c82b8..33ca1f2ffa 100644
--- a/web/src/components/session/TraceEventsRow.tsx
+++ b/web/src/components/session/TraceEventsRow.tsx
@@ -9,9 +9,12 @@ import { deepParseJson, type FilterState } from "@langfuse/shared";
import { SessionObservationIO } from "@/src/components/session/SessionObservationIO";
import { api } from "@/src/utils/api";
import { FilterX } from "lucide-react";
-import isEqual from "lodash/isEqual";
import { SESSION_DETAIL_VIEW_TRIGGER_ID } from "@/src/components/session/session-detail-presets";
import { SessionTraceActionButtons } from "@/src/components/session/SessionTraceActionButtons";
+import {
+ getVisibleSessionObservations,
+ SESSION_CARD_OBSERVATIONS_NOTICE_COUNT,
+} from "@/src/components/session/sessionVisibleObservations";
import {
hasRenderableConversationMessages,
type IOPreviewContentMode,
@@ -21,20 +24,6 @@ import {
export type TraceEventsSurface = "card" | "modern";
-// Display copy for the per-card observation cap; the authoritative limit is
-// SESSION_OBSERVATIONS_PER_TRACE_LIMIT in the sessions router (LFE-10958).
-const SESSION_CARD_OBSERVATIONS_NOTICE_COUNT = 50;
-
-const hasContent = (value: unknown): boolean =>
- value !== null &&
- value !== undefined &&
- !(typeof value === "string" && value.trim() === "");
-
-const observationHasIO = (observation: {
- input?: unknown;
- output?: unknown;
-}): boolean => hasContent(observation.input) || hasContent(observation.output);
-
type SessionObservation =
RouterOutputs["sessions"]["observationsForTraceFromEvents"][number];
@@ -302,10 +291,6 @@ export const TraceEventsRow = React.memo(
| ObservationsResponse
| { observations?: ObservationsResponse }
| undefined;
- const observations = Array.isArray(observationsData)
- ? observationsData
- : (observationsData?.observations ?? 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).
@@ -315,62 +300,12 @@ export const TraceEventsRow = React.memo(
},
[openPeek, trace],
);
- const { visibleObservations, hasMoreObservations } = React.useMemo(() => {
- const all = observations;
- if (!all)
- return {
- visibleObservations: undefined,
- hasMoreObservations: false,
- };
- const syntheticTraceRowId = `t-${trace.id}`;
- // The server returns up to SESSION_CARD_OBSERVATIONS_NOTICE_COUNT + 1
- // real observations; the extra (+1) row is the "more exist" sentinel.
- // Show only the first NOTICE_COUNT real observations, keeping the
- // synthetic trace-level row wherever it sits (it never consumes a slot).
- let realCount = 0;
- let realShown = 0;
- const page: typeof all = [];
- for (const observation of all) {
- if (observation.id === syntheticTraceRowId) {
- page.push(observation);
- continue;
- }
- realCount++;
- if (realShown >= SESSION_CARD_OBSERVATIONS_NOTICE_COUNT) continue;
- page.push(observation);
- realShown++;
- }
- const hasMoreObservations =
- realCount > SESSION_CARD_OBSERVATIONS_NOTICE_COUNT;
-
- const syntheticRow = page.find(
- (observation) => observation.id === syntheticTraceRowId,
- );
- const realObservations = page.filter(
- (observation) => observation.id !== syntheticTraceRowId,
- );
- // I/O can be server-truncated to a preview head (LFE-10958), so equal
- // heads alone don't prove equal payloads — the true lengths must match
- // too (equal head + equal full length ≈ identical content).
- const syntheticRowIsRedundant =
- !syntheticRow ||
- !observationHasIO(syntheticRow) ||
- realObservations.some(
- (observation) =>
- (hasContent(syntheticRow.input) &&
- isEqual(observation.input, syntheticRow.input) &&
- observation.inputLength === syntheticRow.inputLength) ||
- (hasContent(syntheticRow.output) &&
- isEqual(observation.output, syntheticRow.output) &&
- observation.outputLength === syntheticRow.outputLength),
- );
- const visibleObservations = !syntheticRowIsRedundant
- ? page
- : realObservations.length > 0
- ? realObservations
- : page;
- return { visibleObservations, hasMoreObservations };
- }, [observations, trace.id]);
+ const visibleObservationState = React.useMemo(
+ () => getVisibleSessionObservations(observationsData, trace.id),
+ [observationsData, trace.id],
+ );
+ const { visibleObservations, hasMoreObservations } =
+ visibleObservationState;
const Frame = surface === "card" ? Card : "div";
const showTracePanel = surface === "card" && !hideTracePanel;
@@ -488,8 +423,7 @@ export const TraceEventsRow = React.memo(
</p>
)}
</div>
- ) : observations &&
- observations.length === 0 &&
+ ) : visibleObservations?.length === 0 &&
filterState.length === 0 ? (
// No filter and the trace genuinely has no observations.
<div className="text-muted-foreground p-2 text-xs">
diff --git a/web/src/components/session/index.tsx b/web/src/components/session/index.tsx
index 4ff03aa08d..418dcdceb5 100644
--- a/web/src/components/session/index.tsx
+++ b/web/src/components/session/index.tsx
@@ -86,6 +86,7 @@ import { SessionVirtualizedRow } from "@/src/components/session/SessionVirtualiz
import { createSessionDetailStore } from "@/src/components/session/sessionDetailStore";
import { ModernSession } from "@/src/components/session/ModernSession";
import { ModernSessionHeader } from "@/src/components/session/ModernSessionHeader";
+import { SessionMetadataJsonPathControl } from "@/src/components/session/SessionMetadataJsonPathControl";
import { DropdownMenuTrigger } from "@/src/components/ui/dropdown-menu";
import { ModernSessionHeaderActionsController } from "@/src/components/session/ModernSessionHeaderActionsController";
import { ModernSessionFilterControls } from "@/src/components/session/ModernSessionFilterControls";
@@ -1381,6 +1382,9 @@ const LoadedSessionEventsPage: React.FC<{
getItemKey: (index) => traces?.[index]?.id ?? index,
});
const virtualItems = virtualizer.getVirtualItems();
+ const modernSessionTraces = isTracesSuccess
+ ? ({ state: "loaded", data: traces ?? [] } as const)
+ : ({ state: "loading" } as const);
return (
<SessionDetailStoreProvider store={sessionDetailStore}>
@@ -1561,22 +1565,29 @@ const LoadedSessionEventsPage: React.FC<{
}
>
{isModernSessionEnabled ? (
- <ModernSessionHeader
+ <SessionMetadataJsonPathControl
+ key={`${projectId}:${sessionId}`}
projectId={projectId}
- countTraces={session.countTraces}
- traces={
- isTracesSuccess
- ? { state: "loaded", data: traces ?? [] }
- : { state: "loading" }
- }
- tokensIn={session.inputUsage}
- tokensOut={session.outputUsage}
- totalTokens={session.totalTokens}
- totalCost={session.totalCost ?? 0}
- environment={session.environment ?? null}
- users={session.users ?? []}
- scores={session.scores}
- />
+ sessionId={sessionId}
+ traces={modernSessionTraces}
+ filterState={visibleFilterState}
+ >
+ {(metadataJsonPaths) => (
+ <ModernSessionHeader
+ projectId={projectId}
+ countTraces={session.countTraces}
+ traces={modernSessionTraces}
+ tokensIn={session.inputUsage}
+ tokensOut={session.outputUsage}
+ totalTokens={session.totalTokens}
+ totalCost={session.totalCost ?? 0}
+ environment={session.environment ?? null}
+ users={session.users ?? []}
+ metadataJsonPaths={metadataJsonPaths}
+ scores={session.scores}
+ />
+ )}
+ </SessionMetadataJsonPathControl>
) : null}
{!isModernSessionEnabled && hasSessionControls ? (
<SessionControlsBar
diff --git a/web/src/components/session/sessionMetadataJsonPath.clienttest.ts b/web/src/components/session/sessionMetadataJsonPath.clienttest.ts
new file mode 100644
index 0000000000..6463508746
--- /dev/null
+++ b/web/src/components/session/sessionMetadataJsonPath.clienttest.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ getMetadataJsonPathLabel,
+ metadataJsonPathsStorageKey,
+ parseStoredMetadataJsonPaths,
+ resolveMetadataJsonPath,
+} from "@/src/components/session/sessionMetadataJsonPath";
+import { getVisibleSessionObservations } from "@/src/components/session/sessionVisibleObservations";
+
+const observation = ({
+ id,
+ input = null,
+ output = null,
+}: {
+ id: string;
+ input?: unknown;
+ output?: unknown;
+}) => ({
+ id,
+ metadata: {},
+ input,
+ output,
+ inputLength: typeof input === "string" ? input.length : 0,
+ outputLength: typeof output === "string" ? output.length : 0,
+});
+
+describe("session metadata JSONPaths", () => {
+ it("stores multiple paths and resolves their display values", () => {
+ expect(metadataJsonPathsStorageKey("project-1")).toBe(
+ "modern-session:metadata-jsonpaths:v1:project-1",
+ );
+ expect(
+ parseStoredMetadataJsonPaths([" $.email ", "$.cloud_region", "$.email"]),
+ ).toEqual(["$.email", "$.cloud_region"]);
+ expect(parseStoredMetadataJsonPaths({ paths: ["$.email"] })).toEqual([]);
+
+ const metadata = JSON.stringify({
+ email: "[email protected]",
+ admin: false,
+ tags: ["production", "agent"],
+ });
+ expect(resolveMetadataJsonPath(metadata, "$.email")).toEqual({
+ state: "match",
+ displayValue: "[email protected]",
+ });
+ expect(resolveMetadataJsonPath(metadata, "$.admin")).toEqual({
+ state: "match",
+ displayValue: "false",
+ });
+ expect(resolveMetadataJsonPath(metadata, "$.tags")).toEqual({
+ state: "match",
+ displayValue: '["production","agent"]',
+ });
+ expect(resolveMetadataJsonPath({}, "email")).toEqual({
+ state: "invalid",
+ message: "JSONPath must start with $.",
+ });
+ expect(resolveMetadataJsonPath({}, "$.email")).toEqual({
+ state: "no-match",
+ });
+ expect(getMetadataJsonPathLabel("$.langfuse_user_email")).toBe(
+ "langfuse_user_email",
+ );
+ expect(getMetadataJsonPathLabel("$['user.email']")).toBe("user.email");
+ expect(getMetadataJsonPathLabel("$[*]")).toBe("$[*]");
+ });
+
+ it("normalizes the row response and returns exactly its rendered observations", () => {
+ const synthetic = observation({ id: "t-trace-1", input: "trace input" });
+ const firstReal = observation({ id: "observation-1", output: "answer" });
+ expect(
+ getVisibleSessionObservations(
+ { observations: [synthetic, firstReal] },
+ "trace-1",
+ ).visibleObservations,
+ ).toEqual([synthetic, firstReal]);
+
+ const capped = Array.from({ length: 51 }, (_, index) =>
+ observation({ id: `observation-${index + 1}` }),
+ );
+ expect(getVisibleSessionObservations(capped, "trace-1")).toEqual({
+ visibleObservations: capped.slice(0, 50),
+ hasMoreObservations: true,
+ });
+ expect(getVisibleSessionObservations(undefined, "trace-1")).toEqual({
+ visibleObservations: undefined,
+ hasMoreObservations: false,
+ });
+ });
+});
diff --git a/web/src/components/session/sessionMetadataJsonPath.ts b/web/src/components/session/sessionMetadataJsonPath.ts
new file mode 100644
index 0000000000..d5f812c337
--- /dev/null
+++ b/web/src/components/session/sessionMetadataJsonPath.ts
@@ -0,0 +1,86 @@
+import { evaluateJsonPath } from "@langfuse/shared";
+import { z } from "zod";
+
+const JSON_PATH_MAX_LENGTH = 1_000;
+
+const storedMetadataJsonPathsSchema = z
+ .array(z.string().trim().min(1).max(JSON_PATH_MAX_LENGTH).startsWith("$"))
+ .transform((paths) => [...new Set(paths)]);
+
+export type StoredMetadataJsonPaths = z.infer<
+ typeof storedMetadataJsonPathsSchema
+>;
+
+export type FirstVisibleObservationMetadataState =
+ | { state: "idle" }
+ | { state: "loading" }
+ | { state: "error" }
+ | { state: "empty" }
+ | { state: "ready"; metadata: unknown; metadataTruncated: boolean };
+
+export type SessionMetadataJsonPathState = {
+ paths: readonly string[];
+ source: FirstVisibleObservationMetadataState;
+ onEditorOpenChange: (open: boolean) => void;
+ onSave: (path: string) => void;
+ onRemove: (path: string) => void;
+};
+
+export const metadataJsonPathsStorageKey = (projectId: string) =>
+ `modern-session:metadata-jsonpaths:v1:${projectId}`;
+
+export const parseStoredMetadataJsonPaths = (
+ raw: unknown,
+): StoredMetadataJsonPaths => {
+ const result = storedMetadataJsonPathsSchema.safeParse(raw);
+ return result.success ? result.data : [];
+};
+
+export type MetadataJsonPathResolution =
+ | { state: "match"; displayValue: string }
+ | { state: "no-match" }
+ | { state: "invalid"; message: string };
+
+export const resolveMetadataJsonPath = (
+ metadata: unknown,
+ rawPath: string,
+): MetadataJsonPathResolution => {
+ const path = rawPath.trim();
+ if (!path.startsWith("$")) {
+ return { state: "invalid", message: "JSONPath must start with $." };
+ }
+ if (path.length > JSON_PATH_MAX_LENGTH) {
+ return {
+ state: "invalid",
+ message: `JSONPath must be at most ${JSON_PATH_MAX_LENGTH} characters.`,
+ };
+ }
+
+ try {
+ const value = evaluateJsonPath(metadata ?? {}, path);
+ if (value === undefined) return { state: "no-match" };
+
+ const displayValue =
+ typeof value === "string"
+ ? value
+ : typeof value === "number" || typeof value === "boolean"
+ ? String(value)
+ : value === null
+ ? "null"
+ : (JSON.stringify(value) ?? String(value));
+ return { state: "match", displayValue };
+ } catch (error) {
+ return {
+ state: "invalid",
+ message: error instanceof Error ? error.message : "Invalid JSONPath.",
+ };
+ }
+};
+
+export const getMetadataJsonPathLabel = (path: string): string => {
+ const dotProperty = path.match(/\.([A-Za-z_$][\w$]*)$/)?.[1];
+ if (dotProperty) return dotProperty;
+
+ const bracketProperty = path.match(/\[['"]([^'"]+)['"]\]$/)?.[1];
+ return bracketProperty ?? path;
+};
diff --git a/web/src/components/session/sessionVisibleObservations.ts b/web/src/components/session/sessionVisibleObservations.ts
new file mode 100644
index 0000000000..ca21c2c8aa
--- /dev/null
+++ b/web/src/components/session/sessionVisibleObservations.ts
@@ -0,0 +1,87 @@
+import isEqual from "lodash/isEqual";
+
+// Display copy for the per-card observation cap; the authoritative limit is
+// SESSION_OBSERVATIONS_PER_TRACE_LIMIT in the sessions router.
+export const SESSION_CARD_OBSERVATIONS_NOTICE_COUNT = 50;
+
+export type SessionObservationVisibilityFields = {
+ id: string;
+ input: unknown;
+ output: unknown;
+ inputLength: number;
+ outputLength: number;
+};
+
+const hasContent = (value: unknown): boolean =>
+ value !== null &&
+ value !== undefined &&
+ !(typeof value === "string" && value.trim() === "");
+
+const observationHasIO = (
+ observation: Pick<SessionObservationVisibilityFields, "input" | "output">,
+): boolean => hasContent(observation.input) || hasContent(observation.output);
+
+export const getVisibleSessionObservations = <
+ TObservation extends SessionObservationVisibilityFields,
+>(
+ response:
+ | readonly TObservation[]
+ | { observations?: readonly TObservation[] }
+ | undefined,
+ traceId: string,
+): {
+ visibleObservations: readonly TObservation[] | undefined;
+ hasMoreObservations: boolean;
+} => {
+ const observations = Array.isArray(response)
+ ? response
+ : (response as { observations?: readonly TObservation[] } | undefined)
+ ?.observations;
+ if (!observations) {
+ return { visibleObservations: undefined, hasMoreObservations: false };
+ }
+
+ const syntheticTraceRowId = `t-${traceId}`;
+ let realCount = 0;
+ let realShown = 0;
+ const page: TObservation[] = [];
+
+ for (const observation of observations) {
+ if (observation.id === syntheticTraceRowId) {
+ page.push(observation);
+ continue;
+ }
+ realCount++;
+ if (realShown >= SESSION_CARD_OBSERVATIONS_NOTICE_COUNT) continue;
+ page.push(observation);
+ realShown++;
+ }
+
+ const syntheticRow = page.find(
+ (observation) => observation.id === syntheticTraceRowId,
+ );
+ const realObservations = page.filter(
+ (observation) => observation.id !== syntheticTraceRowId,
+ );
+ const syntheticRowIsRedundant =
+ !syntheticRow ||
+ !observationHasIO(syntheticRow) ||
+ realObservations.some(
+ (observation) =>
+ (hasContent(syntheticRow.input) &&
+ isEqual(observation.input, syntheticRow.input) &&
+ observation.inputLength === syntheticRow.inputLength) ||
+ (hasContent(syntheticRow.output) &&
+ isEqual(observation.output, syntheticRow.output) &&
+ observation.outputLength === syntheticRow.outputLength),
+ );
+
+ return {
+ visibleObservations: !syntheticRowIsRedundant
+ ? page
+ : realObservations.length > 0
+ ? realObservations
+ : page,
+ hasMoreObservations: realCount > SESSION_CARD_OBSERVATIONS_NOTICE_COUNT,
+ };
+};
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index 43c2c1b0c4..61d154ee75 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -148,6 +148,7 @@ export const events = {
"truncated_observation_download_click",
"inline_tools_toggled",
"system_prompt_toggled",
+ "metadata_jsonpath_config_changed",
],
eval_config: [
"new_form_submit",