πͺ’ 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
// Persisted per-project map of observed metadata paths β types, feeding the
// `metadata.<path>` key/value suggestions of every filter surface
// (fns/observedMetadata/metadataPaths.ts owns the analysis;
// hooks/useObservedMetadata.ts is the bridge).
//
// Same shape rationale as globalDateRangeStore: one global store holding a
// `Record<projectId, β¦>` map, so switching projects selects a different field
// instead of re-hydrating a per-project key (which could clobber another
// project's entry on an in-app switch). SSR gets a no-op storage.
//
// Growth is bounded on every axis (metadata is user-shaped and unbounded):
// keys per project and values per key/per project are capped on merge
// (MAX_PATHS_PER_PROJECT / MAX_VALUES_PER_KEY / MAX_VALUES_PER_PROJECT,
// drop-new when full), projects are capped with least-recently-updated
// eviction, and a merge that changes nothing skips the localStorage write
// entirely.
import { create } from "zustand";
import {
createJSONStorage,
persist,
type StateStorage,
} from "zustand/middleware";
import {
MAX_PATHS_PER_PROJECT,
MAX_VALUES_PER_KEY,
MAX_VALUES_PER_PROJECT,
mergePathType,
type StoredKeyInfo,
} from "@/src/fns/observedMetadata/metadataPaths";
const OBSERVED_METADATA_STORAGE_KEY = "langfuse-observed-metadata";
const MAX_PROJECTS = 20;
// A merge that changes nothing still refreshes the LRU stamp when it is older
// than this, so an actively-viewed project with a long-stable map outlives a
// stale one β without a localStorage write on every fetch.
const LRU_TOUCH_INTERVAL_MS = 24 * 60 * 60 * 1000;
// No-op storage on the server; the real localStorage is used on the client.
const noopStorage: StateStorage = {
getItem: () => null,
setItem: () => {},
removeItem: () => {},
};
// localStorage can throw (quota exceeded, Safari private mode). This map is a
// best-effort cache, so a failed write must not throw into the React effect
// that recorded the paths. console.warn, not console.error β error-level logs
// become Sentry events via the console integration.
const safeLocalStorage: StateStorage = {
getItem: (name) => {
try {
return window.localStorage.getItem(name);
} catch (error) {
console.warn("Error reading from local storage", error);
return null;
}
},
setItem: (name, value) => {
try {
window.localStorage.setItem(name, value);
} catch (error) {
console.warn("Error writing to local storage", error);
}
},
removeItem: (name) => {
try {
window.localStorage.removeItem(name);
} catch (error) {
console.warn("Error clearing local storage", error);
}
},
};
type ProjectMetadataPaths = {
/** Observed top-level key β stored type + sample values (see StoredKeyInfo). */
paths: Record<string, StoredKeyInfo>;
/** Last change (or daily activity refresh) β the project-eviction LRU key. */
updatedAt: number;
};
type ObservedMetadataState = {
byProject: Record<string, ProjectMetadataPaths>;
actions: {
/** Union newly observed paths into a project's map (see mergeIntoProject). */
recordPaths: (
projectId: string,
collected: ReadonlyMap<string, StoredKeyInfo>,
) => void;
};
};
/**
* Pure merge: union `collected` into the project's path map β merging types
* per key (mixed-absorbing) and unioning observed values (first-observed
* wins) β enforcing the per-project key cap, the per-key and per-project
* value caps, and the project-count cap (evict least-recently-updated).
* Returns null when nothing needs persisting. Exported for tests.
*/
export function mergeIntoProject(
byProject: Record<string, ProjectMetadataPaths>,
projectId: string,
collected: ReadonlyMap<string, StoredKeyInfo>,
now: number,
): Record<string, ProjectMetadataPaths> | null {
if (collected.size === 0) return null;
const prev = byProject[projectId];
const nextPaths: Record<string, StoredKeyInfo> = { ...(prev?.paths ?? {}) };
let count = Object.keys(nextPaths).length;
let totalValues = Object.values(nextPaths).reduce(
(sum, info) => sum + (info.values?.length ?? 0),
0,
);
let changed = false;
for (const [path, incoming] of collected) {
// Own-property lookup: a key shadowing an Object.prototype member
// ("toString", "constructor", β¦) must read as unseen, not as the
// inherited function β which would bypass the cap counter and crash or
// pin the type to "mixed" (`nextPaths["constructor"].values` resolves to
// the static Object.values).
const existing = Object.hasOwn(nextPaths, path)
? nextPaths[path]
: undefined;
if (existing === undefined) {
if (count >= MAX_PATHS_PER_PROJECT) continue;
count++;
}
const mergedType = mergePathType(existing?.type, incoming.type);
let mergedValues = existing?.values;
for (const v of incoming.values ?? []) {
if ((mergedValues?.length ?? 0) >= MAX_VALUES_PER_KEY) break;
if (totalValues >= MAX_VALUES_PER_PROJECT) break;
if (mergedValues?.includes(v)) continue;
mergedValues = [...(mergedValues ?? []), v];
totalValues++;
}
if (
existing === undefined ||
existing.type !== mergedType ||
mergedValues !== existing.values
) {
nextPaths[path] =
mergedValues === undefined
? { type: mergedType }
: { type: mergedType, values: mergedValues };
changed = true;
}
}
// `prev` exists whenever nothing changed: an absent project entry always
// changes on a non-empty `collected` (guarded above).
if (!changed && now - prev!.updatedAt < LRU_TOUCH_INTERVAL_MS) return null;
const next: Record<string, ProjectMetadataPaths> = {
...byProject,
[projectId]: {
paths: changed ? nextPaths : prev!.paths,
updatedAt: now,
},
};
const ids = Object.keys(next);
if (ids.length > MAX_PROJECTS) {
ids
.sort((a, b) => next[a]!.updatedAt - next[b]!.updatedAt)
.slice(0, ids.length - MAX_PROJECTS)
.forEach((id) => delete next[id]);
}
return next;
}
export const useObservedMetadataStore = create<ObservedMetadataState>()(
persist(
(set, get) => ({
byProject: {},
actions: {
recordPaths: (projectId, collected) => {
const next = mergeIntoProject(
get().byProject,
projectId,
collected,
Date.now(),
);
if (next !== null) set({ byProject: next });
},
},
}),
{
name: OBSERVED_METADATA_STORAGE_KEY,
version: 2,
// Hydrates from localStorage on the client; no-op during SSR.
storage: createJSONStorage(() =>
typeof window !== "undefined" ? safeLocalStorage : noopStorage,
),
// Persist only data, never the actions object.
partialize: (state) => ({ byProject: state.byProject }),
// On any schema change, start fresh β the map is a rebuildable cache.
migrate: () => ({ byProject: {} }),
},
),
);