observer.md

Observer

The observer module monitors the health and status of the OpenViking server and its internal components.

When to use which method

• isHealthy() — Quick liveness check; use in application startup or periodic health monitoring.
• system() — Get detailed component breakdown and errors; use for monitoring dashboards or troubleshooting degraded performance.
• Component-specific methods (queue(), vikingdb(), vlm()) — Debug specific services; useful when one subsystem may be unhealthy.

Methods

isHealthy()

Returns true if all server components are healthy. Use as a quick liveness check.

if (!await huscarl.observer.isHealthy()) {
  console.warn("Server is degraded");
}

system()

Returns an aggregated health report across all components, including per-component statuses and any active errors.

const status = await huscarl.observer.system();
console.log("Healthy:", status.isHealthy);
console.log("Errors:", status.errors);

for (const [name, component] of Object.entries(status.components)) {
  console.log(`  ${name}: ${component.status} (healthy: ${component.isHealthy})`);
}

queue()

Returns the health and status of the background processing queue (embedding and indexing jobs).

const queue = await huscarl.observer.queue();
console.log(queue.status);  // e.g. "idle", "processing"

vikingdb()

Returns the health and status of the vector database component.

const db = await huscarl.observer.vikingdb();
console.log(db.isHealthy, db.hasErrors);

vlm()

Returns the health and status of the vision-language model (VLM) component.

const vlm = await huscarl.observer.vlm();
console.log(vlm.isHealthy);

ComponentStatus shape

All component methods return the same shape:

interface ComponentStatus {
  name:      string;
  isHealthy: boolean;
  hasErrors: boolean;
  status:    string;   // human-readable status string from the server
}