Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(telemetry): add Prometheus metrics exporter via observer pattern (#806)

Matt Van Horn08d99490722d
diff --git a/openviking/models/vlm/backends/litellm_vlm.py b/openviking/models/vlm/backends/litellm_vlm.py
index db70fc233..90230987b 100644
--- a/openviking/models/vlm/backends/litellm_vlm.py
+++ b/openviking/models/vlm/backends/litellm_vlm.py
@@ -9,6 +9,7 @@ os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"
import asyncio
import base64
+import time
from pathlib import Path
from typing import Any, Dict, List, Union
@@ -226,8 +227,10 @@ class LiteLLMVLMProvider(VLMBase):
messages = [{"role": "user", "content": prompt}]
kwargs = self._build_kwargs(model, messages)
+ t0 = time.perf_counter()
response = completion(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
return self._clean_response(self._extract_content_from_response(response))
async def get_completion_async(
@@ -241,8 +244,12 @@ class LiteLLMVLMProvider(VLMBase):
last_error = None
for attempt in range(max_retries + 1):
try:
+ t0 = time.perf_counter()
response = await acompletion(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(
+ response, duration_seconds=elapsed,
+ )
return self._clean_response(self._extract_content_from_response(response))
except Exception as e:
last_error = e
@@ -270,8 +277,10 @@ class LiteLLMVLMProvider(VLMBase):
messages = [{"role": "user", "content": content}]
kwargs = self._build_kwargs(model, messages)
+ t0 = time.perf_counter()
response = completion(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
return self._clean_response(self._extract_content_from_response(response))
async def get_vision_completion_async(
@@ -291,11 +300,15 @@ class LiteLLMVLMProvider(VLMBase):
messages = [{"role": "user", "content": content}]
kwargs = self._build_kwargs(model, messages)
+ t0 = time.perf_counter()
response = await acompletion(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
return self._clean_response(self._extract_content_from_response(response))
- def _update_token_usage_from_response(self, response) -> None:
+ def _update_token_usage_from_response(
+ self, response, duration_seconds: float = 0.0,
+ ) -> None:
"""Update token usage from response."""
if hasattr(response, "usage") and response.usage:
prompt_tokens = response.usage.prompt_tokens
@@ -305,4 +318,5 @@ class LiteLLMVLMProvider(VLMBase):
provider=self.provider,
prompt_tokens=prompt_tokens,
completion_tokens=completion_tokens,
+ duration_seconds=duration_seconds,
)
diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.py
index 7a4fd60e9..16d6948fa 100644
--- a/openviking/models/vlm/backends/openai_vlm.py
+++ b/openviking/models/vlm/backends/openai_vlm.py
@@ -5,6 +5,7 @@
import asyncio
import base64
import logging
+import time
from pathlib import Path
from typing import Any, Dict, List, Union
@@ -80,7 +81,9 @@ class OpenAIVLM(VLMBase):
self._async_client = openai.AsyncOpenAI(**kwargs)
return self._async_client
- def _update_token_usage_from_response(self, response):
+ def _update_token_usage_from_response(
+ self, response, duration_seconds: float = 0.0,
+ ):
if hasattr(response, "usage") and response.usage:
prompt_tokens = response.usage.prompt_tokens
completion_tokens = response.usage.completion_tokens
@@ -89,6 +92,7 @@ class OpenAIVLM(VLMBase):
provider=self.provider,
prompt_tokens=prompt_tokens,
completion_tokens=completion_tokens,
+ duration_seconds=duration_seconds,
)
return
@@ -191,12 +195,14 @@ class OpenAIVLM(VLMBase):
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
+ elapsed = time.perf_counter() - t0
if self.stream:
content = self._process_streaming_response(response)
else:
- self._update_token_usage_from_response(response)
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
content = self._extract_content_from_response(response)
return self._clean_response(content)
@@ -218,12 +224,16 @@ class OpenAIVLM(VLMBase):
last_error = None
for attempt in range(max_retries + 1):
try:
+ t0 = time.perf_counter()
response = await client.chat.completions.create(**kwargs)
+ elapsed = time.perf_counter() - t0
if self.stream:
content = await self._process_streaming_response_async(response)
else:
- self._update_token_usage_from_response(response)
+ self._update_token_usage_from_response(
+ response, duration_seconds=elapsed,
+ )
content = self._extract_content_from_response(response)
return self._clean_response(content)
@@ -312,12 +322,14 @@ class OpenAIVLM(VLMBase):
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
+ elapsed = time.perf_counter() - t0
if self.stream:
content = self._process_streaming_response(response)
else:
- self._update_token_usage_from_response(response)
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
content = self._extract_content_from_response(response)
return self._clean_response(content)
@@ -345,12 +357,14 @@ class OpenAIVLM(VLMBase):
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ t0 = time.perf_counter()
response = await client.chat.completions.create(**kwargs)
+ elapsed = time.perf_counter() - t0
if self.stream:
content = await self._process_streaming_response_async(response)
else:
- self._update_token_usage_from_response(response)
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
content = self._extract_content_from_response(response)
return self._clean_response(content)
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index 431625738..0c9c558ae 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -5,6 +5,7 @@
import asyncio
import base64
import logging
+import time
from pathlib import Path
from typing import Any, Dict, List, Union
@@ -71,8 +72,10 @@ class VolcEngineVLM(OpenAIVLM):
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
return self._clean_response(self._extract_content_from_response(response))
async def get_completion_async(
@@ -92,8 +95,12 @@ class VolcEngineVLM(OpenAIVLM):
last_error = None
for attempt in range(max_retries + 1):
try:
+ t0 = time.perf_counter()
response = await client.chat.completions.create(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(
+ response, duration_seconds=elapsed,
+ )
return self._clean_response(self._extract_content_from_response(response))
except Exception as e:
last_error = e
@@ -242,8 +249,10 @@ class VolcEngineVLM(OpenAIVLM):
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
return self._clean_response(self._extract_content_from_response(response))
async def get_vision_completion_async(
@@ -269,6 +278,8 @@ class VolcEngineVLM(OpenAIVLM):
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ t0 = time.perf_counter()
response = await client.chat.completions.create(**kwargs)
- self._update_token_usage_from_response(response)
+ elapsed = time.perf_counter() - t0
+ self._update_token_usage_from_response(response, duration_seconds=elapsed)
return self._clean_response(self._extract_content_from_response(response))
diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.py
index 7588d911d..fd8f939c1 100644
--- a/openviking/models/vlm/base.py
+++ b/openviking/models/vlm/base.py
@@ -74,7 +74,8 @@ class VLMBase(ABC):
# Token usage tracking methods
def update_token_usage(
- self, model_name: str, provider: str, prompt_tokens: int, completion_tokens: int
+ self, model_name: str, provider: str, prompt_tokens: int, completion_tokens: int,
+ duration_seconds: float = 0.0,
) -> None:
"""Update token usage
@@ -83,6 +84,7 @@ class VLMBase(ABC):
provider: Provider name (openai, volcengine)
prompt_tokens: Number of prompt tokens
completion_tokens: Number of completion tokens
+ duration_seconds: Wall-clock duration of the VLM call in seconds
"""
self._token_tracker.update(
model_name=model_name,
@@ -99,6 +101,16 @@ class VLMBase(ABC):
# Telemetry must never break model inference.
pass
+ # Record the VLM call in Prometheus metrics (if enabled).
+ try:
+ from openviking.storage.observers.prometheus_observer import get_prometheus_observer
+
+ prom = get_prometheus_observer()
+ if prom is not None:
+ prom.record_vlm_call(duration_seconds)
+ except Exception:
+ pass
+
def get_token_usage(self) -> Dict[str, Any]:
"""Get token usage
diff --git a/openviking/retrieve/retrieval_stats.py b/openviking/retrieve/retrieval_stats.py
index 9c285dc21..7957a361d 100644
--- a/openviking/retrieve/retrieval_stats.py
+++ b/openviking/retrieve/retrieval_stats.py
@@ -137,6 +137,16 @@ class RetrievalStatsCollector:
if latency_ms > self._stats.max_latency_ms:
self._stats.max_latency_ms = latency_ms
+ # Notify the Prometheus observer (if enabled) outside our lock.
+ try:
+ from openviking.storage.observers.prometheus_observer import get_prometheus_observer
+
+ prom = get_prometheus_observer()
+ if prom is not None:
+ prom.record_retrieval(latency_ms / 1000.0)
+ except Exception:
+ pass
+
def snapshot(self) -> RetrievalStats:
"""Return a copy of the current stats."""
with self._lock:
diff --git a/openviking/server/app.py b/openviking/server/app.py
index d688bd0f7..6358a2f08 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -20,6 +20,7 @@ from openviking.server.routers import (
content_router,
debug_router,
filesystem_router,
+ metrics_router,
observer_router,
pack_router,
relations_router,
@@ -31,6 +32,8 @@ from openviking.server.routers import (
)
from openviking.service.core import OpenVikingService
from openviking.service.task_tracker import get_task_tracker
+from openviking.storage.observers import PrometheusObserver
+from openviking.storage.observers.prometheus_observer import set_prometheus_observer
from openviking_cli.exceptions import OpenVikingError
from openviking_cli.utils import get_logger
@@ -89,6 +92,13 @@ def create_app(
config.host,
)
+ app.state.prometheus_observer = None
+ if config.telemetry.prometheus.enabled:
+ observer = PrometheusObserver()
+ app.state.prometheus_observer = observer
+ set_prometheus_observer(observer)
+ logger.info("Prometheus metrics enabled at /metrics")
+
# Start TaskTracker cleanup loop
task_tracker = get_task_tracker()
task_tracker.start_cleanup_loop()
@@ -96,6 +106,7 @@ def create_app(
yield
# Cleanup
+ set_prometheus_observer(None)
task_tracker.stop_cleanup_loop()
if owns_service and service:
await service.close()
@@ -180,6 +191,7 @@ def create_app(
app.include_router(pack_router)
app.include_router(debug_router)
app.include_router(observer_router)
+ app.include_router(metrics_router)
app.include_router(tasks_router)
app.include_router(bot_router, prefix="/bot/v1")
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 7d8e8aafc..baf058190 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -21,6 +21,20 @@ from openviking_cli.utils.config.consts import (
logger = get_logger(__name__)
+@dataclass
+class PrometheusConfig:
+ """Prometheus exporter configuration."""
+
+ enabled: bool = False
+
+
+@dataclass
+class TelemetryConfig:
+ """Telemetry configuration."""
+
+ prometheus: PrometheusConfig = field(default_factory=PrometheusConfig)
+
+
@dataclass
class ServerConfig:
"""Server configuration (from the ``server`` section of ov.conf)."""
@@ -33,6 +47,7 @@ class ServerConfig:
with_bot: bool = False # Enable Bot API proxy to Vikingbot
bot_api_url: str = "http://localhost:18790" # Vikingbot OpenAPIChannel URL (default port)
encryption_enabled: bool = False # Whether API key hashing is enabled
+ telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
@@ -68,6 +83,8 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
data = load_json_config(path)
server_data = data.get("server", {})
+ telemetry_data = server_data.get("telemetry", {}) or {}
+ prometheus_data = telemetry_data.get("prometheus", {}) or {}
# Get encryption enabled from config data directly (for test compatibility)
encryption_enabled = data.get("encryption", {}).get("enabled", False)
@@ -79,6 +96,11 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
root_api_key=server_data.get("root_api_key"),
cors_origins=server_data.get("cors_origins", ["*"]),
encryption_enabled=encryption_enabled,
+ telemetry=TelemetryConfig(
+ prometheus=PrometheusConfig(
+ enabled=prometheus_data.get("enabled", False),
+ )
+ ),
)
return config
diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.py
index 12aa9f344..df25e358e 100644
--- a/openviking/server/routers/__init__.py
+++ b/openviking/server/routers/__init__.py
@@ -7,6 +7,7 @@ from openviking.server.routers.bot import router as bot_router
from openviking.server.routers.content import router as content_router
from openviking.server.routers.debug import router as debug_router
from openviking.server.routers.filesystem import router as filesystem_router
+from openviking.server.routers.metrics import router as metrics_router
from openviking.server.routers.observer import router as observer_router
from openviking.server.routers.pack import router as pack_router
from openviking.server.routers.relations import router as relations_router
@@ -28,6 +29,7 @@ __all__ = [
"sessions_router",
"pack_router",
"debug_router",
+ "metrics_router",
"observer_router",
"tasks_router",
]
diff --git a/openviking/server/routers/metrics.py b/openviking/server/routers/metrics.py
new file mode 100644
index 000000000..16546e93f
--- /dev/null
+++ b/openviking/server/routers/metrics.py
@@ -0,0 +1,21 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Prometheus metrics endpoint for OpenViking HTTP Server."""
+
+from fastapi import APIRouter, Request
+from fastapi.responses import PlainTextResponse
+
+router = APIRouter(tags=["metrics"])
+
+
[email protected]("/metrics")
+async def metrics(request: Request):
+ """Return Prometheus metrics in text exposition format."""
+ observer = getattr(request.app.state, "prometheus_observer", None)
+ if observer is None:
+ return PlainTextResponse(status_code=404, content="Prometheus metrics are disabled.\n")
+
+ return PlainTextResponse(
+ content=observer.render_metrics(),
+ media_type="text/plain; version=0.0.4; charset=utf-8",
+ )
diff --git a/openviking/storage/collection_schemas.py b/openviking/storage/collection_schemas.py
index 590ad6856..859f9ed2b 100644
--- a/openviking/storage/collection_schemas.py
+++ b/openviking/storage/collection_schemas.py
@@ -248,9 +248,23 @@ class TextEmbeddingHandler(DequeueHandlerBase):
try:
# embed() is a blocking HTTP call; offload to thread pool to avoid
# blocking the event loop and allow real concurrency.
+ import time as _time
+
+ _embed_t0 = _time.monotonic()
result: EmbedResult = await asyncio.to_thread(
self._embedder.embed, embedding_msg.message
)
+ _embed_elapsed = _time.monotonic() - _embed_t0
+ try:
+ from openviking.storage.observers.prometheus_observer import (
+ get_prometheus_observer,
+ )
+
+ _prom = get_prometheus_observer()
+ if _prom is not None:
+ _prom.record_embedding(_embed_elapsed)
+ except Exception:
+ pass
except Exception as embed_err:
error_msg = f"Failed to generate embedding: {embed_err}"
logger.error(error_msg)
diff --git a/openviking/storage/observers/__init__.py b/openviking/storage/observers/__init__.py
index dae5aed35..aa2d02185 100644
--- a/openviking/storage/observers/__init__.py
+++ b/openviking/storage/observers/__init__.py
@@ -2,6 +2,11 @@
# SPDX-License-Identifier: Apache-2.0
from .base_observer import BaseObserver
from .lock_observer import LockObserver
+from .prometheus_observer import (
+ PrometheusObserver,
+ get_prometheus_observer,
+ set_prometheus_observer,
+)
from .queue_observer import QueueObserver
from .retrieval_observer import RetrievalObserver
from .vikingdb_observer import VikingDBObserver
@@ -10,6 +15,9 @@ from .vlm_observer import VLMObserver
__all__ = [
"BaseObserver",
"LockObserver",
+ "PrometheusObserver",
+ "get_prometheus_observer",
+ "set_prometheus_observer",
"QueueObserver",
"RetrievalObserver",
"VikingDBObserver",
diff --git a/openviking/storage/observers/prometheus_observer.py b/openviking/storage/observers/prometheus_observer.py
new file mode 100644
index 000000000..f3be59273
--- /dev/null
+++ b/openviking/storage/observers/prometheus_observer.py
@@ -0,0 +1,195 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""PrometheusObserver: Prometheus metrics exporter for OpenViking."""
+
+import threading
+from threading import Lock
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from openviking.storage.observers.base_observer import BaseObserver
+
+
+class _Histogram:
+ """Thread-safe in-memory histogram for Prometheus exposition."""
+
+ def __init__(self, buckets: Iterable[float]):
+ self._buckets = sorted(float(b) for b in buckets)
+ self._bucket_counts: List[int] = [0] * len(self._buckets)
+ self._sum = 0.0
+ self._count = 0
+
+ def observe(self, value: float) -> None:
+ self._sum += value
+ self._count += 1
+ for idx, upper in enumerate(self._buckets):
+ if value <= upper:
+ self._bucket_counts[idx] += 1
+ # +Inf bucket is implied by _count.
+
+ def snapshot(self) -> Tuple[List[float], List[int], float, int]:
+ return list(self._buckets), list(self._bucket_counts), self._sum, self._count
+
+
+class PrometheusObserver(BaseObserver):
+ """Observer that records and renders Prometheus metrics text format."""
+
+ DEFAULT_LATENCY_BUCKETS = (0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+ CACHE_LEVELS = ("L0", "L1", "L2")
+
+ def __init__(self):
+ self._lock = Lock()
+
+ self._retrieval_requests_total = 0
+ self._embedding_requests_total = 0
+ self._vlm_calls_total = 0
+
+ self._cache_hits_total: Dict[str, int] = dict.fromkeys(self.CACHE_LEVELS, 0)
+ self._cache_misses_total: Dict[str, int] = dict.fromkeys(self.CACHE_LEVELS, 0)
+
+ self._retrieval_latency_seconds = _Histogram(self.DEFAULT_LATENCY_BUCKETS)
+ self._embedding_latency_seconds = _Histogram(self.DEFAULT_LATENCY_BUCKETS)
+ self._vlm_call_duration_seconds = _Histogram(self.DEFAULT_LATENCY_BUCKETS)
+
+ def get_status_table(self) -> str:
+ """Return Prometheus exposition for observer status views."""
+ return self.render_metrics()
+
+ def is_healthy(self) -> bool:
+ return True
+
+ def has_errors(self) -> bool:
+ return False
+
+ def record_retrieval(self, latency_seconds: float) -> None:
+ with self._lock:
+ self._retrieval_requests_total += 1
+ self._retrieval_latency_seconds.observe(float(latency_seconds))
+
+ def record_embedding(self, latency_seconds: float) -> None:
+ with self._lock:
+ self._embedding_requests_total += 1
+ self._embedding_latency_seconds.observe(float(latency_seconds))
+
+ def record_vlm_call(self, duration_seconds: float) -> None:
+ with self._lock:
+ self._vlm_calls_total += 1
+ self._vlm_call_duration_seconds.observe(float(duration_seconds))
+
+ def record_cache_hit(self, level: str) -> None:
+ with self._lock:
+ if level not in self._cache_hits_total:
+ self._cache_hits_total[level] = 0
+ self._cache_hits_total[level] += 1
+
+ def record_cache_miss(self, level: str) -> None:
+ with self._lock:
+ if level not in self._cache_misses_total:
+ self._cache_misses_total[level] = 0
+ self._cache_misses_total[level] += 1
+
+ def render_metrics(self) -> str:
+ with self._lock:
+ retrieval_requests_total = self._retrieval_requests_total
+ embedding_requests_total = self._embedding_requests_total
+ vlm_calls_total = self._vlm_calls_total
+ cache_hits_total = dict(self._cache_hits_total)
+ cache_misses_total = dict(self._cache_misses_total)
+ retrieval_hist = self._retrieval_latency_seconds.snapshot()
+ embedding_hist = self._embedding_latency_seconds.snapshot()
+ vlm_hist = self._vlm_call_duration_seconds.snapshot()
+
+ lines: List[str] = []
+ lines.extend(
+ [
+ "# HELP openviking_retrieval_requests_total Total retrieval requests.",
+ "# TYPE openviking_retrieval_requests_total counter",
+ f"openviking_retrieval_requests_total {retrieval_requests_total}",
+ "# HELP openviking_embedding_requests_total Total embedding requests.",
+ "# TYPE openviking_embedding_requests_total counter",
+ f"openviking_embedding_requests_total {embedding_requests_total}",
+ "# HELP openviking_vlm_calls_total Total VLM calls.",
+ "# TYPE openviking_vlm_calls_total counter",
+ f"openviking_vlm_calls_total {vlm_calls_total}",
+ ]
+ )
+
+ self._append_histogram(
+ lines=lines,
+ name="openviking_retrieval_latency_seconds",
+ help_text="Retrieval request latency in seconds.",
+ histogram=retrieval_hist,
+ )
+ self._append_histogram(
+ lines=lines,
+ name="openviking_embedding_latency_seconds",
+ help_text="Embedding request latency in seconds.",
+ histogram=embedding_hist,
+ )
+ self._append_histogram(
+ lines=lines,
+ name="openviking_vlm_call_duration_seconds",
+ help_text="VLM call duration in seconds.",
+ histogram=vlm_hist,
+ )
+
+ self._append_labeled_counter(
+ lines=lines,
+ name="openviking_cache_hits_total",
+ help_text="Total cache hits by cache level.",
+ counters=cache_hits_total,
+ )
+ self._append_labeled_counter(
+ lines=lines,
+ name="openviking_cache_misses_total",
+ help_text="Total cache misses by cache level.",
+ counters=cache_misses_total,
+ )
+
+ return "\n".join(lines) + "\n"
+
+ @staticmethod
+ def _append_labeled_counter(
+ lines: List[str],
+ name: str,
+ help_text: str,
+ counters: Dict[str, int],
+ ) -> None:
+ lines.append(f"# HELP {name} {help_text}")
+ lines.append(f"# TYPE {name} counter")
+ for level in sorted(counters):
+ lines.append(f'{name}{{level="{level}"}} {counters[level]}')
+
+ @staticmethod
+ def _append_histogram(
+ lines: List[str],
+ name: str,
+ help_text: str,
+ histogram: Tuple[List[float], List[int], float, int],
+ ) -> None:
+ buckets, bucket_counts, total_sum, total_count = histogram
+ lines.append(f"# HELP {name} {help_text}")
+ lines.append(f"# TYPE {name} histogram")
+
+ for upper, count in zip(buckets, bucket_counts):
+ lines.append(f'{name}_bucket{{le="{upper:g}"}} {count}')
+ lines.append(f'{name}_bucket{{le="+Inf"}} {total_count}')
+ lines.append(f"{name}_sum {total_sum}")
+ lines.append(f"{name}_count {total_count}")
+
+
+# Module-level singleton so that data-collection hooks can record metrics
+# without requiring access to the FastAPI app state.
+_observer: Optional[PrometheusObserver] = None
+_observer_lock = threading.Lock()
+
+
+def set_prometheus_observer(observer: Optional[PrometheusObserver]) -> None:
+ """Set the global PrometheusObserver instance (called during app startup)."""
+ global _observer
+ with _observer_lock:
+ _observer = observer
+
+
+def get_prometheus_observer() -> Optional[PrometheusObserver]:
+ """Return the global PrometheusObserver, or None when metrics are disabled."""
+ return _observer
diff --git a/tests/server/test_prometheus_metrics.py b/tests/server/test_prometheus_metrics.py
new file mode 100644
index 000000000..4b2a422a1
--- /dev/null
+++ b/tests/server/test_prometheus_metrics.py
@@ -0,0 +1,134 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the Prometheus metrics exporter."""
+
+import httpx
+import pytest
+
+from openviking.server.app import create_app
+from openviking.server.config import PrometheusConfig, ServerConfig, TelemetryConfig
+from openviking.storage.observers.prometheus_observer import (
+ PrometheusObserver,
+ get_prometheus_observer,
+ set_prometheus_observer,
+)
+
+
+class TestPrometheusObserver:
+ """Unit tests for PrometheusObserver recording and rendering."""
+
+ def test_record_retrieval(self):
+ obs = PrometheusObserver()
+ obs.record_retrieval(0.05)
+ obs.record_retrieval(0.12)
+ text = obs.render_metrics()
+ assert "openviking_retrieval_requests_total 2" in text
+ assert "openviking_retrieval_latency_seconds_count 2" in text
+
+ def test_record_embedding(self):
+ obs = PrometheusObserver()
+ obs.record_embedding(0.3)
+ text = obs.render_metrics()
+ assert "openviking_embedding_requests_total 1" in text
+ assert "openviking_embedding_latency_seconds_count 1" in text
+
+ def test_record_vlm_call(self):
+ obs = PrometheusObserver()
+ obs.record_vlm_call(1.5)
+ text = obs.render_metrics()
+ assert "openviking_vlm_calls_total 1" in text
+ assert "openviking_vlm_call_duration_seconds_count 1" in text
+
+ def test_cache_hit_miss(self):
+ obs = PrometheusObserver()
+ obs.record_cache_hit("L0")
+ obs.record_cache_hit("L0")
+ obs.record_cache_miss("L1")
+ text = obs.render_metrics()
+ assert 'openviking_cache_hits_total{level="L0"} 2' in text
+ assert 'openviking_cache_misses_total{level="L1"} 1' in text
+
+ def test_render_empty_metrics(self):
+ obs = PrometheusObserver()
+ text = obs.render_metrics()
+ assert "openviking_retrieval_requests_total 0" in text
+ assert "openviking_embedding_requests_total 0" in text
+ assert "openviking_vlm_calls_total 0" in text
+
+ def test_histogram_buckets(self):
+ obs = PrometheusObserver()
+ obs.record_retrieval(0.02)
+ text = obs.render_metrics()
+ assert 'openviking_retrieval_latency_seconds_bucket{le="0.05"} 1' in text
+ assert 'openviking_retrieval_latency_seconds_bucket{le="+Inf"} 1' in text
+
+
+class TestPrometheusObserverSingleton:
+ """Tests for the module-level singleton accessor."""
+
+ def test_default_is_none(self):
+ set_prometheus_observer(None)
+ assert get_prometheus_observer() is None
+
+ def test_set_and_get(self):
+ obs = PrometheusObserver()
+ set_prometheus_observer(obs)
+ assert get_prometheus_observer() is obs
+ set_prometheus_observer(None)
+
+ def test_clear_singleton(self):
+ obs = PrometheusObserver()
+ set_prometheus_observer(obs)
+ set_prometheus_observer(None)
+ assert get_prometheus_observer() is None
+
+
+class TestRetrievalStatsPrometheusIntegration:
+ """Test that RetrievalStatsCollector notifies the PrometheusObserver."""
+
+ def test_record_query_notifies_prometheus(self):
+ from openviking.retrieve.retrieval_stats import RetrievalStatsCollector
+
+ obs = PrometheusObserver()
+ set_prometheus_observer(obs)
+ try:
+ collector = RetrievalStatsCollector()
+ collector.record_query(
+ context_type="memory",
+ result_count=3,
+ scores=[0.8, 0.7, 0.6],
+ latency_ms=42.5,
+ )
+ text = obs.render_metrics()
+ assert "openviking_retrieval_requests_total 1" in text
+ assert "openviking_retrieval_latency_seconds_count 1" in text
+ finally:
+ set_prometheus_observer(None)
+
+
+class TestMetricsEndpoint:
+ """Tests for the /metrics HTTP endpoint."""
+
+ async def test_metrics_disabled_returns_404(self):
+ config = ServerConfig()
+ app = create_app(config=config, service=None)
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ resp = await client.get("/metrics")
+ assert resp.status_code == 404
+
+ async def test_metrics_enabled_returns_200(self):
+ config = ServerConfig(
+ telemetry=TelemetryConfig(prometheus=PrometheusConfig(enabled=True))
+ )
+ app = create_app(config=config, service=None)
+ # Simulate lifespan setting the observer on app.state
+ obs = PrometheusObserver()
+ app.state.prometheus_observer = obs
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ resp = await client.get("/metrics")
+ assert resp.status_code == 200
+ assert "openviking_retrieval_requests_total" in resp.text