Runtime Observability

July 25, 2026 ยท View on GitHub

The Observer API reports immediate status for queues, the vector database, models, locks, retrieval, and the file system.

Observer API

The observer API provides detailed component-level monitoring.

observer.queue

1. API Implementation Overview

Get queue system status (embedding and semantic processing queues). Shows pending, in-progress, completed, and error counts for each queue.

Code Entry Points:

  • openviking/server/routers/observer.py:observer_queue - HTTP route
  • openviking/service/debug_service.py:ObserverService.queue - Core implementation
  • openviking/storage/observers/queue_observer.py - Queue observer

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/queue

curl -X GET http://localhost:1933/api/v1/observer/queue \
  -H "X-API-Key: your-key"

Python SDK

print(client.observer.queue())
# Output:
# [queue] (healthy)
# Queue                 Pending  In Progress  Processed  Errors  Total
# Embedding             0        0            10         0       10
# Semantic              0        0            10         0       10
# TOTAL                 0        0            20         0       20

TypeScript SDK

console.log(await client.queueStatus());

Go SDK

status, err := client.QueueStatus(ctx)
if err != nil {
    return err
}
fmt.Println(status["is_healthy"])

CLI

ov observer queue

Response Example

{
  "status": "ok",
  "result": {
    "name": "queue",
    "is_healthy": true,
    "has_errors": false,
    "status": "Queue                 Pending  In Progress  Processed  Errors  Total\nEmbedding             0        0            10         0       10\nSemantic              0        0            10         0       10\nTOTAL                 0        0            20         0       20"
  },
  "time": 0.1
}

observer.vikingdb

1. API Implementation Overview

Get VikingDB status (collections, indexes, vector counts).

Code Entry Points:

  • openviking/server/routers/observer.py:observer_vikingdb - HTTP route
  • openviking/service/debug_service.py:ObserverService.vikingdb - Core implementation
  • openviking/storage/observers/vikingdb_observer.py - VikingDB observer
  • crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/vikingdb

curl -X GET http://localhost:1933/api/v1/observer/vikingdb \
  -H "X-API-Key: your-key"

Python SDK

print(client.observer.vikingdb())
# Output:
# [vikingdb] (healthy)
# Collection  Index Count  Vector Count  Status
# context     1            55            OK
# TOTAL       1            55

# Access specific attributes
print(client.observer.vikingdb().is_healthy)  # True
print(client.observer.vikingdb().status)      # Status table string

TypeScript SDK

console.log(await client.vikingDBStatus());

Go SDK

status, err := client.VikingDBStatus(ctx)
if err != nil {
    return err
}
fmt.Println(status["is_healthy"])

CLI

ov observer vikingdb

Response Example

{
  "status": "ok",
  "result": {
    "name": "vikingdb",
    "is_healthy": true,
    "has_errors": false,
    "status": "Collection  Index Count  Vector Count  Status\ncontext     1            55            OK\nTOTAL       1            55"
  },
  "time": 0.1
}

observer.models

1. API Implementation Overview

Get aggregated model subsystem status (VLM, embedding, rerank). Checks if each model provider is healthy and available.

Code Entry Points:

  • openviking/server/routers/observer.py:observer_models - HTTP route
  • openviking/service/debug_service.py:ObserverService.models - Core implementation
  • openviking/storage/observers/models_observer.py - Models observer
  • crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/models

curl -X GET http://localhost:1933/api/v1/observer/models \
  -H "X-API-Key: your-key"

Python SDK

print(client.observer.models())
# Output:
# [models] (healthy)
# provider_model         healthy  detail
# dense_embedding        yes      ...
# rerank                 yes      ...
# vlm                    yes      ...

TypeScript SDK

console.log(await client.modelsStatus());

Go SDK

status, err := client.ModelsStatus(ctx)
if err != nil {
    return err
}
fmt.Println(status["is_healthy"])

CLI

ov observer models

Response Example

{
  "status": "ok",
  "result": {
    "name": "models",
    "is_healthy": true,
    "has_errors": false,
    "status": "provider_model         healthy  detail\ndense_embedding        yes      ...\nrerank                 yes      ...\nvlm                    yes      ..."
  },
  "time": 0.1
}

observer.lock

1. API Implementation Overview

Get distributed lock system status.

Code Entry Points:

  • openviking/server/routers/observer.py:observer_lock - HTTP route
  • openviking/service/debug_service.py:ObserverService.lock - Core implementation
  • openviking/storage/observers/lock_observer.py - Lock observer
  • crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/lock

curl -X GET http://localhost:1933/api/v1/observer/lock \
  -H "X-API-Key: your-key"

The public SDKs and CLI do not currently expose a lock-specific observer method. Use the HTTP API for this component; ov observer system includes it in the aggregate status.

Response Example

{
  "status": "ok",
  "result": {
    "name": "lock",
    "is_healthy": true,
    "has_errors": false,
    "status": "..."
  },
  "time": 0.1
}

observer.retrieval

1. API Implementation Overview

Get retrieval quality metrics.

Code Entry Points:

  • openviking/server/routers/observer.py:observer_retrieval - HTTP route
  • openviking/service/debug_service.py:ObserverService.retrieval - Core implementation
  • openviking/storage/observers/retrieval_observer.py - Retrieval observer
  • crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/retrieval

curl -X GET http://localhost:1933/api/v1/observer/retrieval \
  -H "X-API-Key: your-key"

CLI

ov observer retrieval

Response Example

{
  "status": "ok",
  "result": {
    "name": "retrieval",
    "is_healthy": true,
    "has_errors": false,
    "status": "..."
  },
  "time": 0.1
}

observer.filesystem

1. API Implementation Overview

Get filesystem operation metrics.

Code Entry Points:

  • openviking/server/routers/observer.py:observer_filesystem - HTTP route
  • openviking/service/debug_service.py:ObserverService.filesystem - Core implementation
  • openviking/storage/observers/filesystem_observer.py - Filesystem observer
  • crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/filesystem

curl -X GET http://localhost:1933/api/v1/observer/filesystem \
  -H "X-API-Key: your-key"

CLI

ov observer filesystem

Response Example

{
  "status": "ok",
  "result": {
    "name": "filesystem",
    "is_healthy": true,
    "has_errors": false,
    "status": "..."
  },
  "time": 0.1
}

observer.system

1. API Implementation Overview

Get overall system status, including all components (queue, vikingdb, models, lock, retrieval).

Code Entry Points:

  • openviking/server/routers/observer.py:observer_system - HTTP route
  • openviking/service/debug_service.py:ObserverService.system - Core implementation
  • crates/ov_cli/src/commands/observer.rs - CLI command

2. Interface and Parameters

No parameters.

3. Usage Examples

HTTP API

GET /api/v1/observer/system

curl -X GET http://localhost:1933/api/v1/observer/system \
  -H "X-API-Key: your-key"

Python SDK

print(client.observer.system())
# Output:
# [queue] (healthy)
# ...
#
# [vikingdb] (healthy)
# ...
#
# [models] (healthy)
# ...
#
# [system] (healthy)

TypeScript SDK

console.log(await client.getStatus());

Go SDK

status, err := client.GetStatus(ctx)
if err != nil {
    return err
}
fmt.Println(status["is_healthy"])

CLI

ov observer system

Response Example

{
  "status": "ok",
  "result": {
    "is_healthy": true,
    "errors": [],
    "components": {
      "queue": {
        "name": "queue",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "vikingdb": {
        "name": "vikingdb",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "models": {
        "name": "models",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "lock": {
        "name": "lock",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      },
      "retrieval": {
        "name": "retrieval",
        "is_healthy": true,
        "has_errors": false,
        "status": "..."
      }
    }
  },
  "time": 0.1
}