Operation Telemetry Reference

Operation telemetry lets you ask OpenViking to return a compact summary of what happened during a request, such as duration, token usage, vector retrieval activity, queue progress, and resource-processing stages.

Use it when you want to:

• debug a slow or unexpected request
• inspect token or retrieval behavior
• capture structured execution data in your own logs or observability pipeline

For the broader observability entry points, including health checks, ov tui, and OpenViking Console, see Observability & Diagnostics.

How it works

Telemetry is opt-in. OpenViking only returns a top-level telemetry object when you request it.

Typical response shape:

{
  "status": "ok",
  "result": {"...": "..."},
  "telemetry": {
    "id": "tm_xxx",
    "summary": {
      "operation": "search.find",
      "status": "ok",
      "duration_ms": 31.2,
      "tokens": {
        "total": 24,
        "llm": {
          "input": 12,
          "output": 6,
          "total": 18
        }
      },
      "vector": {
        "searches": 3,
        "scored": 26,
        "passed": 8,
        "returned": 5
      }
    }
  }
}

Notes:

• telemetry.id is an opaque correlation id
• telemetry.summary is the structured payload intended for users
• summary groups appear only when the operation produced them
• numeric 0 values are omitted from the response

Supported operations

HTTP API

Operation telemetry is currently available on these endpoints:

• POST /api/v1/search/find
• POST /api/v1/search/search
• POST /api/v1/resources/temp_upload
• POST /api/v1/resources
• POST /api/v1/skills
• POST /api/v1/sessions/{session_id}/commit

Python SDK

The same telemetry model is available from the Python clients for:

• add_resource(...)
• add_skill(...)
• find(...)
• search(...)
• commit_session(...)
• Session.commit(...)

Requesting telemetry

JSON APIs

For JSON request bodies, telemetry supports these forms:

{"telemetry": true}

{"telemetry": {"summary": true}}

true and {"summary": true} both request the same payload: telemetry.id + telemetry.summary.

The object form currently exposes the summary switch only.

If you do not want telemetry, either omit the field or set:

{"telemetry": false}

{"telemetry": {"summary": false}}

Multipart upload API

POST /api/v1/resources/temp_upload is a multipart form endpoint. For this endpoint, pass telemetry as a form field:

curl -X POST http://localhost:1933/api/v1/resources/temp_upload \
  -H "X-API-Key: your-key" \
  -F "file=@./notes.md" \
  -F "telemetry=true"

This endpoint currently accepts the boolean form only.

Common summary groups

The top-level summary always includes:

• operation
• status
• duration_ms

Depending on the operation, you may also see these groups:

• tokens: LLM and embedding token totals
• vector: vector search and filtering counts
• resource: resource ingestion and processing stages
• queue: queue processing counts for wait-mode imports
• semantic_nodes: semantic extraction totals
• memory: memory extraction or dedup summaries
• errors: aggregated error information

If a group does not apply to the operation, it is omitted.

Field reference

Only fields that are actually produced by an operation are returned. Missing groups should be treated as "not applicable" rather than as zero.

Top-level telemetry fields

summary.tokens

summary.vector

summary.resource

This group appears on resource ingestion operations such as resources.add_resource.

summary.queue

This group appears when OpenViking waits for queue-backed work to complete.

summary.semantic_nodes

summary.memory

This group appears on memory-extraction flows such as session.commit.

summary.errors

Examples

Search request with telemetry

curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query": "memory dedup",
    "limit": 5,
    "telemetry": true
  }'

Add a resource and return telemetry

curl -X POST http://localhost:1933/api/v1/resources \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "path": "./docs/readme.md",
    "reason": "telemetry demo",
    "wait": true,
    "telemetry": true
  }'

Python SDK

from openviking import AsyncOpenVikingClient

client = AsyncOpenVikingClient(config_path="/path/to/config.yaml")
await client.initialize()

result = await client.find("memory dedup", telemetry=True)
print(result["telemetry"]["summary"]["operation"])
print(result["telemetry"]["summary"]["duration_ms"])

Limitations and behavior

• OpenViking currently exposes summary-only telemetry to users
• {"telemetry": {"events": true}} is not a supported public request shape
• event-stream style selection is not part of the public API
• session.commit supports telemetry only when wait=true
• if you call session.commit with wait=false and request telemetry, the server returns INVALID_ARGUMENT
• telemetry shape is stable at the top level, but optional summary groups vary by operation

Related docs

• Observability & Diagnostics
• Authentication
• System API