feat(dashboard): add a log viewer for the observability proxy

Tenants could not read their applications' logs without Grafana. The
viewer reads VictoriaLogs' native responses through a proxy root: a
time-ranged LogsQL query, pod and container pickers fed by the stream
field values of the same scope, and a follow mode over the streamed
tail.

The picked pod and container wrap the filter part of the query rather
than being appended to it, because AND binds tighter than OR in LogsQL
and the user's pipes must still run last. A dropped tail resumes from
the last line's _time; the proxy may replay lines around that point,
so the client drops replayed lines it already holds by stream and
time, which VictoriaLogs does not guarantee unique and is therefore
applied only at the resume boundary. Follow keeps the newest 1000
lines so a chatty stream cannot grow the page without bound.

Assisted-by: LLM
Signed-off-by: ZverGuy <maximbel2003@gmail.com>
This commit is contained in:
ZverGuy committed 2026-11-04 05:34:01 +07:00
1 parent 063e56ede5
commit b5a0ab8de6
7 files changed
+563 -1

No files matched your search

@@ -0,0 +1,111 @@
import { describe, it, expect, vi } from "vitest"
import { screen, waitFor } from "@testing-library/react"
import userEvent from "@testing-library/user-event"
import { K8sClient } from "@cozystack/k8s-client"
import { renderWithK8sProvider } from "../../test-utils/render.tsx"
import { LogsView } from "./LogsView.tsx"
const app = { namespace: "tenant-a", plural: "postgreses", name: "db" }
const ROOT = "/apis/apps.cozystack.io/v1alpha1/namespaces/tenant-a/postgreses/db/log/"
const line = (time: string, msg: string, pod = "db-0") =>
JSON.stringify({ _time: time, _msg: msg, _stream_id: "s", kubernetes_pod_name: pod, kubernetes_container_name: "postgres" })
function clientWith(handler: (endpoint: string, params: URLSearchParams) => Response | Promise<Response>) {
const client = new K8sClient()
const raw = vi.spyOn(client, "raw").mockImplementation(async (path) => {
const url = new URL(path, "http://x")
return handler(url.pathname, url.searchParams)
})
return { client, raw }
}
const values = (...v: string[]) => Response.json({ values: v.map((value) => ({ value, hits: 1 })) })
function defaultHandler(endpoint: string, params?: URLSearchParams): Response | Promise<Response> {
if (endpoint.endsWith("stream_field_values")) {
return params?.get("field") === "kubernetes_pod_name" ? values("db-0", "db-1") : values("postgres")
}
if (endpoint.endsWith("query")) return new Response(`${line("2026-11-04T10:00:01Z", "ready to accept connections")}\n`)
return new Promise(() => {})
}
describe("LogsView", () => {
it("shows recent lines from the application root", async () => {
const { client, raw } = clientWith(defaultHandler)
renderWithK8sProvider(<LogsView scope={app} />, { client })
expect(await screen.findByText("ready to accept connections")).toBeInTheDocument()
const call = raw.mock.calls.find(([p]) => p.includes("select/logsql/query?"))!
expect(call[0].startsWith(`${ROOT}select/logsql/query?`)).toBe(true)
const params = new URL(call[0], "http://x").searchParams
expect(params.get("query")).toBe("*")
expect(params.get("limit")).toBe("500")
})
it("narrows to the picked pod with a stream filter", async () => {
const { client, raw } = clientWith(defaultHandler)
renderWithK8sProvider(<LogsView scope={app} />, { client })
await screen.findByRole("option", { name: "db-1" })
await userEvent.selectOptions(screen.getByLabelText("Pod"), "db-1")
await waitFor(() =>
expect(
raw.mock.calls.some(([p]) => new URL(p, "http://x").searchParams.get("query") === '{kubernetes_pod_name="db-1"} (*)'),
).toBe(true),
)
})
it("applies the LogsQL filter on submit", async () => {
const { client, raw } = clientWith(defaultHandler)
renderWithK8sProvider(<LogsView scope={app} />, { client })
await userEvent.type(screen.getByLabelText("LogsQL filter"), "error{Enter}")
await waitFor(() =>
expect(raw.mock.calls.some(([p]) => p.includes("select/logsql/query?") && p.includes("query=error"))).toBe(true),
)
})
it("follows the live tail when Follow is pressed", async () => {
const { client } = clientWith((endpoint, params) =>
endpoint.endsWith("tail") ? new Response(`${line("2026-11-04T10:00:05Z", "checkpoint complete")}\n`) : defaultHandler(endpoint, params),
)
renderWithK8sProvider(<LogsView scope={app} />, { client })
await userEvent.click(screen.getByRole("button", { name: "Follow" }))
expect(await screen.findByText("checkpoint complete")).toBeInTheDocument()
expect(screen.getByRole("button", { name: "Follow" })).toHaveAttribute("aria-pressed", "true")
})
it("renders a cluster without the proxy as not available", async () => {
const { client } = clientWith(() => new Response("404 page not found", { status: 404 }))
renderWithK8sProvider(<LogsView scope={app} />, { client })
expect(await screen.findByText("Logs are not available on this cluster.")).toBeInTheDocument()
expect(screen.queryByLabelText("LogsQL filter")).toBeNull()
})
it("keeps the controls and explains a rejected query", async () => {
const { client } = clientWith((endpoint, params) =>
endpoint.endsWith("query") ? new Response("cannot parse query", { status: 400 }) : defaultHandler(endpoint, params),
)
renderWithK8sProvider(<LogsView scope={app} />, { client })
expect(await screen.findByText("cannot parse query")).toBeInTheDocument()
expect(screen.getByLabelText("LogsQL filter")).toBeInTheDocument()
})
it("names the source pod and container of each line", async () => {
const { client } = clientWith(defaultHandler)
renderWithK8sProvider(<LogsView scope={{ namespace: "tenant-a" }} />, { client })
expect(await screen.findByText("db-0/postgres")).toBeInTheDocument()
})
})
@@ -0,0 +1,152 @@
import { useEffect, useRef, useState } from "react"
import { useQuery } from "@tanstack/react-query"
import { useK8sClient } from "@cozystack/k8s-client"
import { Button, Spinner } from "@cozystack/ui"
import {
CONTAINER_FIELD,
LOG_RANGES,
POD_FIELD,
buildLogsQuery,
type LogRangeKey,
} from "../../lib/observability/logs.ts"
import {
fieldValues,
isScopeWide,
logsRoot,
queryLogs,
type LogEntry,
type ObservabilityScope,
} from "../../lib/observability/proxy.ts"
import { useLogTail } from "../../lib/observability/use-log-tail.ts"
import { ProxyNotice } from "./ProxyNotice.tsx"
import { RangePicker } from "./RangePicker.tsx"
const HISTORY_LIMIT = 500
const FOLLOW_CAP = 1000
function windowFor(range: LogRangeKey) {
const end = Date.now()
return { start: new Date(end - LOG_RANGES[range] * 1000).toISOString(), end: new Date(end).toISOString() }
}
function Picker({ label, value, options, onChange }: { label: string; value: string; options: string[]; onChange: (v: string) => void }) {
return (
<label className="flex items-center gap-1.5 text-xs text-slate-600">
{label}
<select
aria-label={label}
value={value}
onChange={(e) => onChange(e.target.value)}
className="rounded-md border border-slate-200 bg-white px-2 py-1 text-xs text-slate-900"
>
<option value="">All</option>
{options.map((o) => (
<option key={o} value={o}>
{o}
</option>
))}
</select>
</label>
)
}
function LogLines({ entries, follow }: { entries: LogEntry[]; follow: boolean }) {
const ref = useRef<HTMLOListElement>(null)
useEffect(() => {
if (follow && ref.current) ref.current.scrollTop = ref.current.scrollHeight
}, [entries, follow])
if (entries.length === 0) return <p className="text-sm text-slate-500">No log lines for this range and filter.</p>
return (
<ol ref={ref} className="max-h-[60vh] overflow-auto rounded-md bg-slate-950 p-3 font-mono text-xs leading-5 text-slate-100">
{entries.map((e, i) => (
<li key={`${e._stream_id}-${e._time}-${i}`} className="whitespace-pre-wrap break-all">
<span className="text-slate-400">{new Date(e._time).toLocaleTimeString()}</span>{" "}
<span className="text-sky-300">{`${e[POD_FIELD] ?? ""}/${e[CONTAINER_FIELD] ?? ""}`}</span>{" "}
{e._msg}
</li>
))}
</ol>
)
}
export function LogsView({ scope }: { scope: ObservabilityScope }) {
const client = useK8sClient()
const root = logsRoot(scope)
const [range, setRange] = useState<LogRangeKey>("1h")
const [draft, setDraft] = useState("")
const [filter, setFilter] = useState("")
const [pod, setPod] = useState("")
const [container, setContainer] = useState("")
const [follow, setFollow] = useState(false)
const query = buildLogsQuery({ filter, pod, container })
const pickerQuery = (field: string, narrowTo?: string) => ({
queryKey: ["observability", "logs-fields", root, field, range, narrowTo ?? ""],
queryFn: ({ signal }: { signal: AbortSignal }) =>
fieldValues(client, root, {
field,
stream: true,
query: buildLogsQuery({ filter: "", pod: narrowTo }),
...windowFor(range),
}, signal),
retry: false,
})
const pods = useQuery(pickerQuery(POD_FIELD))
const containers = useQuery(pickerQuery(CONTAINER_FIELD, pod || undefined))
const history = useQuery({
queryKey: ["observability", "logs", root, query, range],
queryFn: ({ signal }) => queryLogs(client, root, { query, limit: HISTORY_LIMIT, ...windowFor(range) }, signal),
enabled: !follow,
retry: false,
})
const tail = useLogTail(root, query, follow, { cap: FOLLOW_CAP })
const wide = [pods.error, history.error, tail.error].find(isScopeWide)
if (wide) {
return (
<div className="p-6">
<ProxyNotice what="Logs" error={wide} />
</div>
)
}
const error = follow ? tail.error : history.error
const entries = follow ? tail.entries : (history.data ?? [])
return (
<div className="space-y-3 p-6">
<div className="flex flex-wrap items-center gap-3">
<form
className="flex min-w-64 flex-1"
onSubmit={(e) => {
e.preventDefault()
setFilter(draft)
}}
>
<input
aria-label="LogsQL filter"
value={draft}
onChange={(e) => setDraft(e.target.value)}
placeholder='LogsQL filter, e.g. error or "connection refused"'
className="w-full rounded-md border border-slate-200 px-2.5 py-1.5 font-mono text-xs"
/>
</form>
<Picker label="Pod" value={pod} options={pods.data ?? []} onChange={(v) => { setPod(v); setContainer("") }} />
<Picker label="Container" value={container} options={containers.data ?? []} onChange={setContainer} />
{!follow && <RangePicker options={Object.keys(LOG_RANGES) as LogRangeKey[]} value={range} onChange={setRange} />}
<Button variant={follow ? "default" : "outline"} size="sm" aria-pressed={follow} onClick={() => setFollow(!follow)}>
Follow
</Button>
</div>
{follow && (
<p className="text-xs text-slate-500">
{tail.state === "live" ? "Live" : tail.state === "reconnecting" ? "Reconnecting…" : "Connecting…"}
{` · newest ${FOLLOW_CAP} lines kept`}
</p>
)}
{error ? <ProxyNotice what="Logs" error={error} /> : null}
{!follow && history.isLoading ? <Spinner /> : <LogLines entries={entries} follow={follow} />}
</div>
)
}
@@ -0,0 +1,65 @@
import { describe, it, expect } from "vitest"
import { buildLogsQuery, compareTime, mergeTail } from "./logs.ts"
describe("buildLogsQuery", () => {
it("passes the filter through when nothing is picked", () => {
expect(buildLogsQuery({ filter: "error or warn" })).toBe("error or warn")
expect(buildLogsQuery({ filter: " " })).toBe("*")
})
it("ANDs the picked pod and container as a stream filter around the whole filter", () => {
expect(buildLogsQuery({ filter: "error or warn", pod: "db-0", container: "postgres" })).toBe(
'{kubernetes_pod_name="db-0",kubernetes_container_name="postgres"} (error or warn)',
)
})
it("keeps the user's pipes after the scoped filter", () => {
expect(buildLogsQuery({ filter: 'a or "x|y" | fields _msg', pod: "db-0" })).toBe(
'{kubernetes_pod_name="db-0"} (a or "x|y") | fields _msg',
)
})
it("escapes quotes in picked values", () => {
expect(buildLogsQuery({ filter: "", pod: 'a"b' })).toBe('{kubernetes_pod_name="a\\"b"} (*)')
})
})
describe("compareTime", () => {
it("orders RFC3339 times with differing fraction lengths", () => {
expect(compareTime("2026-11-04T10:00:01Z", "2026-11-04T10:00:01.1Z")).toBeLessThan(0)
expect(compareTime("2026-11-04T10:00:01.5Z", "2026-11-04T10:00:01.123Z")).toBeGreaterThan(0)
expect(compareTime("2026-11-04T10:00:01.10Z", "2026-11-04T10:00:01.1Z")).toBe(0)
})
})
const e = (time: string, msg: string, stream = "s1") => ({ _time: time, _msg: msg, _stream_id: stream })
describe("mergeTail", () => {
it("appends and keeps only the newest lines over the cap", () => {
const out = mergeTail([e("t1", "a"), e("t2", "b")], [e("t3", "c")], 2)
expect(out.map((x) => x._msg)).toEqual(["b", "c"])
})
it("drops replayed lines at or before the resume point", () => {
const buffer = [e("2026-01-01T00:00:01Z", "a"), e("2026-01-01T00:00:02Z", "b")]
const out = mergeTail(buffer, [e("2026-01-01T00:00:02Z", "b"), e("2026-01-01T00:00:03Z", "c")], 10, "2026-01-01T00:00:02Z")
expect(out.map((x) => x._msg)).toEqual(["a", "b", "c"])
})
it("keeps a line at the resume point from another stream", () => {
const buffer = [e("2026-01-01T00:00:02Z", "b", "s1")]
const out = mergeTail(buffer, [e("2026-01-01T00:00:02Z", "other", "s2")], 10, "2026-01-01T00:00:02Z")
expect(out).toHaveLength(2)
})
it("does not deduplicate outside a resume", () => {
const out = mergeTail([e("t1", "a")], [e("t1", "a")], 10)
expect(out).toHaveLength(2)
})
})
@@ -0,0 +1,73 @@
import type { LogEntry } from "./proxy.ts"
export const LOG_RANGES = {
"15m": 15 * 60,
"1h": 3600,
"6h": 6 * 3600,
"24h": 24 * 3600,
} as const
export type LogRangeKey = keyof typeof LOG_RANGES
export const POD_FIELD = "kubernetes_pod_name"
export const CONTAINER_FIELD = "kubernetes_container_name"
function quote(value: string): string {
return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
}
function splitAtFirstPipe(query: string): [string, string] {
let quoteChar = ""
for (let i = 0; i < query.length; i++) {
const c = query[i]
if (quoteChar) {
if (c === "\\") i++
else if (c === quoteChar) quoteChar = ""
} else if (c === '"' || c === "'" || c === "`") {
quoteChar = c
} else if (c === "|") {
return [query.slice(0, i), query.slice(i + 1)]
}
}
return [query, ""]
}
// The picker narrows the filter part only: AND binds tighter than OR in
// LogsQL, and the user's pipes must still run after the narrowed filter.
export function buildLogsQuery({ filter, pod, container }: { filter: string; pod?: string; container?: string }): string {
const trimmed = filter.trim() || "*"
const matchers = [
pod ? `${POD_FIELD}=${quote(pod)}` : "",
container ? `${CONTAINER_FIELD}=${quote(container)}` : "",
].filter(Boolean)
if (matchers.length === 0) return trimmed
const [head, pipes] = splitAtFirstPipe(trimmed)
const scoped = `{${matchers.join(",")}} (${head.trim() || "*"})`
return pipes.trim() ? `${scoped} | ${pipes.trim()}` : scoped
}
// VictoriaLogs trims trailing zeros from the fraction, so the strings do not sort lexically.
function padFraction(time: string): string {
const m = /^([^.Z]+)(?:\.(\d+))?Z$/.exec(time)
return m ? `${m[1]}.${(m[2] ?? "").padEnd(9, "0")}Z` : time
}
export function compareTime(a: string, b: string): number {
const x = padFraction(a)
const y = padFraction(b)
return x < y ? -1 : x > y ? 1 : 0
}
const entryKey = (e: LogEntry) => `${e._stream_id ?? ""}\u0000${e._time}`
// (_stream_id, _time) is not unique in VictoriaLogs, so dedup applies only to
// lines a resumed tail replays at or before the resume point.
export function mergeTail(buffer: LogEntry[], incoming: LogEntry[], cap: number, resumedFrom?: string): LogEntry[] {
let fresh = incoming
if (resumedFrom) {
const seen = new Set(buffer.map(entryKey))
fresh = incoming.filter((e) => compareTime(e._time, resumedFrom) > 0 || !seen.has(entryKey(e)))
}
const merged = buffer.concat(fresh)
return merged.length > cap ? merged.slice(merged.length - cap) : merged
}
@@ -1,4 +1,5 @@
import type { K8sClient } from "@cozystack/k8s-client"
import { compareTime } from "./logs.ts"
export type ObservabilityScope =
| { namespace: string }
@@ -160,7 +161,7 @@ export async function queryLogs(
): Promise<LogEntry[]> {
const res = await proxyGet(client, `${root}select/logsql/query`, { ...params }, signal)
const entries = (await res.text()).split("\n").map(parseLine).filter((e) => e !== null)
return entries.sort((a, b) => (a._time < b._time ? -1 : a._time > b._time ? 1 : 0))
return entries.sort((a, b) => compareTime(a._time, b._time))
}
export interface FieldValuesParams {
@@ -0,0 +1,65 @@
import { describe, it, expect, vi } from "vitest"
import { renderHook, waitFor } from "@testing-library/react"
import type { ReactNode } from "react"
import { K8sClient, K8sProvider } from "@cozystack/k8s-client"
import { useLogTail } from "./use-log-tail.ts"
const line = (time: string, msg: string) => JSON.stringify({ _time: time, _msg: msg, _stream_id: "s" })
function ndjson(...lines: string[]): Response {
return new Response(lines.map((l) => `${l}\n`).join(""))
}
function setup(...responses: Response[]) {
const client = new K8sClient()
const raw = vi.spyOn(client, "raw")
for (const r of responses) raw.mockResolvedValueOnce(r)
raw.mockImplementation(() => new Promise(() => {}))
const wrapper = ({ children }: { children: ReactNode }) => <K8sProvider client={client}>{children}</K8sProvider>
return { raw, wrapper }
}
const T1 = "2026-11-04T10:00:01Z"
const T2 = "2026-11-04T10:00:02Z"
const T3 = "2026-11-04T10:00:03Z"
describe("useLogTail", () => {
it("streams lines and resumes after a disconnect from the last _time without duplicates", async () => {
const { raw, wrapper } = setup(ndjson(line(T1, "a"), line(T2, "b")), ndjson(line(T2, "b"), line(T3, "c")))
const { result } = renderHook(() => useLogTail("/root/", "*", true, { cap: 100, retryDelayMs: 1 }), { wrapper })
await waitFor(() => expect(result.current.entries.map((e) => e._msg)).toEqual(["a", "b", "c"]))
expect(new URL(raw.mock.calls[0][0], "http://x").searchParams.has("since")).toBe(false)
expect(new URL(raw.mock.calls[1][0], "http://x").searchParams.get("since")).toBe(T2)
})
it("stops and reports an error the proxy will repeat on every retry", async () => {
const { raw, wrapper } = setup(new Response("", { status: 403 }))
const { result } = renderHook(() => useLogTail("/root/", "*", true, { cap: 100, retryDelayMs: 1 }), { wrapper })
await waitFor(() => expect(result.current.state).toBe("stopped"))
expect(result.current.error).toMatchObject({ kind: "forbidden" })
expect(raw).toHaveBeenCalledTimes(1)
})
it("does not connect while disabled", () => {
const { raw, wrapper } = setup()
renderHook(() => useLogTail("/root/", "*", false), { wrapper })
expect(raw).not.toHaveBeenCalled()
})
it("aborts the stream on unmount", async () => {
const { raw, wrapper } = setup()
const { unmount } = renderHook(() => useLogTail("/root/", "*", true), { wrapper })
await waitFor(() => expect(raw).toHaveBeenCalled())
unmount()
const init = raw.mock.calls[0][1] as RequestInit
expect(init.signal?.aborted).toBe(true)
})
})
@@ -0,0 +1,95 @@
import { useEffect, useState } from "react"
import { useK8sClient } from "@cozystack/k8s-client"
import { mergeTail } from "./logs.ts"
import { ProxyError, tailLogs, type LogEntry } from "./proxy.ts"
export type TailState = "connecting" | "live" | "reconnecting" | "stopped"
interface TailSnapshot {
key: string
entries: LogEntry[]
state: TailState
error: unknown
}
const FLUSH_MS = 100
const MAX_RETRY_MS = 30_000
const FATAL: ReadonlySet<string> = new Set(["bad-request", "unauthorized", "forbidden", "not-available", "limit"])
const sleep = (ms: number, signal: AbortSignal) =>
new Promise<void>((resolve) => {
const t = setTimeout(resolve, ms)
signal.addEventListener("abort", () => {
clearTimeout(t)
resolve()
})
})
export function useLogTail(
root: string,
query: string,
enabled: boolean,
{ cap = 1000, retryDelayMs = 2000 }: { cap?: number; retryDelayMs?: number } = {},
): Omit<TailSnapshot, "key"> {
const client = useK8sClient()
const key = `${root}\n${query}\n${enabled}`
const [snap, setSnap] = useState<TailSnapshot>({ key, entries: [], state: "connecting", error: null })
useEffect(() => {
if (!enabled) return
const controller = new AbortController()
const { signal } = controller
let pending: LogEntry[] = []
let timer: ReturnType<typeof setTimeout> | undefined
let resumedFrom: string | undefined
let lastTime: string | undefined
const update = (patch: Partial<TailSnapshot>, batch: LogEntry[] = [], from = resumedFrom) =>
setSnap((prev) => {
const base = prev.key === key ? prev : { key, entries: [], state: "connecting" as const, error: null }
return { ...base, ...patch, entries: batch.length ? mergeTail(base.entries, batch, cap, from) : base.entries }
})
const flush = () => {
clearTimeout(timer)
timer = undefined
if (pending.length === 0 || signal.aborted) return
const batch = pending
pending = []
update({ state: "live", error: null }, batch)
}
const run = async () => {
for (let attempt = 0; !signal.aborted; attempt++) {
resumedFrom = lastTime
try {
await tailLogs(client, root, { query, since: lastTime }, (entry) => {
attempt = 0
lastTime = entry._time
pending.push(entry)
timer ??= setTimeout(flush, FLUSH_MS)
}, signal)
flush()
} catch (err) {
flush()
if (signal.aborted) return
if (err instanceof ProxyError && FATAL.has(err.kind)) {
update({ state: "stopped", error: err })
return
}
update({ error: err })
}
if (signal.aborted) return
update({ state: "reconnecting" })
await sleep(Math.min(retryDelayMs * 2 ** attempt, MAX_RETRY_MS), signal)
}
}
void run()
return () => {
controller.abort()
clearTimeout(timer)
}
}, [client, root, query, enabled, key, cap, retryDelayMs])
const current = snap.key === key ? snap : { key, entries: [], state: "connecting" as const, error: null }
return { entries: current.entries, state: current.state, error: current.error }
}