Observability

Structured logging, performance measurement and error tracking, shipped as an installable library. Every log line carries the [mzizi] prefix so one grep finds everything across every service.

The prefix is [mzizi], not [mukoko]. Earlier documentation said [mukoko], and a grep pattern copied from it matches nothing. The prefix is set in lib/observability.ts in mzizi-dev/mzizi-registry.

Install

npx shadcn@latest add https://mzizi.dev/api/v1/ui/observability

`log`

A structured logger with four levels — debug, info, warn, error. Output is prefixed with [mzizi] and optionally scoped to a module.

log.info("Server started")
// [mzizi] INFO Server started

log.info("Component served", {
  module: "registry",
  data: { name: "button", fileCount: 1 },
})
// [mzizi:registry] INFO Component served { name: "button", fileCount: 1 }

log.error("Failed to fetch weather", {
  module: "weather",
  error: new Error("timeout"),
  traceId: "req-abc123",
})
// [mzizi:weather] ERROR Failed to fetch weather [trace:req-abc123] Error: timeout

`createLogger`

Binds a logger to a module name. Use it in any file that logs more than once.

const logger = createLogger("registry")

logger.info("Registry index served", { data: { itemCount: 575 } })
// [mzizi:registry] INFO Registry index served { itemCount: 575 }

logger.warn("File not found, skipping", { data: { filePath: "components/ui/missing.tsx" } })
// [mzizi:registry] WARN File not found, skipping { filePath: … }

`measure`

Times a synchronous or asynchronous function, logs the duration on success and on failure, and returns the function’s result.

const data = await measure("fetch-weather", async () => {
  const res = await fetch("https://example.com/weather")
  return res.json()
})
// [mzizi:perf] INFO fetch-weather completed in 142ms { duration: 142, label: "fetch-weather" }

const result = await measure("build-registry", () => buildAllComponents(), {
  module: "registry",
})
// [mzizi:registry] INFO build-registry completed in 3204ms { duration: 3204, … }

await measure("risky-operation", async () => {
  throw new Error("something broke")
})
// [mzizi:perf] ERROR risky-operation failed after 2ms { duration: 2, … } Error: something broke

Logging on failure as well as success is the part that matters. A timing helper that only records successes tells you your slow path is fast. The default module is perf; pass a module to scope it to your own.

`trackError`

Records an error without rethrowing it, wrapping a non-Error value automatically.

try {
  await riskyOperation()
} catch (error) {
  trackError(error, {
    module: "checkout",
    data: { action: "payment" },
  })
  return <FallbackView />
}

Be careful what you put in data. It goes to the log, so it is subject to whatever your log retention and access rules are — an identifier is usually enough, and the record it points at is usually not.

Error boundaries log automatically

SectionErrorBoundary calls the logger itself, so wrapping a section is the whole integration:

[mzizi:error-boundary] ERROR Section "Weather overview" crashed
  { section: "Weather overview", componentStack: [...] }

See error boundaries.

Grep patterns

Pattern	Finds
`grep "\[mzizi\]" logs`	Every unscoped log line
`grep "\[mzizi:registry\]" logs`	The registry module only
`grep "\[mzizi.*ERROR" logs`	Every error, scoped or not
`grep "\[mzizi:error-boundary\]" logs`	Boundary events
`grep "\[mzizi:perf\]" logs`	Performance measurements
`grep "\[trace:req-" logs`	Request traces

The square brackets need escaping in a basic grep — unescaped, [mzizi] is a character class matching a single letter, which matches almost every line in the file and looks like it worked.

Start here

The language

The research programme

The registry

Registry architecture

Foundations

Patterns

Blocks

Charts

Content style

Registry tooling

Observability

Install

`log`

`createLogger`

`measure`

`trackError`

Error boundaries log automatically

Grep patterns

​Install

​log

​createLogger

​measure

​trackError

​Error boundaries log automatically

​Grep patterns

Install

`log`

`createLogger`

`measure`

`trackError`

Error boundaries log automatically

Grep patterns