Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.pyindex 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 asyncioimport base64+import timefrom pathlib import Pathfrom 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 = Nonefor 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.pyindex 7a4fd60e9..16d6948fa 100644--- a/openviking/models/vlm/backends/openai_vlm.py+++ b/openviking/models/vlm/backends/openai_vlm.py@@ -5,6 +5,7 @@import asyncioimport base64import logging+import timefrom pathlib import Pathfrom 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_tokenscompletion_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() - t0if 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 = Nonefor attempt in range(max_retries + 1):try:+ t0 = time.perf_counter()response = await client.chat.completions.create(**kwargs)+ elapsed = time.perf_counter() - t0if 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() - t0if 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() - t0if 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.pyindex 431625738..0c9c558ae 100644--- a/openviking/models/vlm/backends/volcengine_vlm.py+++ b/openviking/models/vlm/backends/volcengine_vlm.py@@ -5,6 +5,7 @@import asyncioimport base64import logging+import timefrom pathlib import Pathfrom 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 = Nonefor 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.pyindex 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 methodsdef 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 tokenscompletion_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 usagediff --git a/openviking/retrieve/retrieval_stats.py b/openviking/retrieve/retrieval_stats.pyindex 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.pyindex 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 OpenVikingServicefrom openviking.service.task_tracker import get_task_tracker+from openviking.storage.observers import PrometheusObserver+from openviking.storage.observers.prometheus_observer import set_prometheus_observerfrom openviking_cli.exceptions import OpenVikingErrorfrom 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 looptask_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.pyindex 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)++@dataclassclass 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 Vikingbotbot_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 configdiff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.pyindex 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_routerfrom openviking.server.routers.content import router as content_routerfrom openviking.server.routers.debug import router as debug_routerfrom openviking.server.routers.filesystem import router as filesystem_router+from openviking.server.routers.metrics import router as metrics_routerfrom openviking.server.routers.observer import router as observer_routerfrom openviking.server.routers.pack import router as pack_routerfrom 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.pynew file mode 100644index 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.pyindex 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:+ passexcept 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__.pyindex dae5aed35..aa2d02185 100644--- a/openviking/storage/observers/__init__.py+++ b/openviking/storage/observers/__init__.py@@ -2,6 +2,11 @@# SPDX-License-Identifier: Apache-2.0from .base_observer import BaseObserverfrom .lock_observer import LockObserver+from .prometheus_observer import (+ PrometheusObserver,+ get_prometheus_observer,+ set_prometheus_observer,+)from .queue_observer import QueueObserverfrom .retrieval_observer import RetrievalObserverfrom .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.pynew file mode 100644index 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 _observerdiff --git a/tests/server/test_prometheus_metrics.py b/tests/server/test_prometheus_metrics.pynew file mode 100644index 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