@@ -156,7 +174,7 @@ export function AgentTracesSection({
>
← Back to traces
-
);
}
@@ -183,7 +201,7 @@ export function AgentTracesSection({
onStatusChange={setStatus}
>
{timeControls && (
diff --git a/ui/litellm-dashboard/src/components/view_logs/TraceView/TracePreview.tsx b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracePreview.tsx
new file mode 100644
index 00000000000..c4fd04602ac
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracePreview.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import { cn } from "@/lib/cva.config";
+
+import previewTrace from "./previewTrace.json";
+import { SpanIcon } from "./SpanIcon";
+import type { SpanType } from "./traceTypes";
+import { fmtMs } from "./traceUtils";
+
+interface PreviewRow {
+ id: string;
+ name: string;
+ type: SpanType;
+ model: string | null;
+ depth: number;
+ start_offset_ms: number;
+ duration_ms: number;
+ error: boolean;
+}
+
+const preview = previewTrace as {
+ name: string;
+ input_preview: string;
+ span_count: number;
+ duration_ms: number;
+ rows: PreviewRow[];
+};
+
+export function TracePreview() {
+ const total = preview.duration_ms;
+ return (
+
+
+ );
+}
diff --git a/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.test.tsx b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.test.tsx
index 4f42180d409..027870ab1ae 100644
--- a/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.test.tsx
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/TracingSetupCard.test.tsx
@@ -1,39 +1,98 @@
-import { render, screen } from "@testing-library/react";
+import { screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
-import { describe, expect, it, vi } from "vitest";
-import { chooseSelectOption } from "@/../tests/test-utils";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { chooseSelectOption, renderWithProviders } from "@/../tests/test-utils";
import { copyToClipboard } from "@/utils/dataUtils";
-import { codingAgentPrompt, tracingEnvSnippet, TracingSetupCard } from "./TracingSetupCard";
+import { agentTraceCall, apiClient, sendOtlpTraceCall } from "../../networking";
+import {
+ codingAgentCommand,
+ codingAgentPrompt,
+ maskSecret,
+ TRACING_KEY_REQUEST,
+ tracingEnvSnippet,
+ TracingSetupCard,
+} from "./TracingSetupCard";
+import type { Trace } from "./traceTypes";
-vi.mock("../../networking", () => ({ getProxyBaseUrl: () => "http://proxy.test/" }));
+vi.mock("../../networking", () => ({
+ getProxyBaseUrl: () => "http://proxy.test/",
+ sendOtlpTraceCall: vi.fn(),
+ agentTraceCall: vi.fn(),
+ apiClient: { post: vi.fn() },
+}));
vi.mock("@/utils/dataUtils", () => ({ copyToClipboard: vi.fn().mockResolvedValue(true) }));
+const SECRET = "sk-abcdefghijklmnopWXYZ";
+
+const renderCard = (
+ props: {
+ detail?: string | null;
+ connected?: boolean;
+ onCheck?: () => void;
+ readOnly?: boolean;
+ canMintTracingKey?: boolean;
+ } = {},
+) => {
+ const onOpenTrace = vi.fn();
+ renderWithProviders(
+
+
+
+ {preview.rows.map((row) => (
+
+
+
+ ))}
+
+
+
+
+
+
+
+ {fmtMs(row.duration_ms)}
+
+ {code}
+ {display}
);
@@ -198,10 +287,12 @@ function LineTabs
@@ -213,12 +304,13 @@ function LineTabs({
aria-selected={value === option}
onClick={() => onChange(option)}
className={cn(
- "-mb-px h-9 border-b-2 text-[12.5px]",
+ "-mb-px inline-flex h-9 items-center gap-1.5 border-b-2 text-[12.5px]",
value === option
? "border-foreground text-foreground"
: "border-transparent text-muted-foreground hover:text-foreground",
)}
>
+ {logos?.[option] && 
}
{option}
))}
@@ -226,7 +318,7 @@ function LineTabs({
);
}
-function Step({ title, children }: { title: string; children: React.ReactNode }) {
+function Step({ title, children }: { title: React.ReactNode; children: React.ReactNode }) {
return (
, string> = {
+ idle: "Send a test trace",
+ sending: "Sending…",
+ waiting: "Waiting for it to arrive…",
+ failed: "Send a test trace",
+};
+
+const delay = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
+
+async function waitForTrace(accessToken: string, traceId: string): Promise {
+ for (let attempt = 0; attempt < SAMPLE_TRACE_POLL_ATTEMPTS; attempt++) {
+ try {
+ return (await agentTraceCall(accessToken, traceId)).summary;
+ } catch {
+ await delay(SAMPLE_TRACE_POLL_MS);
+ }
+ }
+ return null;
+}
+
+function SendTestTrace({
+ accessToken,
+ onOpenTrace,
+}: {
+ accessToken: string;
+ onOpenTrace: (trace: TraceSummary) => void;
+}) {
+ const [state, setState] = useState({ kind: "idle" });
+ const send = async () => {
+ setState({ kind: "sending" });
+ const sample = sampleTraceExport(Date.now());
+ try {
+ await sendOtlpTraceCall(accessToken, sample.body);
+ } catch {
+ setState({ kind: "failed", message: "Could not send the test trace." });
+ return;
+ }
+ setState({ kind: "waiting" });
+ const trace = await waitForTrace(accessToken, sample.traceId);
+ setState(
+ trace
+ ? { kind: "ready", trace }
+ : { kind: "failed", message: "Sent, but it has not shown up yet. Check again in a moment." },
+ );
+ };
+ if (state.kind === "ready") {
+ return (
+
+
+
+
+ );
+}
+
+const CODING_AGENT_LOGOS: Record = {
+ "Claude Code": anthropicLogo.src,
+ Codex: openaiLogo.src,
+};
+
function setupTitle(enabled: boolean, connected: boolean) {
if (!enabled) return "Enable tracing";
return connected ? "Connect another agent" : "Connect your agent";
}
-export function TracingSetupCard({
- detail,
- connected = false,
+interface ConnectAgentProps {
+ accessToken: string;
+ onOpenTrace: (trace: TraceSummary) => void;
+ connected: boolean;
+ checked: boolean;
+ checking: boolean;
+ onCheck: () => void;
+ readOnly: boolean;
+ canMintTracingKey: boolean;
+}
+
+function EnableTracing({ checked, checking, onCheck }: { checked: boolean; checking: boolean; onCheck: () => void }) {
+ return (
+ <>
+
+ config.yaml} />
+
+ ClickHouse and proxy setup
+
+
+ {checked && !checking && (
+ ("pip");
- const [copied, setCopied] = useState(false);
- const [checked, setChecked] = useState(false);
+ const [codingAgent, setCodingAgent] = useState("Claude Code");
+ const [tracingKey, setTracingKey] = useState(null);
const guide = FRAMEWORKS.find((f) => f.id === framework) ?? FRAMEWORKS[0];
const packages = installPackages(guide);
- const install = installer === "pip" ? `pip install -U ${packages}` : `uv add ${packages}`;
+ const install = guide.typescript ? `npm install ${packages}` : PY_INSTALL[installer](packages);
+ const quickstart = guide.quickstart.replace("{PROXY}", proxyUrl);
+ return (
+ <>
+ {!readOnly && (
+
+
+ )}
+
+
+ {canMintTracingKey && !readOnly ? (
+
+
+
+ Let 
Claude Code or
+ 
Codex connect it
+
+ }
+ >
+
+
+
+
+ )}
+
+ );
+}
+
+export function TracingSetupCard({
+ detail,
+ accessToken,
+ onOpenTrace,
+ connected = false,
+ onCheck,
+ checking = false,
+ readOnly = false,
+ canMintTracingKey = false,
+}: {
+ detail: string | null;
+ accessToken: string;
+ onOpenTrace: (trace: TraceSummary) => void;
+ connected?: boolean;
+ onCheck?: () => void;
+ checking?: boolean;
+ readOnly?: boolean;
+ canMintTracingKey?: boolean;
+}) {
+ const [checked, setChecked] = useState(false);
const enabled = detail === null;
- const copyPrompt = async () => {
- if (await copyToClipboard(codingAgentPrompt(proxyUrl, guide))) {
- setCopied(true);
- window.setTimeout(() => setCopied(false), COPIED_RESET_MS);
- }
- };
const check = () => {
setChecked(true);
onCheck?.();
};
return (
-
{title}
@@ -235,6 +327,86 @@ function Step({ title, children }: { title: string; children: React.ReactNode }) ); } +type SendState = + | { kind: "idle" } + | { kind: "sending" } + | { kind: "waiting" } + | { kind: "ready"; trace: TraceSummary } + | { kind: "failed"; message: string }; + +const SEND_LABEL: Record
+
+ Test trace received
+
+
+
+ );
+ }
+ const busy = state.kind === "sending" || state.kind === "waiting";
+ return (
+
+
+ {state.kind === "failed" &&
+ );
+}
+
function TraceReceipt({
connected,
checked,
@@ -273,159 +445,367 @@ function TraceReceipt({
);
}
+function TracingKey({
+ accessToken,
+ tracingKey,
+ onCreated,
+}: {
+ accessToken: string;
+ tracingKey: string | null;
+ onCreated: (key: string) => void;
+}) {
+ const [creating, setCreating] = useState(false);
+ const [error, setError] = useState("");
+ const create = async () => {
+ setCreating(true);
+ setError("");
+ try {
+ const result = await apiClient.post<{ key?: string }>("/key/generate", {
+ accessToken,
+ body: TRACING_KEY_REQUEST,
+ });
+ if (!result.key) throw new Error("The proxy did not return the new key");
+ onCreated(result.key);
+ } catch (cause) {
+ setError(cause instanceof Error ? cause.message : "Could not create a key");
+ } finally {
+ setCreating(false);
+ }
+ };
+ if (tracingKey) {
+ return (
+ {state.message}
} +
+ Your tracing key} />
+
+ );
+ }
+ return (
+ + Hidden for safety. Copy copies the full key, and the environment step below includes it. This key can only + send traces, so your agent still needs its own key for model calls. Manage it under Virtual Keys as + "Agent tracing". +
+
+
+ Or use any existing LiteLLM virtual key.
+ {error &&
+ );
+}
+
+function EndpointValue({ value }: { value: string }) {
+ const [copied, setCopied] = useState(false);
+ const copy = async () => {
+ if (await copyToClipboard(value)) {
+ setCopied(true);
+ window.setTimeout(() => setCopied(false), COPIED_RESET_MS);
+ }
+ };
+ return (
+
+ );
+}
+
+function Endpoints({ proxyUrl }: { proxyUrl: string }) {
+ return (
+ {error}
} +
+ 
+ OpenTelemetry (OTEL) endpoints
+
+ + Point any OpenTelemetry exporter here. The framework guides below set these for you. +
+-
+ {otlpEndpoints(proxyUrl).map(([label, value, copyable]) => (
+
- {label} +
-
+ {copyable ?
: {value}} +
+
+
+ ))}
+ + Set your ClickHouse writer and read-only reader URLs, add this to config.yaml, then restart the proxy. Ask + your proxy administrator if you don’t manage this deployment. +
++ Tracing is still unavailable. Check that the configuration was applied to this proxy and it has restarted. +
+ )} + + + ); +} + +function ConnectAgent({ + accessToken, + onOpenTrace, + connected, + checked, + checking, onCheck, - checking = false, -}: { - detail: string | null; - connected?: boolean; - onCheck?: () => void; - checking?: boolean; -}) { + readOnly, + canMintTracingKey, +}: ConnectAgentProps) { const proxyUrl = getProxyBaseUrl().replace(/\/$/, ""); const [framework, setFramework] = useState(FRAMEWORKS[0].id); const [installer, setInstaller] = useState+ Send a small sample run (an agent, an LLM call and a tool call) to confirm tracing works end to end. +
+
+
+
+
+
+ + Use any LiteLLM virtual key you already have, or ask a proxy admin for one. +
+ )} ++ Run this in your agent’s project. It starts your coding agent with the setup task and reads the key from + LITELLM_API_KEY. +
+
+
+ npm
+ ) : (
+
+
+ Shell}
+ />
+
+
+ {guide.typescript ? "my_agent.ts" : "my_agent.py"}}
+ />
+
+
+
+ Set up manually
++ Replace the example model with a model configured on your proxy. +
+
+ Shell} />
+
+ + Example run (sample data, not your runs) +
+
- [];
+}
+
+export function sampleTraceExport(nowMs: number): { traceId: string; body: object } {
+ const traceId = randomHexId(16);
+ const agentId = randomHexId(8);
+ const question = "What is the weather in San Francisco?";
+ const answer = "It is 18°C and sunny in San Francisco.";
+ const spans: readonly (SampleSpan & { id: string })[] = [
+ {
+ id: agentId,
+ name: "weather_agent",
+ parent: null,
+ startMs: 0,
+ endMs: 2400,
+ attributes: [
+ str("gen_ai.operation.name", "invoke_agent"),
+ str("gen_ai.agent.name", "weather_agent"),
+ str("gen_ai.input.messages", messages("user", question)),
+ str("gen_ai.output.messages", messages("assistant", answer)),
+ ],
+ },
+ {
+ id: randomHexId(8),
+ name: "chat sample-model",
+ parent: agentId,
+ startMs: 100,
+ endMs: 1500,
+ attributes: [
+ str("gen_ai.operation.name", "chat"),
+ str("gen_ai.agent.name", "weather_agent"),
+ str("gen_ai.request.model", "sample-model"),
+ str("gen_ai.input.messages", messages("user", question)),
+ str("gen_ai.output.messages", messages("assistant", "Calling get_weather(city=San Francisco)")),
+ ],
+ },
+ {
+ id: randomHexId(8),
+ name: "get_weather",
+ parent: agentId,
+ startMs: 1600,
+ endMs: 2300,
+ attributes: [
+ str("gen_ai.operation.name", "execute_tool"),
+ str("gen_ai.agent.name", "weather_agent"),
+ str("gen_ai.tool.call.arguments", JSON.stringify({ city: "San Francisco" })),
+ str("gen_ai.tool.call.result", JSON.stringify({ temp_c: 18, sky: "sunny" })),
+ ],
+ },
+ ];
+ const startNs = BigInt(nowMs - 2400) * NS_PER_MS;
+ const toNs = (ms: number): string => String(startNs + BigInt(ms) * NS_PER_MS);
+ return {
+ traceId,
+ body: {
+ resourceSpans: [
+ {
+ resource: { attributes: [str("service.name", SAMPLE_TRACE_SERVICE)] },
+ scopeSpans: [
+ {
+ scope: { name: "litellm-ui-sample" },
+ spans: spans.map((s) => ({
+ traceId,
+ spanId: s.id,
+ ...(s.parent ? { parentSpanId: s.parent } : {}),
+ name: s.name,
+ kind: 1,
+ startTimeUnixNano: toNs(s.startMs),
+ endTimeUnixNano: toNs(s.endMs),
+ attributes: s.attributes,
+ status: { code: 1 },
+ })),
+ },
+ ],
+ },
+ ],
+ },
+ };
+}
{setupTitle(enabled, connected)}
+
+
- config.yaml} />
-
- ClickHouse and proxy setup
-
-
- {checked && !checking && (
-
-
-
);
diff --git a/ui/litellm-dashboard/src/components/view_logs/TraceView/previewTrace.json b/ui/litellm-dashboard/src/components/view_logs/TraceView/previewTrace.json
new file mode 100644
index 00000000000..7da2a5b454d
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/previewTrace.json
@@ -0,0 +1,98 @@
+{
+ "name": "deep_research_agent",
+ "input_preview": "Should we store OTEL agent spans in ClickHouse or Postgres at 50k spans/sec?",
+ "span_count": 126,
+ "duration_ms": 51385,
+ "rows": [
+ {
+ "id": "5e79f3b5b504985e",
+ "name": "deep_research_agent",
+ "type": "agent",
+ "model": null,
+ "depth": 0,
+ "start_offset_ms": 0,
+ "duration_ms": 51385.4,
+ "error": false
+ },
+ {
+ "id": "83451f3235847f6c",
+ "name": "model",
+ "type": "chain",
+ "model": null,
+ "depth": 1,
+ "start_offset_ms": 1,
+ "duration_ms": 9518.2,
+ "error": false
+ },
+ {
+ "id": "8a6a1c31940d07af",
+ "name": "ChatOpenAI",
+ "type": "llm",
+ "model": "claude-sonnet-4-5",
+ "depth": 2,
+ "start_offset_ms": 6,
+ "duration_ms": 9510.8,
+ "error": false
+ },
+ {
+ "id": "f6fdd164d528fee5",
+ "name": "tools",
+ "type": "chain",
+ "model": null,
+ "depth": 1,
+ "start_offset_ms": 9520,
+ "duration_ms": 2.7,
+ "error": false
+ },
+ {
+ "id": "1526d46d48d29a09",
+ "name": "write_file",
+ "type": "tool",
+ "model": null,
+ "depth": 2,
+ "start_offset_ms": 9521,
+ "duration_ms": 0.6,
+ "error": false
+ },
+ {
+ "id": "2697122e295d91b6",
+ "name": "tools",
+ "type": "chain",
+ "model": null,
+ "depth": 1,
+ "start_offset_ms": 9523,
+ "duration_ms": 35177.7,
+ "error": false
+ },
+ {
+ "id": "b2fb3a8f5a2fce01",
+ "name": "task",
+ "type": "tool",
+ "model": null,
+ "depth": 2,
+ "start_offset_ms": 9524,
+ "duration_ms": 35176.1,
+ "error": false
+ },
+ {
+ "id": "81499b492fd93f85",
+ "name": "researcher",
+ "type": "agent",
+ "model": null,
+ "depth": 3,
+ "start_offset_ms": 9524,
+ "duration_ms": 35175.3,
+ "error": false
+ },
+ {
+ "id": "64a2c760897f3310",
+ "name": "model",
+ "type": "chain",
+ "model": null,
+ "depth": 4,
+ "start_offset_ms": 9526,
+ "duration_ms": 6071.3,
+ "error": false
+ }
+ ]
+}
diff --git a/ui/litellm-dashboard/src/components/view_logs/TraceView/sampleTrace.test.ts b/ui/litellm-dashboard/src/components/view_logs/TraceView/sampleTrace.test.ts
new file mode 100644
index 00000000000..56ac75a5ea7
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/sampleTrace.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import { SAMPLE_TRACE_SERVICE, sampleTraceExport } from "./sampleTrace";
+
+interface ExportedSpan {
+ traceId: string;
+ spanId: string;
+ parentSpanId?: string;
+ startTimeUnixNano: string;
+ endTimeUnixNano: string;
+ attributes: { key: string; value: { stringValue: string } }[];
+}
+
+const spansOf = (body: object): ExportedSpan[] =>
+ (body as { resourceSpans: { scopeSpans: { spans: ExportedSpan[] }[] }[] }).resourceSpans[0].scopeSpans[0].spans;
+
+const operation = (span: ExportedSpan) =>
+ span.attributes.find((a) => a.key === "gen_ai.operation.name")?.value.stringValue;
+
+describe("sampleTraceExport", () => {
+ it("uses OTLP/JSON hex ids and returns the trace id the spans carry", () => {
+ const { traceId, body } = sampleTraceExport(Date.now());
+ const spans = spansOf(body);
+ expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+ for (const span of spans) {
+ expect(span.traceId).toBe(traceId);
+ expect(span.spanId).toMatch(/^[0-9a-f]{16}$/);
+ }
+ });
+
+ it("nests an LLM call and a tool call under one root agent", () => {
+ const spans = spansOf(sampleTraceExport(Date.now()).body);
+ const roots = spans.filter((s) => !s.parentSpanId);
+ expect(roots).toHaveLength(1);
+ expect(operation(roots[0])).toBe("invoke_agent");
+ const children = spans.filter((s) => s.parentSpanId === roots[0].spanId);
+ expect(children.map(operation).sort()).toEqual(["chat", "execute_tool"]);
+ });
+
+ it("ends at the given time and tags the sample service", () => {
+ const now = 1_790_000_000_000;
+ const { body } = sampleTraceExport(now);
+ const root = spansOf(body).find((s) => !s.parentSpanId)!;
+ expect(BigInt(root.endTimeUnixNano)).toBe(BigInt(now) * BigInt(1_000_000));
+ expect(BigInt(root.startTimeUnixNano)).toBeLessThan(BigInt(root.endTimeUnixNano));
+ expect(JSON.stringify(body)).toContain(SAMPLE_TRACE_SERVICE);
+ });
+});
diff --git a/ui/litellm-dashboard/src/components/view_logs/TraceView/sampleTrace.ts b/ui/litellm-dashboard/src/components/view_logs/TraceView/sampleTrace.ts
new file mode 100644
index 00000000000..6dc6f3262b7
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/view_logs/TraceView/sampleTrace.ts
@@ -0,0 +1,95 @@
+const NS_PER_MS = BigInt(1_000_000);
+
+export const SAMPLE_TRACE_SERVICE = "litellm-sample-agent";
+
+const randomHexId = (bytes: number): string =>
+ Array.from(crypto.getRandomValues(new Uint8Array(bytes)), (b) => b.toString(16).padStart(2, "0")).join("");
+
+const str = (key: string, value: string) => ({ key, value: { stringValue: value } });
+
+const messages = (role: string, content: string): string => JSON.stringify([{ role, content }]);
+
+interface SampleSpan {
+ name: string;
+ parent: string | null;
+ startMs: number;
+ endMs: number;
+ attributes: ReturnType
+
{setupTitle(enabled, connected)}
+ + Docs + +{enabled ? "Send your agent’s runs to LiteLLM to see its inputs, outputs, and tool calls." : "Tracing needs ClickHouse and a small update to your LiteLLM proxy configuration."}
- {enabled && }
+ {enabled &&
- Set your ClickHouse writer and read-only reader URLs, add this to config.yaml, then restart the proxy. Ask - your proxy administrator if you don’t manage this deployment. -
-- Tracing is still unavailable. Check that the configuration was applied to this proxy and it has restarted. -
- )} - - + {enabled ? ( +
-
-
-
- - Paste the setup prompt into Claude Code or Codex in your agent’s project. It uses your existing LiteLLM - key from the environment. -
- -
-
-
-
- Shell} />
-
-
- my_agent.py}
- />
-
-
- Set up manually
-- Replace the example model with a model configured on your proxy. -
-
- Shell} />
-
-
- 
-
-
+ See an example trace
-Example only. These are not your agent’s runs.
-