Skip to content

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

feat(console): 增加 Usage/Audit Dashboard BFF (#2016)

Qin Haojie9d36b2fd833d
diff --git a/openviking/console/app.py b/openviking/console/app.py
index 03f7f5ff9..8883a063f 100644
--- a/openviking/console/app.py
+++ b/openviking/console/app.py
@@ -253,6 +253,22 @@ def _create_proxy_router() -> APIRouter:
async def system_status(request: Request):
return await _forward_request(request, "/api/v1/system/status")
+ @router.get("/ov/console/dashboard/summary")
+ async def console_dashboard_summary(request: Request):
+ return await _forward_request(request, "/api/v1/console/dashboard/summary")
+
+ @router.get("/ov/console/tokens")
+ async def console_tokens(request: Request):
+ return await _forward_request(request, "/api/v1/console/tokens")
+
+ @router.get("/ov/console/context-commits")
+ async def console_context_commits(request: Request):
+ return await _forward_request(request, "/api/v1/console/context-commits")
+
+ @router.get("/ov/console/audit")
+ async def console_audit(request: Request):
+ return await _forward_request(request, "/api/v1/console/audit")
+
@router.get("/ov/observer/{component}")
async def observer_component(request: Request, component: str):
invalid = _validate_path_param(component, "component")
diff --git a/openviking/metrics/core/runtime.py b/openviking/metrics/core/runtime.py
index 3d92be25d..31aa07316 100644
--- a/openviking/metrics/core/runtime.py
+++ b/openviking/metrics/core/runtime.py
@@ -4,9 +4,9 @@
"""
Runtime utilities for the metrics subsystem.
-Currently this module defines a small in-process event router:
-- DataSources emit events by calling `openviking.metrics.global_api.try_dispatch_event(...)`.
-- The global API routes events to the matching Collector handler.
+Currently this module defines the metrics subscriber's event router:
+- DataSources publish events to the shared observability event bus.
+- Metrics subscribes with this router and routes each event to the matching Collector handler.
This avoids wiring MetricRegistry into business code and keeps the write-path
restricted to Collector implementations.
diff --git a/openviking/metrics/datasources/base.py b/openviking/metrics/datasources/base.py
index 34a1af850..63e83d4c5 100644
--- a/openviking/metrics/datasources/base.py
+++ b/openviking/metrics/datasources/base.py
@@ -12,8 +12,8 @@ class EventMetricDataSource(MetricDataSource):
"""
Shared base for datasources that emit push-style in-process metrics events.
- Event datasources publish normalized payloads into the metrics event router instead of
- writing to the registry directly, keeping business code decoupled from collector internals.
+ Event datasources publish normalized payloads into the shared observability event bus instead
+ of writing to the registry directly, keeping business code decoupled from collector internals.
"""
KIND: ClassVar[str] = "event"
@@ -26,14 +26,14 @@ class EventMetricDataSource(MetricDataSource):
@staticmethod
def _emit(event_name: str, payload: dict) -> None:
"""
- Emit one normalized metrics event through the global best-effort event router.
+ Emit one normalized event through the global best-effort observability event bus.
- Missing metrics initialization is handled by the router path so callers can fire events
- without adding explicit metrics-enabled guards around business logic.
+ Missing subscribers are handled by the bus path so callers can fire events without adding
+ explicit metrics-enabled guards around business logic.
"""
- from openviking.metrics.global_api import try_dispatch_event
+ from openviking.observability.events import try_publish_event
- try_dispatch_event(str(event_name), dict(payload))
+ try_publish_event(str(event_name), dict(payload))
class StateMetricDataSource(MetricDataSource):
diff --git a/openviking/metrics/datasources/http.py b/openviking/metrics/datasources/http.py
index aebc53d8c..1c5f9bbd7 100644
--- a/openviking/metrics/datasources/http.py
+++ b/openviking/metrics/datasources/http.py
@@ -32,6 +32,10 @@ class HttpRequestLifecycleDataSource(EventMetricDataSource):
status: str,
duration_seconds: float,
account_id: str | None = None,
+ request_id: str | None = None,
+ user_id: str | None = None,
+ agent_id: str | None = None,
+ url_path: str | None = None,
) -> None:
"""
Emit a completed-request event with normalized method, route, status, and duration data.
@@ -39,16 +43,22 @@ class HttpRequestLifecycleDataSource(EventMetricDataSource):
The payload is plain data so middleware can attach an explicit `account_id` when the
authenticated tenant is already known.
"""
- EventMetricDataSource._emit(
- "http.request",
- {
- "method": str(method),
- "route": str(route),
- "status": str(status),
- "duration_seconds": float(duration_seconds),
- "account_id": None if account_id is None else str(account_id),
- },
- )
+ payload = {
+ "method": str(method),
+ "route": str(route),
+ "status": str(status),
+ "duration_seconds": float(duration_seconds),
+ "account_id": None if account_id is None else str(account_id),
+ }
+ if request_id is not None:
+ payload["request_id"] = str(request_id)
+ if user_id is not None:
+ payload["user_id"] = str(user_id)
+ if agent_id is not None:
+ payload["agent_id"] = str(agent_id)
+ if url_path is not None:
+ payload["url_path"] = str(url_path)
+ EventMetricDataSource._emit("http.request", payload)
@staticmethod
def set_inflight(*, route: str, value: float, account_id: str | None = None) -> None:
diff --git a/openviking/metrics/datasources/model_usage.py b/openviking/metrics/datasources/model_usage.py
index 39292fec5..cdff63b09 100644
--- a/openviking/metrics/datasources/model_usage.py
+++ b/openviking/metrics/datasources/model_usage.py
@@ -10,7 +10,8 @@ This file provides two categories of DataSource APIs:
`ModelUsageCollector` which converts cumulative stats into Prometheus Counters via deltas.
2) Event (push): `VLMEventDataSource`, `EmbeddingEventDataSource`, and
`RerankEventDataSource` emit per-call events.
- These events are routed to Event collectors via `try_dispatch_event`.
+ These events are published to the shared observability event bus and consumed by metrics
+ collectors and Usage/Audit subscribers.
Note: DataSources are not allowed to write into MetricRegistry directly in this architecture.
They only emit events or expose read APIs. Collectors are the only writers.
diff --git a/openviking/metrics/global_api.py b/openviking/metrics/global_api.py
index 96af2a193..b11aa07ca 100644
--- a/openviking/metrics/global_api.py
+++ b/openviking/metrics/global_api.py
@@ -2,17 +2,19 @@
# SPDX-License-Identifier: AGPL-3.0
"""
-Global metrics bootstrap and event dispatch.
+Global metrics bootstrap and event subscription.
This module provides:
- A process-global MetricRegistry and PrometheusExporter instance for the server.
-- A lightweight in-process event router used by DataSources to emit events without
- directly depending on MetricRegistry internals.
+- A metrics subscriber that consumes shared observability events without making
+ DataSources depend on MetricRegistry internals.
Why an event router?
Business code (models, encryption, HTTP middleware, etc.) calls DataSource APIs such as
-`VLMEventDataSource.record_call(...)`. DataSources emit events here. Collectors are the
-only layer allowed to write into MetricRegistry, keeping the architecture consistent.
+`VLMEventDataSource.record_call(...)`. DataSources publish observability events. Metrics
+collectors subscribe to those events and remain the only layer allowed to write into
+MetricRegistry, keeping the architecture consistent while letting other subscribers consume
+the same signal.
"""
from __future__ import annotations
@@ -22,6 +24,12 @@ import inspect
import threading
from typing import Optional
+from openviking.observability.events import (
+ make_payload_subscriber,
+ register_event_subscriber,
+ try_publish_event,
+ unregister_event_subscriber,
+)
from openviking.server.config import ServerConfig
from openviking_cli.utils import get_logger
@@ -53,6 +61,7 @@ _lock = threading.Lock()
_registry: Optional[MetricRegistry] = None
_exporters: list = []
_event_router: EventCollectorRouter | None = None
+_METRICS_EVENT_SUBSCRIBER = "metrics"
def _shutdown_exporters_best_effort(exporters: list) -> None:
@@ -136,6 +145,7 @@ def init_metrics_from_server_config(
_registry = None
_exporters = []
_event_router = None
+ unregister_event_subscriber(_METRICS_EVENT_SUBSCRIBER)
reset_metric_account_dimension()
if app is not None:
app.state.metrics_exporters = []
@@ -153,6 +163,10 @@ def init_metrics_from_server_config(
_registry = registry or MetricRegistry()
collector_manager = create_default_collector_manager(app=app, service=service)
_event_router = _build_event_router(_registry)
+ register_event_subscriber(
+ _METRICS_EVENT_SUBSCRIBER,
+ make_payload_subscriber(_event_router.dispatch),
+ )
_exporters = []
exporters_config = config.observability.metrics.exporters
@@ -198,6 +212,7 @@ def shutdown_metrics(*, app=None) -> None:
_registry = None
_exporters = []
_event_router = None
+ unregister_event_subscriber(_METRICS_EVENT_SUBSCRIBER)
reset_metric_account_dimension()
if app is not None:
app.state.metrics_exporters = []
@@ -211,6 +226,7 @@ async def shutdown_metrics_async(*, app=None) -> None:
_registry = None
_exporters = []
_event_router = None
+ unregister_event_subscriber(_METRICS_EVENT_SUBSCRIBER)
reset_metric_account_dimension()
if app is not None:
app.state.metrics_exporters = []
@@ -250,15 +266,13 @@ def try_get_metrics_registry() -> MetricRegistry | None:
def try_dispatch_event(event_name: str, payload: dict) -> None:
"""
- Dispatch an in-process metrics event.
+ Publish an in-process observability event.
- This is a best-effort API: if metrics are not initialized, it is a no-op.
- Callers must not assume the event is recorded.
+ Kept for older call sites that imported the metrics API directly. The event is now
+ published to the shared bus, so non-metrics subscribers can consume it even when
+ Prometheus metrics are disabled.
"""
- router = _event_router
- if router is None:
- return
- router.dispatch(event_name, payload)
+ try_publish_event(event_name, payload)
def _build_event_router(registry: MetricRegistry) -> EventCollectorRouter:
diff --git a/openviking/observability/events.py b/openviking/observability/events.py
new file mode 100644
index 000000000..2f84e7675
--- /dev/null
+++ b/openviking/observability/events.py
@@ -0,0 +1,167 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Process-local observability event bus.
+
+The bus is intentionally small and best-effort. It lets one emitted event feed
+multiple side-channel consumers, such as Prometheus collectors and product
+usage/audit projections, without coupling business code to either consumer.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Protocol
+
+from openviking.observability.context import get_observability_context
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class ObservabilityEvent:
+ """One normalized in-process observability event."""
+
+ event_name: str
+ payload: dict[str, Any]
+ timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+ request_id: str | None = None
+ account_id: str | None = None
+ user_id: str | None = None
+ agent_id: str | None = None
+
+
+class ObservabilitySubscriber(Protocol):
+ """Callable protocol for event bus subscribers."""
+
+ def __call__(self, event: ObservabilityEvent) -> None:
+ """Consume one best-effort observability event."""
+
+
+class ObservabilityEventBus:
+ """Thread-safe fan-out dispatcher for process-local observability events."""
+
+ def __init__(self) -> None:
+ self._subscribers: dict[str, ObservabilitySubscriber] = {}
+ self._lock = threading.RLock()
+
+ def register(self, name: str, subscriber: ObservabilitySubscriber) -> None:
+ """Register or replace one named subscriber."""
+ key = str(name)
+ with self._lock:
+ self._subscribers[key] = subscriber
+
+ def unregister(self, name: str) -> None:
+ """Remove one named subscriber if present."""
+ key = str(name)
+ with self._lock:
+ self._subscribers.pop(key, None)
+
+ def publish(self, event: ObservabilityEvent) -> None:
+ """Deliver an event to every subscriber without raising to callers."""
+ with self._lock:
+ subscribers = list(self._subscribers.items())
+
+ for name, subscriber in subscribers:
+ try:
+ subscriber(event)
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "observability subscriber %s failed for event %s: %s",
+ name,
+ event.event_name,
+ exc,
+ exc_info=logger.isEnabledFor(logging.DEBUG),
+ )
+
+ def clear(self) -> None:
+ """Remove all subscribers. Intended for tests and process shutdown."""
+ with self._lock:
+ self._subscribers.clear()
+
+
+_GLOBAL_EVENT_BUS = ObservabilityEventBus()
+
+
+def get_event_bus() -> ObservabilityEventBus:
+ """Return the process-global observability event bus."""
+ return _GLOBAL_EVENT_BUS
+
+
+def register_event_subscriber(name: str, subscriber: ObservabilitySubscriber) -> None:
+ """Register a process-global event subscriber."""
+ _GLOBAL_EVENT_BUS.register(name, subscriber)
+
+
+def unregister_event_subscriber(name: str) -> None:
+ """Unregister a process-global event subscriber."""
+ _GLOBAL_EVENT_BUS.unregister(name)
+
+
+def reset_event_bus_for_tests() -> None:
+ """Clear all subscribers from the process-global bus."""
+ _GLOBAL_EVENT_BUS.clear()
+
+
+def _metadata_from_context(payload: dict[str, Any]) -> dict[str, str | None]:
+ """Build event metadata from payload first, then current root context."""
+ root = get_observability_context().root
+
+ def _first(*values: Any) -> str | None:
+ for value in values:
+ if value is not None:
+ return str(value)
+ return None
+
+ return {
+ "request_id": _first(payload.get("request_id"), getattr(root, "request_id", None)),
+ "account_id": _first(payload.get("account_id"), getattr(root, "account_id", None)),
+ "user_id": _first(payload.get("user_id"), getattr(root, "user_id", None)),
+ "agent_id": _first(payload.get("agent_id"), getattr(root, "agent_id", None)),
+ }
+
+
+def build_event(event_name: str, payload: dict[str, Any] | None = None) -> ObservabilityEvent:
+ """Create an enriched event envelope from a raw event name and payload."""
+ normalized_payload = dict(payload or {})
+ metadata = _metadata_from_context(normalized_payload)
+ return ObservabilityEvent(
+ event_name=str(event_name),
+ payload=normalized_payload,
+ request_id=metadata["request_id"],
+ account_id=metadata["account_id"],
+ user_id=metadata["user_id"],
+ agent_id=metadata["agent_id"],
+ )
+
+
+def try_publish_event(event_name: str, payload: dict[str, Any] | None = None) -> None:
+ """Best-effort publish API used by observability data sources."""
+ try:
+ _GLOBAL_EVENT_BUS.publish(build_event(event_name, payload))
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "observability event publish failed for %s: %s",
+ event_name,
+ exc,
+ exc_info=logger.isEnabledFor(logging.DEBUG),
+ )
+
+
+def make_payload_subscriber(
+ handler: Callable[[str, dict[str, Any]], None],
+) -> ObservabilitySubscriber:
+ """Adapt a legacy `(event_name, payload)` handler to an event subscriber."""
+
+ def _subscriber(event: ObservabilityEvent) -> None:
+ payload = dict(event.payload)
+ for key in ("request_id", "account_id", "user_id", "agent_id"):
+ if payload.get(key) is None:
+ value = getattr(event, key)
+ if value is not None:
+ payload[key] = value
+ handler(event.event_name, payload)
+
+ return _subscriber
diff --git a/openviking/observability/http_observability_middleware.py b/openviking/observability/http_observability_middleware.py
index ce30a1085..3febc6c28 100644
--- a/openviking/observability/http_observability_middleware.py
+++ b/openviking/observability/http_observability_middleware.py
@@ -194,6 +194,12 @@ class ShardedInflightCounter:
result.update(self._shards[i])
return result
+ def clear(self) -> None:
+ """Clear all inflight counters. Intended for tests and shutdown hygiene."""
+ for i in range(self._num_shards):
+ with self._locks[i]:
+ self._shards[i].clear()
+
# Global sharded inflight counter instance
# Using 16 shards provides good balance between memory and contention reduction
@@ -677,6 +683,10 @@ def apply_http_metrics_finalize(
status=str(root_attrs.http_status_code or 500),
duration_seconds=elapsed,
account_id=final_account_id,
+ request_id=root_attrs.request_id,
+ user_id=root_attrs.user_id,
+ agent_id=root_attrs.agent_id,
+ url_path=root_attrs.url_path,
)
except (TypeError, ValueError, AttributeError) as e:
diff --git a/openviking/observability/usage_audit/README.md b/openviking/observability/usage_audit/README.md
new file mode 100644
index 000000000..f27a5777f
--- /dev/null
+++ b/openviking/observability/usage_audit/README.md
@@ -0,0 +1,419 @@
+# Usage/Audit 使用说明
+
+Usage/Audit 是 OpenViking Server 给 Console 使用的产品统计与请求审计模块。它复用
+OpenViking 已有的 observability 事件,不要求 Console 直接依赖 Prometheus,也不会在正常
+API 请求链路里同步写统计库。
+
+## 适用场景
+
+当前模块主要服务 Console P0 页面:
+
+- 总览页首屏:上下文数据量、今日 Token、今日检索、Agent 概览
+- Token 趋势:按日期范围查询模型 Token 消耗
+- 上下文提交热力图:按日期和小时段查询上下文写入活动
+- 请求日志:分页查询请求明细、状态、耗时和成功率
+
+这套数据是产品语义数据,不是运维指标。QPS、latency histogram、queue depth、cache
+hit/miss 等仍然应该看 Prometheus metrics。
+
+## 工作方式
+
+数据流如下:
+
+```text
+业务请求 / 模型调用
+ |
+ v
+Observability Event Bus
+ |
+ +--> Metrics subscriber
+ |
+ +--> Usage/Audit subscriber
+ |
+ v
+ Usage/Audit worker
+ |
+ v
+ Usage/Audit store
+ |
+ v
+ /api/v1/console/* BFF
+```
+
+关键点:
+
+- Usage/Audit 订阅共享事件总线,不重复散落 Console 专用打点。
+- `server.observability.metrics.enabled=false` 不影响 Usage/Audit。
+- 请求路径只做非阻塞事件投递;写库由后台 worker 批量完成。
+- worker 使用 bounded queue;队列满时会丢弃统计事件并增加 `dropped_count`。
+- 服务关闭时会尽量 flush 剩余事件;如果已有 batch 正在写入,会等待它完成,避免尾部审计丢失或重复写入。
+
+## 配置
+
+默认启用 Usage/Audit。最小配置可以不写任何字段。
+
+完整配置示例:
+
+```json
+{
+ "server": {
+ "observability": {
+ "usage_audit": {
+ "enabled": true,
+ "backend": "sqlite",
+ "sqlite_path": "/path/to/usage_audit.sqlite3",
+ "queue_size": 10000,
+ "batch_size": 500,
+ "flush_interval_seconds": 1.0,
+ "shutdown_flush_timeout_seconds": 3.0,
+ "usage_retention_days": 14,
+ "audit_retention_days": 7,
+ "audit_retention_per_account": 1000,
+ "timezone": "local",
+ "inventory_ttl_seconds": 10.0
+ }
+ }
+ }
+}
+```
+
+字段说明:
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `true` | 是否启用 Usage/Audit |
+| `backend` | `"sqlite"` | 当前仅支持 SQLite |
+| `sqlite_path` | `null` | SQLite 文件路径;为空时使用 OpenViking workspace 下的 `usage_audit.sqlite3` |
+| `queue_size` | `10000` | 后台写入队列大小 |
+| `batch_size` | `500` | 单次批量写入的最大事件数 |
+| `flush_interval_seconds` | `1.0` | worker 定时 flush 间隔 |
+| `shutdown_flush_timeout_seconds` | `3.0` | 服务关闭时 flush 等待时间 |
+| `usage_retention_days` | `14` | 统计聚合数据保留天数,包含 Token、检索、上下文写入热力图、Agent 活跃;`0` 表示不按天裁剪 |
+| `audit_retention_days` | `7` | 请求审计日志保留天数;`0` 表示不按天裁剪 |
+| `audit_retention_per_account` | `1000` | 每个 account 保留的最新请求审计条数;`0` 表示不按条数裁剪 |
+| `timezone` | `"local"` | 统计日期使用的时区;可填 `"local"`、`"UTC"` 或 IANA 时区名 |
+| `inventory_ttl_seconds` | `10.0` | 上下文当前数据量查询缓存时间 |
+
+本地版使用 SQLite 没问题。分布式生产环境如果多实例同时提供 Console,建议后续增加共享
+store backend,而不是让多个实例各写各的本地 SQLite。
+
+## 数据口径
+
+### Token
+
+来自模型调用事件:
+
+| 事件 | 当前 Console 展示口径 |
+| --- | --- |
+| `vlm.call` | `prompt_tokens` 计入 `vlm_input`,`completion_tokens` 计入 `vlm_output` |
+| `embedding.call` | `prompt_tokens` 计入 `embedding_input` |
+| `rerank.call` | 已可落库,当前 Console summary/series 暂不展示 |
+
+### 今日检索
+
+来自 HTTP 请求完成事件 `http.request`:
+
+| API route | operation |
+| --- | --- |
+| `POST /api/v1/search/find` | `find` |
+| `POST /api/v1/search/search` | `search` |
+
+`2xx` 和 `3xx` 记为 `success`,`4xx/5xx` 记为 `error`。Dashboard 今日检索只展示成功请求数。
+
+### 上下文提交热力图
+
+来自成功的公开写请求:
+
+| API route | operation |
+| --- | --- |
+| `POST /api/v1/resources` | `add_resource` |
+| `POST /api/v1/skills` | `add_skill` |
+| `POST /api/v1/sessions/{session_id}/messages` | `session_add_message` |
+| `POST /api/v1/sessions/{session_id}/commit` | `session_commit` |
+
+只有 `2xx/3xx` 会进入上下文提交统计。
+
+### 上下文数据量
+
+Dashboard 首屏的上下文数据量是当前状态查询,不是历史事件累加:
+
+- `files`:读取 `viking://resources` 的 `stat.count`
+- `skills`:读取当前 Agent `skills` 根目录的 `stat.count`
+- `memories`:读取当前 User 和当前 Agent 的 `memories` 根目录 `stat.count` 后求和
+
+`stat.count` 是底层 `VikingFS.stat()` 暴露的目录计数字段。Usage/Audit 不自己拼
+vector filter,也不从历史写入事件累计当前库存。
+
+这部分会走 `inventory_ttl_seconds` 缓存,避免 Console 刷新频繁打到底层存储。业务根目录
+不存在时按 0 处理,避免新环境或空租户反复刷 warning。
+
+### 请求审计
+
+请求审计来自 `http.request`,保留字段:
+
+- `request_id`
+- `account_id`
+- `user_id`
+- `agent_id`
+- `method`
+- `route`
+- `api_type`
+- `status_code`
+- `duration_ms`
+- `created_at`
+
+以下 route 不进入审计:
+
+- `/metrics`
+- `/health`
+- `/ready`
+- `/docs`
+- `/docs/oauth2-redirect`
+- `/redoc`
+- `/openapi.json`
+- `/favicon.ico`
+- `/favicon.png`
+- `/apple-touch-icon.png`
+- `/console/*`
+- `/api/v1/console/*`
+
+## Console BFF API
+
+所有接口都在 OV Server 侧:
+
+```text
+/api/v1/console/*
+```
+
+Console 前端通过 Console server 的 allowlist proxy 访问:
+
+```text
+/console/api/v1/ov/console/dashboard/summary
+/console/api/v1/ov/console/tokens
+/console/api/v1/ov/console/context-commits
+/console/api/v1/ov/console/audit
+```
+
+权限要求:
+
+- `ROOT` 和 `ADMIN` 可以访问
+- 普通 `USER` 返回 `403 PERMISSION_DENIED`
+
+### Dashboard Summary
+
+```text
+GET /api/v1/console/dashboard/summary
+```
+
+返回示例:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "context_counts": {
+ "files": 12,
+ "skills": 3,
+ "memories": 8,
+ "total": 23
+ },
+ "today_tokens": {
+ "vlm_input": 1000,
+ "vlm_output": 500,
+ "embedding_input": 200,
+ "total": 1700
+ },
+ "today_retrievals": {
+ "find": 10,
+ "search": 4,
+ "total": 14
+ },
+ "agent_overview": {
+ "total": 2,
+ "items": [
+ {
+ "agent_id": "agent-1",
+ "last_seen_at": "2026-05-12T10:00:00+08:00"
+ }
+ ]
+ }
+ }
+}
+```
+
+如果 Usage/Audit 被关闭或尚未初始化,返回:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "enabled": false,
+ "message": "Usage/Audit is disabled or not initialized."
+ }
+}
+```
+
+### Token Series
+
+```text
+GET /api/v1/console/tokens?start_date=2026-05-01&end_date=2026-05-12&bucket=day
+```
+
+参数:
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `start_date` | 是 | 开始日期,格式 `YYYY-MM-DD` |
+| `end_date` | 是 | 结束日期,格式 `YYYY-MM-DD` |
+| `bucket` | 否 | 当前仅支持 `day` |
+
+返回中会补齐日期范围内没有数据的日期。
+
+### Context Commits
+
+```text
+GET /api/v1/console/context-commits?start_date=2026-05-01&end_date=2026-05-12&bucket=4h
+```
+
+参数:
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `start_date` | 是 | 开始日期,格式 `YYYY-MM-DD` |
+| `end_date` | 是 | 结束日期,格式 `YYYY-MM-DD` |
+| `bucket` | 否 | `hour` 或 `4h`,默认 `hour` |
+
+返回中会补齐日期和小时段范围内没有数据的 bucket。
+
+### Audit Logs
+
+```text
+GET /api/v1/console/audit?page=1&page_size=20&status=success,error&api_type=search.find
+```
+
+参数:
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `page` | 否 | 页码,从 `1` 开始 |
+| `page_size` | 否 | 每页条数,范围 `1..100` |
+| `request_id` | 否 | 精确匹配 request id |
+| `status` | 否 | 可重复传,也可逗号分隔 |
+| `api_type` | 否 | 可重复传,也可逗号分隔 |
+
+`status` 支持:
+
+- `success` / `ok`:`2xx` 和 `3xx`
+- `2xx`
+- `3xx`
+- `error` / `failed`:`4xx/5xx`
+- `4xx`、`5xx` 等通配段
+- 具体状态码,例如 `404`
+
+返回字段:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "total": 123,
+ "success_rate": 0.98,
+ "page": 1,
+ "page_size": 20,
+ "items": []
+ }
+}
+```
+
+`success_rate` 使用当前筛选条件下的 `2xx/3xx` 占比。
+
+## 本地验证
+
+启动 server 后,可以通过请求触发数据:
+
+```bash
+curl -X POST "http://127.0.0.1:1933/api/v1/search/find" \
+ -H "Authorization: Bearer $OPENVIKING_API_KEY" \
+ -H "X-OpenViking-Account: default" \
+ -H "X-OpenViking-User: default" \
+ -H "X-OpenViking-Agent: default" \
+ -H "Content-Type: application/json" \
+ -d '{"query":"hello","limit":3}'
+```
+
+查询 Console BFF:
+
+```bash
+curl "http://127.0.0.1:1933/api/v1/console/dashboard/summary" \
+ -H "Authorization: Bearer $OPENVIKING_API_KEY" \
+ -H "X-OpenViking-Account: default" \
+ -H "X-OpenViking-User: default" \
+ -H "X-OpenViking-Agent: default"
+```
+
+如果使用 Console server,则访问 `/console/api/v1/ov/console/*` 代理路径。
+
+## 测试
+
+相关单测:
+
+```bash
+.venv/bin/python -m pytest \
+ tests/observability/test_events.py \
+ tests/observability/test_usage_audit_store.py \
+ tests/observability/test_usage_audit_worker.py \
+ tests/observability/test_console_router.py \
+ tests/observability/test_usage_audit_runtime.py \
+ tests/observability/test_usage_audit_inventory.py \
+ tests/misc/test_console_proxy.py
+```
+
+相关 lint:
+
+```bash
+.venv/bin/python -m ruff check \
+ openviking/observability/events.py \
+ openviking/observability/usage_audit \
+ openviking/server/routers/console.py \
+ openviking/console/app.py \
+ tests/observability \
+ tests/misc/test_console_proxy.py
+```
+
+## 常见问题
+
+### Console 查询为什么返回 `enabled=false`?
+
+通常是 `server.observability.usage_audit.enabled=false`,或者 Usage/Audit runtime 没有初始化成功。
+先看 server 启动日志中是否有 `Usage/Audit store initialized with sqlite backend`。
+
+### 为什么 Dashboard 今天没有 Token?
+
+确认模型调用事件是否触发:
+
+- VLM 需要产生 `vlm.call`
+- Embedding 需要产生 `embedding.call`
+
+统计日期使用 `server.observability.usage_audit.timezone`。如果时区配置不同,数据可能落在另一天。
+
+### 为什么请求日志里没有 Console 自己的请求?
+
+这是预期行为。`/api/v1/console/*` 和 `/console/*` 会被排除,避免 Console 页面刷新污染产品请求审计。
+
+### 为什么普通用户访问 Console BFF 是 403?
+
+Console BFF 查询的是账号级聚合和审计明细,当前只允许 `ROOT` / `ADMIN` 访问。
+
+### SQLite 文件在哪里?
+
+如果没有配置 `sqlite_path`,默认在 OpenViking workspace 下:
+
+```text
+<workspace>/usage_audit.sqlite3
+```
+
+可以通过 `server.observability.usage_audit.sqlite_path` 显式指定。
+
+### 生产多实例怎么部署?
+
+当前实现只有 SQLite backend,更适合单机本地版。多实例生产环境需要共享 store backend,避免每个实例只持有自己的局部统计。后续扩展时应实现 `UsageAuditStore` 协议,而不是改 Console BFF。
diff --git a/openviking/observability/usage_audit/__init__.py b/openviking/observability/usage_audit/__init__.py
new file mode 100644
index 000000000..ce7ae1ed7
--- /dev/null
+++ b/openviking/observability/usage_audit/__init__.py
@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Product usage and audit projections."""
+
+from .runtime import init_usage_audit_from_server_config, shutdown_usage_audit
+
+__all__ = ["init_usage_audit_from_server_config", "shutdown_usage_audit"]
diff --git a/openviking/observability/usage_audit/api_service.py b/openviking/observability/usage_audit/api_service.py
new file mode 100644
index 000000000..4f2cb38ae
--- /dev/null
+++ b/openviking/observability/usage_audit/api_service.py
@@ -0,0 +1,121 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Read service for product Usage/Audit APIs."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any
+
+from openviking.server.identity import RequestContext
+from openviking_cli.exceptions import InvalidArgumentError
+
+from .inventory import ContextInventoryProvider
+from .store import UsageAuditStore
+from .time import resolve_usage_timezone
+
+
+class UsageAuditQueryService:
+ """High-level query facade used by HTTP readers."""
+
+ def __init__(
+ self,
+ *,
+ store: UsageAuditStore,
+ inventory: ContextInventoryProvider,
+ timezone_name: str = "local",
+ ) -> None:
+ self._store = store
+ self._inventory = inventory
+ self._tz = resolve_usage_timezone(timezone_name)
+
+ def today(self) -> str:
+ """Return today's date in the configured usage/audit timezone."""
+ return datetime.now(self._tz).date().isoformat()
+
+ async def dashboard_summary(self, ctx: RequestContext) -> dict[str, Any]:
+ """Return all Dashboard top-card data."""
+ today = self.today()
+ context_counts = await self._inventory.get_counts(ctx)
+ today_tokens = await self._store.get_today_tokens(account_id=ctx.account_id, date=today)
+ today_retrievals = await self._store.get_today_retrievals(
+ account_id=ctx.account_id,
+ date=today,
+ )
+ agent_overview = await self._store.get_agent_overview(
+ account_id=ctx.account_id,
+ date=today,
+ limit=5,
+ )
+ return {
+ "context_counts": context_counts,
+ "today_tokens": today_tokens,
+ "today_retrievals": today_retrievals,
+ "agent_overview": agent_overview,
+ }
+
+ async def token_series(
+ self,
+ *,
+ ctx: RequestContext,
+ start_date: str,
+ end_date: str,
+ bucket: str,
+ ) -> dict[str, Any]:
+ """Return token usage series for a date range."""
+ self._validate_date_range(start_date, end_date)
+ items = await self._store.get_token_series(
+ account_id=ctx.account_id,
+ start_date=start_date,
+ end_date=end_date,
+ bucket=bucket,
+ )
+ return {"start_date": start_date, "end_date": end_date, "bucket": bucket, "items": items}
+
+ async def context_commits(
+ self,
+ *,
+ ctx: RequestContext,
+ start_date: str,
+ end_date: str,
+ bucket: str,
+ ) -> dict[str, Any]:
+ """Return context write heatmap rows for a date range."""
+ self._validate_date_range(start_date, end_date)
+ items = await self._store.get_context_commit_heatmap(
+ account_id=ctx.account_id,
+ start_date=start_date,
+ end_date=end_date,
+ bucket=bucket,
+ )
+ return {"start_date": start_date, "end_date": end_date, "bucket": bucket, "items": items}
+
+ async def audit_logs(
+ self,
+ *,
+ ctx: RequestContext,
+ request_id: str | None,
+ statuses: list[str],
+ api_types: list[str],
+ page: int,
+ page_size: int,
+ ) -> dict[str, Any]:
+ """Return filtered request audit rows."""
+ return await self._store.query_audit_logs(
+ account_id=ctx.account_id,
+ request_id=request_id,
+ statuses=statuses,
+ api_types=api_types,
+ page=max(int(page), 1),
+ page_size=min(max(int(page_size), 1), 100),
+ )
+
+ @staticmethod
+ def _validate_date_range(start_date: str, end_date: str) -> None:
+ try:
+ start = date.fromisoformat(start_date)
+ end = date.fromisoformat(end_date)
+ except ValueError as exc:
+ raise InvalidArgumentError("date must be in YYYY-MM-DD format") from exc
+ if end < start:
+ raise InvalidArgumentError("end_date must be greater than or equal to start_date")
diff --git a/openviking/observability/usage_audit/inventory.py b/openviking/observability/usage_audit/inventory.py
new file mode 100644
index 000000000..cf996ed9d
--- /dev/null
+++ b/openviking/observability/usage_audit/inventory.py
@@ -0,0 +1,80 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Context inventory provider for product dashboard counts."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+from openviking.core.namespace import canonical_agent_root, canonical_user_root
+from openviking.pyagfs.exceptions import AGFSNotFoundError
+from openviking.server.identity import RequestContext
+from openviking_cli.exceptions import NotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+class ContextInventoryProvider:
+ """Best-effort current-state context counter with a short TTL cache."""
+
+ def __init__(self, service: Any, *, ttl_seconds: float = 10.0) -> None:
+ self._service = service
+ self._ttl_seconds = max(float(ttl_seconds), 0.0)
+ self._cache: dict[tuple[str, str, str], tuple[float, dict[str, int]]] = {}
+ self._lock = asyncio.Lock()
+
+ async def get_counts(self, ctx: RequestContext) -> dict[str, int]:
+ """Return current context counts for the caller's tenant scope."""
+ key = (ctx.account_id, ctx.user.user_id, ctx.user.agent_id)
+ now = time.monotonic()
+ cached = self._cache.get(key)
+ if cached and now - cached[0] < self._ttl_seconds:
+ return dict(cached[1])
+
+ async with self._lock:
+ cached = self._cache.get(key)
+ if cached and now - cached[0] < self._ttl_seconds:
+ return dict(cached[1])
+ counts = await self._read_counts(ctx)
+ self._cache[key] = (time.monotonic(), counts)
+ return dict(counts)
+
+ async def _read_counts(self, ctx: RequestContext) -> dict[str, int]:
+ user_root = canonical_user_root(ctx)
+ agent_root = canonical_agent_root(ctx)
+
+ files, skills, user_memories, agent_memories = await asyncio.gather(
+ self._stat_count("viking://resources", ctx=ctx),
+ self._stat_count(f"{agent_root}/skills", ctx=ctx),
+ self._stat_count(f"{user_root}/memories", ctx=ctx),
+ self._stat_count(f"{agent_root}/memories", ctx=ctx),
+ )
+ memories = user_memories + agent_memories
+ return {
+ "files": files,
+ "skills": skills,
+ "memories": memories,
+ "total": files + skills + memories,
+ }
+
+ async def _stat_count(self, uri: str, *, ctx: RequestContext) -> int:
+ fs_service = getattr(self._service, "fs", None)
+ if fs_service is None:
+ return 0
+ try:
+ stat = await fs_service.stat(uri, ctx=ctx)
+ return max(int(stat.get("count") or 0), 0)
+ except (FileNotFoundError, AGFSNotFoundError, NotFoundError):
+ logger.debug("Usage/Audit inventory root does not exist: %s", uri)
+ return 0
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "Usage/Audit inventory stat count failed for uri=%s: %s",
+ uri,
+ exc,
+ exc_info=logger.isEnabledFor(logging.DEBUG),
+ )
+ return 0
diff --git a/openviking/observability/usage_audit/projection.py b/openviking/observability/usage_audit/projection.py
new file mode 100644
index 000000000..728219a56
--- /dev/null
+++ b/openviking/observability/usage_audit/projection.py
@@ -0,0 +1,329 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Projection from generic observability events into product usage/audit rows."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Sequence
+
+from openviking.observability.events import ObservabilityEvent
+
+UNKNOWN_IDENTITY = "__unknown__"
+AUDIT_EXCLUDED_ROUTES = frozenset(
+ {
+ "",
+ "/metrics",
+ "/health",
+ "/ready",
+ "/docs",
+ "/docs/oauth2-redirect",
+ "/redoc",
+ "/openapi.json",
+ "/favicon.ico",
+ "/favicon.png",
+ "/apple-touch-icon.png",
+ }
+)
+
+
+@dataclass(slots=True)
+class UsageAuditProjection:
+ """Write-ready rows derived from a batch of observability events."""
+
+ token_rows: dict[tuple, int] = field(default_factory=dict)
+ retrieval_rows: dict[tuple, tuple[int, int]] = field(default_factory=dict)
+ context_rows: dict[tuple, int] = field(default_factory=dict)
+ agent_rows: dict[tuple, tuple[int, str]] = field(default_factory=dict)
+ audit_rows: list[tuple] = field(default_factory=list)
+ touched_audit_accounts: set[str] = field(default_factory=set)
+
+
+def normalize_identity(value: Any, *, unknown: bool = False) -> str:
+ """Normalize optional identity fields into stable store keys."""
+ if value is None or value == "":
+ return UNKNOWN_IDENTITY if unknown else ""
+ return str(value)
+
+
+def safe_int(value: Any, default: int = 0) -> int:
+ """Best-effort integer conversion."""
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return default
+
+
+def safe_float(value: Any, default: float = 0.0) -> float:
+ """Best-effort float conversion."""
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ return default
+
+
+def project_events(
+ events: Sequence[ObservabilityEvent],
+ *,
+ tz,
+) -> UsageAuditProjection:
+ """Project generic events into product usage/audit rows."""
+ token_rows: defaultdict[tuple, int] = defaultdict(int)
+ retrieval_rows: defaultdict[tuple, tuple[int, int]] = defaultdict(lambda: (0, 0))
+ context_rows: defaultdict[tuple, int] = defaultdict(int)
+ agent_rows: dict[tuple, tuple[int, str]] = {}
+ audit_rows: list[tuple] = []
+ touched_audit_accounts: set[str] = set()
+
+ for event in events:
+ account_id = normalize_identity(event.account_id, unknown=True)
+ user_id = normalize_identity(event.user_id)
+ agent_id = normalize_identity(event.agent_id)
+ local_dt = _local_dt(event, tz)
+ event_date = local_dt.date().isoformat()
+ created_at = local_dt.isoformat()
+ payload = event.payload
+
+ if event.event_name == "vlm.call":
+ _add_token_rows(
+ token_rows,
+ account_id=account_id,
+ user_id=user_id,
+ agent_id=agent_id,
+ event_date=event_date,
+ source="vlm",
+ provider=payload.get("provider"),
+ model_name=payload.get("model_name"),
+ input_tokens=payload.get("prompt_tokens"),
+ output_tokens=payload.get("completion_tokens"),
+ )
+ continue
+
+ if event.event_name == "embedding.call":
+ _add_token_rows(
+ token_rows,
+ account_id=account_id,
+ user_id=user_id,
+ agent_id=agent_id,
+ event_date=event_date,
+ source="embedding",
+ provider=payload.get("provider"),
+ model_name=payload.get("model_name"),
+ input_tokens=payload.get("prompt_tokens"),
+ output_tokens=0,
+ )
+ continue
+
+ if event.event_name == "rerank.call":
+ _add_token_rows(
+ token_rows,
+ account_id=account_id,
+ user_id=user_id,
+ agent_id=agent_id,
+ event_date=event_date,
+ source="rerank",
+ provider=payload.get("provider"),
+ model_name=payload.get("model_name"),
+ input_tokens=payload.get("prompt_tokens"),
+ output_tokens=payload.get("completion_tokens"),
+ )
+ continue
+
+ if event.event_name == "http.request":
+ _project_http_request(
+ event,
+ event_date=event_date,
+ hour=int(local_dt.hour),
+ created_at=created_at,
+ retrieval_rows=retrieval_rows,
+ context_rows=context_rows,
+ audit_rows=audit_rows,
+ touched_audit_accounts=touched_audit_accounts,
+ agent_rows=agent_rows,
+ )
+
+ return UsageAuditProjection(
+ token_rows=dict(token_rows),
+ retrieval_rows=dict(retrieval_rows),
+ context_rows=dict(context_rows),
+ agent_rows=agent_rows,
+ audit_rows=audit_rows,
+ touched_audit_accounts=touched_audit_accounts,
+ )
+
+
+def _local_dt(event: ObservabilityEvent, tz) -> datetime:
+ ts = event.timestamp
+ if ts.tzinfo is None:
+ ts = ts.replace(tzinfo=timezone.utc)
+ return ts.astimezone(tz)
+
+
+def _add_token_rows(
+ rows: defaultdict[tuple, int],
+ *,
+ account_id: str,
+ user_id: str,
+ agent_id: str,
+ event_date: str,
+ source: str,
+ provider: Any,
+ model_name: Any,
+ input_tokens: Any,
+ output_tokens: Any,
+) -> None:
+ provider_key = normalize_identity(provider)
+ model_key = normalize_identity(model_name)
+ input_count = max(safe_int(input_tokens), 0)
+ output_count = max(safe_int(output_tokens), 0)
+ if input_count:
+ key = (
+ account_id,
+ user_id,
+ agent_id,
+ event_date,
+ source,
+ "input",
+ provider_key,
+ model_key,
+ )
+ rows[key] += input_count
+ if output_count:
+ key = (
+ account_id,
+ user_id,
+ agent_id,
+ event_date,
+ source,
+ "output",
+ provider_key,
+ model_key,
+ )
+ rows[key] += output_count
+
+
+def _project_http_request(
+ event: ObservabilityEvent,
+ *,
+ event_date: str,
+ hour: int,
+ created_at: str,
+ retrieval_rows: defaultdict[tuple, tuple[int, int]],
+ context_rows: defaultdict[tuple, int],
+ audit_rows: list[tuple],
+ touched_audit_accounts: set[str],
+ agent_rows: dict[tuple, tuple[int, str]],
+) -> None:
+ payload = event.payload
+ route = str(payload.get("route") or "")
+ method = str(payload.get("method") or "").upper()
+ if should_skip_audit_route(route):
+ return
+ status_code = safe_int(payload.get("status"), 500)
+ duration_ms = safe_float(payload.get("duration_ms"))
+ if duration_ms <= 0:
+ duration_ms = safe_float(payload.get("duration_seconds")) * 1000.0
+ audit_account = normalize_identity(
+ payload.get("account_id") or event.account_id,
+ unknown=True,
+ )
+ audit_user = normalize_identity(payload.get("user_id") or event.user_id) or None
+ audit_agent = normalize_identity(payload.get("agent_id") or event.agent_id) or None
+ row_user = audit_user or ""
+ row_agent = audit_agent or ""
+ status = "success" if 200 <= status_code < 400 else "error"
+
+ retrieval_operation = retrieval_operation_for_http(method, route)
+ if retrieval_operation:
+ key = (audit_account, row_user, row_agent, event_date, retrieval_operation, status)
+ prev_count, prev_results = retrieval_rows[key]
+ retrieval_rows[key] = (prev_count + 1, prev_results)
+
+ context_operation = context_write_operation_for_http(method, route, status_code)
+ if context_operation:
+ key = (audit_account, row_user, row_agent, event_date, hour, context_operation)
+ context_rows[key] += 1
+
+ audit_rows.append(
+ (
+ payload.get("request_id") or event.request_id,
+ audit_account,
+ audit_user,
+ audit_agent,
+ str(payload.get("method") or ""),
+ route,
+ str(payload.get("api_type") or derive_api_type(route)),
+ status_code,
+ duration_ms,
+ created_at,
+ )
+ )
+ touched_audit_accounts.add(audit_account)
+ if audit_agent:
+ agent_key = (audit_account, audit_agent, event_date)
+ prev_count, prev_seen = agent_rows.get(agent_key, (0, ""))
+ agent_rows[agent_key] = (
+ prev_count + 1,
+ max(prev_seen, created_at) if prev_seen else created_at,
+ )
+
+
+def should_skip_audit_route(route: str) -> bool:
+ """Return whether an HTTP route should be omitted from product audit."""
+ return (
+ route in AUDIT_EXCLUDED_ROUTES
+ or route.startswith("/console/")
+ or route.startswith("/api/v1/console/")
+ )
+
+
+def retrieval_operation_for_http(method: str, route: str) -> str | None:
+ """Map successful public search APIs from `http.request` into dashboard counters."""
+ if method != "POST":
+ return None
+ if route == "/api/v1/search/find":
+ return "find"
+ if route == "/api/v1/search/search":
+ return "search"
+ return None
+
+
+def context_write_operation_for_http(method: str, route: str, status_code: int) -> str | None:
+ """Map successful write APIs from `http.request` into context-write heatmap buckets."""
+ if method != "POST" or not (200 <= status_code < 400):
+ return None
+ if route == "/api/v1/resources":
+ return "add_resource"
+ if route == "/api/v1/skills":
+ return "add_skill"
+ if route == "/api/v1/sessions/{session_id}/messages":
+ return "session.add_message"
+ if route == "/api/v1/sessions/{session_id}/commit":
+ return "session.commit"
+ return None
+
+
+def derive_api_type(route: str) -> str:
+ """Derive the stable product-facing API type from a route template."""
+ if route == "/api/v1/search/find":
+ return "search.find"
+ if route == "/api/v1/search/search":
+ return "search.search"
+ prefix_map = {
+ "/api/v1/resources": "resources",
+ "/api/v1/skills": "skills",
+ "/api/v1/sessions": "sessions",
+ "/api/v1/fs": "filesystem",
+ "/api/v1/content": "content",
+ "/api/v1/admin": "admin",
+ "/api/v1/tasks": "tasks",
+ }
+ for prefix, api_type in prefix_map.items():
+ if route == prefix or route.startswith(prefix + "/"):
+ return api_type
+ parts = [part for part in route.split("/") if part]
+ if len(parts) >= 3 and parts[0] == "api" and parts[1] == "v1":
+ return parts[2]
+ return "unknown"
diff --git a/openviking/observability/usage_audit/runtime.py b/openviking/observability/usage_audit/runtime.py
new file mode 100644
index 000000000..bc9312344
--- /dev/null
+++ b/openviking/observability/usage_audit/runtime.py
@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Runtime bootstrap for product Usage/Audit projections."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from openviking.observability.events import register_event_subscriber, unregister_event_subscriber
+from openviking.server.config import ServerConfig
+from openviking_cli.utils.config import get_openviking_config
+from openviking_cli.utils.config.consts import DEFAULT_CONFIG_DIR
+
+from .api_service import UsageAuditQueryService
+from .inventory import ContextInventoryProvider
+from .sqlite_store import SQLiteUsageAuditStore
+from .store import UsageAuditStore
+from .subscriber import UsageAuditSubscriber
+from .worker import UsageAuditWorker
+
+logger = logging.getLogger(__name__)
+
+_SUBSCRIBER_NAME = "usage_audit"
+
+
+@dataclass(slots=True)
+class UsageAuditRuntime:
+ """Container for active Usage/Audit runtime objects."""
+
+ store: UsageAuditStore
+ worker: UsageAuditWorker
+ api_service: UsageAuditQueryService
+ shutdown_flush_timeout_seconds: float
+
+
+def _resolve_sqlite_path(config: ServerConfig) -> Path:
+ configured = config.observability.usage_audit.sqlite_path
+ if configured:
+ return Path(configured).expanduser().resolve()
+ try:
+ ov_config = get_openviking_config()
+ workspace = Path(ov_config.storage.workspace).expanduser().resolve()
+ except Exception: # noqa: BLE001
+ workspace = DEFAULT_CONFIG_DIR
+ return workspace / "usage_audit.sqlite3"
+
+
+async def init_usage_audit_from_server_config(
+ config: ServerConfig,
+ *,
+ app: Any = None,
+ service: Any = None,
+) -> UsageAuditRuntime | None:
+ """Initialize Usage/Audit store, worker, and event subscriber."""
+ usage_config = config.observability.usage_audit
+ unregister_event_subscriber(_SUBSCRIBER_NAME)
+
+ if not usage_config.enabled:
+ if app is not None:
+ app.state.usage_audit_runtime = None
+ return None
+
+ store = SQLiteUsageAuditStore(
+ _resolve_sqlite_path(config),
+ usage_retention_days=usage_config.usage_retention_days,
+ audit_retention_days=usage_config.audit_retention_days,
+ audit_retention_per_account=usage_config.audit_retention_per_account,
+ timezone_name=usage_config.timezone,
+ )
+ await store.initialize()
+
+ worker = UsageAuditWorker(
+ store,
+ queue_size=usage_config.queue_size,
+ batch_size=usage_config.batch_size,
+ flush_interval_seconds=usage_config.flush_interval_seconds,
+ )
+ await worker.start()
+ register_event_subscriber(_SUBSCRIBER_NAME, UsageAuditSubscriber(worker))
+
+ inventory = ContextInventoryProvider(
+ service,
+ ttl_seconds=usage_config.inventory_ttl_seconds,
+ )
+ api_service = UsageAuditQueryService(
+ store=store,
+ inventory=inventory,
+ timezone_name=usage_config.timezone,
+ )
+ runtime = UsageAuditRuntime(
+ store=store,
+ worker=worker,
+ api_service=api_service,
+ shutdown_flush_timeout_seconds=usage_config.shutdown_flush_timeout_seconds,
+ )
+ if app is not None:
+ app.state.usage_audit_runtime = runtime
+ logger.info("Usage/Audit store initialized with sqlite backend")
+ return runtime
+
+
+async def shutdown_usage_audit(*, app: Any = None) -> None:
+ """Shutdown Usage/Audit runtime if it is attached to the FastAPI app."""
+ unregister_event_subscriber(_SUBSCRIBER_NAME)
+ runtime = getattr(getattr(app, "state", None), "usage_audit_runtime", None)
+ if runtime is None:
+ return
+ try:
+ await runtime.worker.close(timeout_seconds=runtime.shutdown_flush_timeout_seconds)
+ finally:
+ await runtime.store.close()
+ app.state.usage_audit_runtime = None
diff --git a/openviking/observability/usage_audit/schema.py b/openviking/observability/usage_audit/schema.py
new file mode 100644
index 000000000..45d5f046c
--- /dev/null
+++ b/openviking/observability/usage_audit/schema.py
@@ -0,0 +1,86 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""SQLite schema for product usage/audit projections."""
+
+SQLITE_SCHEMA = """
+CREATE TABLE IF NOT EXISTS usage_token_daily (
+ account_id TEXT NOT NULL,
+ user_id TEXT NOT NULL,
+ agent_id TEXT NOT NULL,
+ date TEXT NOT NULL,
+ source TEXT NOT NULL,
+ token_type TEXT NOT NULL,
+ provider TEXT NOT NULL,
+ model_name TEXT NOT NULL,
+ token_count INTEGER NOT NULL DEFAULT 0,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (
+ account_id, user_id, agent_id, date, source, token_type, provider, model_name
+ )
+);
+CREATE INDEX IF NOT EXISTS idx_usage_token_account_date
+ ON usage_token_daily(account_id, date);
+
+CREATE TABLE IF NOT EXISTS usage_retrieval_daily (
+ account_id TEXT NOT NULL,
+ user_id TEXT NOT NULL,
+ agent_id TEXT NOT NULL,
+ date TEXT NOT NULL,
+ operation TEXT NOT NULL,
+ status TEXT NOT NULL,
+ request_count INTEGER NOT NULL DEFAULT 0,
+ result_count INTEGER NOT NULL DEFAULT 0,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (account_id, user_id, agent_id, date, operation, status)
+);
+CREATE INDEX IF NOT EXISTS idx_usage_retrieval_account_date
+ ON usage_retrieval_daily(account_id, date);
+
+CREATE TABLE IF NOT EXISTS usage_context_write_bucket (
+ account_id TEXT NOT NULL,
+ user_id TEXT NOT NULL,
+ agent_id TEXT NOT NULL,
+ date TEXT NOT NULL,
+ hour_bucket INTEGER NOT NULL,
+ operation TEXT NOT NULL,
+ count INTEGER NOT NULL DEFAULT 0,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (account_id, user_id, agent_id, date, hour_bucket, operation)
+);
+CREATE INDEX IF NOT EXISTS idx_usage_context_write_account_date
+ ON usage_context_write_bucket(account_id, date, hour_bucket);
+
+CREATE TABLE IF NOT EXISTS usage_agent_activity_daily (
+ account_id TEXT NOT NULL,
+ agent_id TEXT NOT NULL,
+ date TEXT NOT NULL,
+ request_count INTEGER NOT NULL DEFAULT 0,
+ last_seen_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL,
+ PRIMARY KEY (account_id, agent_id, date)
+);
+CREATE INDEX IF NOT EXISTS idx_usage_agent_activity_account_date
+ ON usage_agent_activity_daily(account_id, date, last_seen_at);
+
+CREATE TABLE IF NOT EXISTS request_audit (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ request_id TEXT,
+ account_id TEXT NOT NULL,
+ user_id TEXT,
+ agent_id TEXT,
+ method TEXT NOT NULL,
+ route TEXT NOT NULL,
+ api_type TEXT NOT NULL,
+ status_code INTEGER NOT NULL,
+ duration_ms REAL NOT NULL,
+ created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_request_audit_account_created
+ ON request_audit(account_id, created_at DESC, id DESC);
+CREATE INDEX IF NOT EXISTS idx_request_audit_request_id
+ ON request_audit(request_id);
+CREATE INDEX IF NOT EXISTS idx_request_audit_account_api
+ ON request_audit(account_id, api_type);
+CREATE INDEX IF NOT EXISTS idx_request_audit_account_status
+ ON request_audit(account_id, status_code);
+"""
diff --git a/openviking/observability/usage_audit/sqlite_store.py b/openviking/observability/usage_audit/sqlite_store.py
new file mode 100644
index 000000000..202228f6e
--- /dev/null
+++ b/openviking/observability/usage_audit/sqlite_store.py
@@ -0,0 +1,558 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""SQLite implementation of the product usage/audit store."""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+from openviking.observability.events import ObservabilityEvent
+
+from .projection import UsageAuditProjection, project_events, safe_int
+from .schema import SQLITE_SCHEMA
+from .time import resolve_usage_timezone
+
+
+def _date_range(start_date: str, end_date: str) -> Iterable[str]:
+ start = date.fromisoformat(start_date)
+ end = date.fromisoformat(end_date)
+ if end < start:
+ return []
+ days = (end - start).days
+ return ((start + timedelta(days=offset)).isoformat() for offset in range(days + 1))
+
+
+class SQLiteUsageAuditStore:
+ """Async wrapper around a SQLite usage/audit database."""
+
+ def __init__(
+ self,
+ db_path: Path,
+ *,
+ usage_retention_days: int = 14,
+ audit_retention_days: int = 7,
+ audit_retention_per_account: int = 1000,
+ timezone_name: str = "local",
+ ) -> None:
+ self._db_path = Path(db_path)
+ self._usage_retention_days = int(usage_retention_days)
+ self._audit_retention_days = int(audit_retention_days)
+ self._audit_retention_per_account = int(audit_retention_per_account)
+ self._tz = resolve_usage_timezone(timezone_name)
+ self._conn: sqlite3.Connection | None = None
+ self._lock = asyncio.Lock()
+
+ async def initialize(self) -> None:
+ await asyncio.to_thread(self._initialize_sync)
+
+ def _initialize_sync(self) -> None:
+ self._db_path.parent.mkdir(parents=True, exist_ok=True)
+ conn = sqlite3.connect(
+ self._db_path,
+ isolation_level=None,
+ check_same_thread=False,
+ )
+ conn.row_factory = sqlite3.Row
+ conn.execute("PRAGMA journal_mode=WAL")
+ conn.execute("PRAGMA synchronous=NORMAL")
+ conn.execute("PRAGMA foreign_keys=ON")
+ conn.executescript(SQLITE_SCHEMA)
+ self._conn = conn
+
+ async def close(self) -> None:
+ await asyncio.to_thread(self._close_sync)
+
+ def _close_sync(self) -> None:
+ if self._conn is not None:
+ self._conn.close()
+ self._conn = None
+
+ async def record_batch(self, events: Sequence[ObservabilityEvent]) -> None:
+ if not events:
+ return
+ projection = project_events(events, tz=self._tz)
+ async with self._lock:
+ await asyncio.to_thread(self._record_projection_sync, projection)
+
+ def _record_projection_sync(self, projection: UsageAuditProjection) -> None:
+ assert self._conn is not None
+ updated_at = datetime.now(timezone.utc).isoformat()
+ conn = self._conn
+ conn.execute("BEGIN")
+ try:
+ self._write_token_rows(conn, projection.token_rows, updated_at)
+ self._write_retrieval_rows(conn, projection.retrieval_rows, updated_at)
+ self._write_context_rows(conn, projection.context_rows, updated_at)
+ self._write_agent_rows(conn, projection.agent_rows, updated_at)
+ self._write_audit_rows(conn, projection.audit_rows)
+ self._trim_usage_rows(conn, self._usage_max_dates(projection))
+ self._trim_audit_rows(conn, projection.touched_audit_accounts)
+ conn.execute("COMMIT")
+ except Exception:
+ conn.execute("ROLLBACK")
+ raise
+
+ @staticmethod
+ def _write_token_rows(conn, rows: dict[tuple, int], updated_at: str) -> None:
+ conn.executemany(
+ """
+ INSERT INTO usage_token_daily (
+ account_id, user_id, agent_id, date, source, token_type,
+ provider, model_name, token_count, updated_at
+ )
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT (
+ account_id, user_id, agent_id, date, source, token_type, provider, model_name
+ )
+ DO UPDATE SET
+ token_count = token_count + excluded.token_count,
+ updated_at = excluded.updated_at
+ """,
+ [(*key, value, updated_at) for key, value in rows.items() if value > 0],
+ )
+
+ @staticmethod
+ def _write_retrieval_rows(conn, rows: dict[tuple, tuple[int, int]], updated_at: str) -> None:
+ conn.executemany(
+ """
+ INSERT INTO usage_retrieval_daily (
+ account_id, user_id, agent_id, date, operation, status,
+ request_count, result_count, updated_at
+ )
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT (account_id, user_id, agent_id, date, operation, status)
+ DO UPDATE SET
+ request_count = request_count + excluded.request_count,
+ result_count = result_count + excluded.result_count,
+ updated_at = excluded.updated_at
+ """,
+ [
+ (*key, count, result_count, updated_at)
+ for key, (count, result_count) in rows.items()
+ ],
+ )
+
+ @staticmethod
+ def _write_context_rows(conn, rows: dict[tuple, int], updated_at: str) -> None:
+ conn.executemany(
+ """
+ INSERT INTO usage_context_write_bucket (
+ account_id, user_id, agent_id, date, hour_bucket, operation, count, updated_at
+ )
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT (account_id, user_id, agent_id, date, hour_bucket, operation)
+ DO UPDATE SET
+ count = count + excluded.count,
+ updated_at = excluded.updated_at
+ """,
+ [(*key, value, updated_at) for key, value in rows.items() if value > 0],
+ )
+
+ @staticmethod
+ def _write_agent_rows(conn, rows: dict[tuple, tuple[int, str]], updated_at: str) -> None:
+ conn.executemany(
+ """
+ INSERT INTO usage_agent_activity_daily (
+ account_id, agent_id, date, request_count, last_seen_at, updated_at
+ )
+ VALUES (?, ?, ?, ?, ?, ?)
+ ON CONFLICT (account_id, agent_id, date)
+ DO UPDATE SET
+ request_count = request_count + excluded.request_count,
+ last_seen_at = MAX(last_seen_at, excluded.last_seen_at),
+ updated_at = excluded.updated_at
+ """,
+ [(*key, count, last_seen, updated_at) for key, (count, last_seen) in rows.items()],
+ )
+
+ @staticmethod
+ def _write_audit_rows(conn, rows: list[tuple]) -> None:
+ conn.executemany(
+ """
+ INSERT INTO request_audit (
+ request_id, account_id, user_id, agent_id, method, route,
+ api_type, status_code, duration_ms, created_at
+ )
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ """,
+ rows,
+ )
+
+ def _trim_audit_rows(self, conn, accounts: set[str]) -> None:
+ if self._audit_retention_days > 0:
+ max_dates = self._audit_max_dates(conn, accounts)
+ for account_id, cutoff_date in self._cutoff_dates(
+ max_dates,
+ retention_days=self._audit_retention_days,
+ ).items():
+ conn.execute(
+ """
+ DELETE FROM request_audit
+ WHERE account_id = ? AND substr(created_at, 1, 10) < ?
+ """,
+ (account_id, cutoff_date),
+ )
+ if self._audit_retention_per_account <= 0:
+ return
+ for account_id in accounts:
+ conn.execute(
+ """
+ DELETE FROM request_audit
+ WHERE account_id = ?
+ AND id NOT IN (
+ SELECT id FROM request_audit
+ WHERE account_id = ?
+ ORDER BY id DESC
+ LIMIT ?
+ )
+ """,
+ (account_id, account_id, self._audit_retention_per_account),
+ )
+
+ def _trim_usage_rows(self, conn, max_dates_by_account: dict[str, str]) -> None:
+ cutoff_by_account = self._cutoff_dates(
+ max_dates_by_account,
+ retention_days=self._usage_retention_days,
+ )
+ for account_id, cutoff_date in cutoff_by_account.items():
+ for table in (
+ "usage_token_daily",
+ "usage_retrieval_daily",
+ "usage_context_write_bucket",
+ "usage_agent_activity_daily",
+ ):
+ conn.execute(
+ f"DELETE FROM {table} WHERE account_id = ? AND date < ?",
+ (account_id, cutoff_date),
+ )
+
+ @staticmethod
+ def _usage_max_dates(projection: UsageAuditProjection) -> dict[str, str]:
+ max_dates: dict[str, str] = {}
+ SQLiteUsageAuditStore._merge_max_dates(max_dates, projection.token_rows, date_index=3)
+ SQLiteUsageAuditStore._merge_max_dates(max_dates, projection.retrieval_rows, date_index=3)
+ SQLiteUsageAuditStore._merge_max_dates(max_dates, projection.context_rows, date_index=3)
+ SQLiteUsageAuditStore._merge_max_dates(max_dates, projection.agent_rows, date_index=2)
+ return max_dates
+
+ @staticmethod
+ def _merge_max_dates(
+ target: dict[str, str], rows: dict[tuple, Any], *, date_index: int
+ ) -> None:
+ for key in rows:
+ account_id = str(key[0])
+ event_date = str(key[date_index])
+ if event_date > target.get(account_id, ""):
+ target[account_id] = event_date
+
+ @staticmethod
+ def _cutoff_dates(
+ max_dates_by_account: dict[str, str], *, retention_days: int
+ ) -> dict[str, str]:
+ if retention_days <= 0:
+ return {}
+ return {
+ account_id: (
+ date.fromisoformat(max_date) - timedelta(days=retention_days - 1)
+ ).isoformat()
+ for account_id, max_date in max_dates_by_account.items()
+ }
+
+ @staticmethod
+ def _audit_max_dates(conn, accounts: set[str]) -> dict[str, str]:
+ max_dates: dict[str, str] = {}
+ for account_id in accounts:
+ row = conn.execute(
+ """
+ SELECT MAX(substr(created_at, 1, 10)) AS max_date
+ FROM request_audit
+ WHERE account_id = ?
+ """,
+ (account_id,),
+ ).fetchone()
+ if row and row["max_date"]:
+ max_dates[account_id] = str(row["max_date"])
+ return max_dates
+
+ async def get_today_tokens(self, *, account_id: str, date: str) -> dict[str, int]:
+ async with self._lock:
+ return await asyncio.to_thread(self._get_today_tokens_sync, account_id, date)
+
+ def _get_today_tokens_sync(self, account_id: str, event_date: str) -> dict[str, int]:
+ assert self._conn is not None
+ cur = self._conn.execute(
+ """
+ SELECT source, token_type, SUM(token_count) AS total
+ FROM usage_token_daily
+ WHERE account_id = ? AND date = ?
+ GROUP BY source, token_type
+ """,
+ (account_id, event_date),
+ )
+ result = {"vlm_input": 0, "vlm_output": 0, "embedding_input": 0}
+ for row in cur.fetchall():
+ key = f"{row['source']}_{row['token_type']}"
+ if key in result:
+ result[key] = int(row["total"] or 0)
+ result["total"] = sum(result.values())
+ return result
+
+ async def get_today_retrievals(self, *, account_id: str, date: str) -> dict[str, int]:
+ async with self._lock:
+ return await asyncio.to_thread(self._get_today_retrievals_sync, account_id, date)
+
+ def _get_today_retrievals_sync(self, account_id: str, event_date: str) -> dict[str, int]:
+ assert self._conn is not None
+ cur = self._conn.execute(
+ """
+ SELECT operation, SUM(request_count) AS total
+ FROM usage_retrieval_daily
+ WHERE account_id = ? AND date = ? AND status = 'success'
+ GROUP BY operation
+ """,
+ (account_id, event_date),
+ )
+ result = {"find": 0, "search": 0}
+ for row in cur.fetchall():
+ operation = str(row["operation"])
+ if operation in result:
+ result[operation] = int(row["total"] or 0)
+ result["total"] = sum(result.values())
+ return result
+
+ async def get_agent_overview(
+ self, *, account_id: str, date: str, limit: int = 5
+ ) -> dict[str, Any]:
+ async with self._lock:
+ return await asyncio.to_thread(
+ self._get_agent_overview_sync, account_id, date, int(limit)
+ )
+
+ def _get_agent_overview_sync(
+ self, account_id: str, event_date: str, limit: int
+ ) -> dict[str, Any]:
+ assert self._conn is not None
+ total_cur = self._conn.execute(
+ """
+ SELECT COUNT(DISTINCT agent_id) AS total
+ FROM usage_agent_activity_daily
+ WHERE account_id = ? AND date = ?
+ """,
+ (account_id, event_date),
+ )
+ total = int(total_cur.fetchone()["total"] or 0)
+ cur = self._conn.execute(
+ """
+ SELECT agent_id, last_seen_at
+ FROM usage_agent_activity_daily
+ WHERE account_id = ? AND date = ?
+ ORDER BY last_seen_at DESC
+ LIMIT ?
+ """,
+ (account_id, event_date, limit),
+ )
+ return {
+ "total": total,
+ "items": [
+ {"agent_id": row["agent_id"], "last_seen_at": row["last_seen_at"]}
+ for row in cur.fetchall()
+ ],
+ }
+
+ async def get_token_series(
+ self, *, account_id: str, start_date: str, end_date: str, bucket: str
+ ) -> list[dict[str, Any]]:
+ async with self._lock:
+ return await asyncio.to_thread(
+ self._get_token_series_sync, account_id, start_date, end_date, bucket
+ )
+
+ def _get_token_series_sync(
+ self, account_id: str, start_date: str, end_date: str, bucket: str
+ ) -> list[dict[str, Any]]:
+ assert self._conn is not None
+ cur = self._conn.execute(
+ """
+ SELECT date, source, token_type, SUM(token_count) AS total
+ FROM usage_token_daily
+ WHERE account_id = ? AND date >= ? AND date <= ?
+ GROUP BY date, source, token_type
+ """,
+ (account_id, start_date, end_date),
+ )
+ by_date = {
+ d: {"date": d, "vlm_input": 0, "vlm_output": 0, "embedding_input": 0}
+ for d in _date_range(start_date, end_date)
+ }
+ for row in cur.fetchall():
+ key = f"{row['source']}_{row['token_type']}"
+ if key in {"vlm_input", "vlm_output", "embedding_input"}:
+ by_date.setdefault(
+ row["date"],
+ {"date": row["date"], "vlm_input": 0, "vlm_output": 0, "embedding_input": 0},
+ )[key] = int(row["total"] or 0)
+ return list(by_date.values())
+
+ async def get_context_commit_heatmap(
+ self, *, account_id: str, start_date: str, end_date: str, bucket: str
+ ) -> list[dict[str, Any]]:
+ async with self._lock:
+ return await asyncio.to_thread(
+ self._get_context_commit_heatmap_sync,
+ account_id,
+ start_date,
+ end_date,
+ bucket,
+ )
+
+ def _get_context_commit_heatmap_sync(
+ self, account_id: str, start_date: str, end_date: str, bucket: str
+ ) -> list[dict[str, Any]]:
+ assert self._conn is not None
+ bucket_size = 4 if bucket == "4h" else 1
+ cur = self._conn.execute(
+ """
+ SELECT date, hour_bucket, operation, SUM(count) AS total
+ FROM usage_context_write_bucket
+ WHERE account_id = ? AND date >= ? AND date <= ?
+ GROUP BY date, hour_bucket, operation
+ """,
+ (account_id, start_date, end_date),
+ )
+ rows: dict[tuple[str, int], dict[str, Any]] = {}
+ for event_date in _date_range(start_date, end_date):
+ for hour in range(0, 24, bucket_size):
+ rows[(event_date, hour)] = self._empty_context_row(event_date, hour)
+ for row in cur.fetchall():
+ hour = int(row["hour_bucket"])
+ normalized_hour = (hour // bucket_size) * bucket_size
+ key = (row["date"], normalized_hour)
+ item = rows.setdefault(key, self._empty_context_row(row["date"], normalized_hour))
+ operation_key = str(row["operation"]).replace(".", "_")
+ if operation_key in item:
+ item[operation_key] += int(row["total"] or 0)
+ item["total"] += int(row["total"] or 0)
+ return [rows[key] for key in sorted(rows)]
+
+ @staticmethod
+ def _empty_context_row(event_date: str, hour: int) -> dict[str, Any]:
+ return {
+ "date": event_date,
+ "hour": hour,
+ "total": 0,
+ "add_resource": 0,
+ "add_skill": 0,
+ "session_add_message": 0,
+ "session_commit": 0,
+ }
+
+ async def query_audit_logs(
+ self,
+ *,
+ account_id: str,
+ request_id: str | None = None,
+ statuses: list[str] | None = None,
+ api_types: list[str] | None = None,
+ page: int = 1,
+ page_size: int = 10,
+ ) -> dict[str, Any]:
+ async with self._lock:
+ return await asyncio.to_thread(
+ self._query_audit_logs_sync,
+ account_id,
+ request_id,
+ statuses or [],
+ api_types or [],
+ int(page),
+ int(page_size),
+ )
+
+ def _query_audit_logs_sync(
+ self,
+ account_id: str,
+ request_id: str | None,
+ statuses: list[str],
+ api_types: list[str],
+ page: int,
+ page_size: int,
+ ) -> dict[str, Any]:
+ assert self._conn is not None
+ where = ["account_id = ?"]
+ params: list[Any] = [account_id]
+ if request_id:
+ where.append("request_id = ?")
+ params.append(request_id)
+ status_clause, status_params = self._status_filter_sql(statuses)
+ if status_clause:
+ where.append(status_clause)
+ params.extend(status_params)
+ if api_types:
+ placeholders = ", ".join("?" for _ in api_types)
+ where.append(f"api_type IN ({placeholders})")
+ params.extend(api_types)
+ where_sql = " AND ".join(where)
+ summary = self._conn.execute(
+ f"""
+ SELECT
+ COUNT(*) AS total,
+ SUM(CASE WHEN status_code >= 200 AND status_code < 400 THEN 1 ELSE 0 END)
+ AS success
+ FROM request_audit
+ WHERE {where_sql}
+ """,
+ params,
+ ).fetchone()
+ total = int(summary["total"] or 0)
+ success = int(summary["success"] or 0)
+ offset = max(page - 1, 0) * page_size
+ rows = self._conn.execute(
+ f"""
+ SELECT request_id, account_id, user_id, agent_id, method, route, api_type,
+ status_code, duration_ms, created_at
+ FROM request_audit
+ WHERE {where_sql}
+ ORDER BY created_at DESC, id DESC
+ LIMIT ? OFFSET ?
+ """,
+ [*params, page_size, offset],
+ ).fetchall()
+ return {
+ "total": total,
+ "success_rate": (success / total) if total else 0.0,
+ "page": page,
+ "page_size": page_size,
+ "items": [dict(row) for row in rows],
+ }
+
+ @staticmethod
+ def _status_filter_sql(statuses: list[str]) -> tuple[str, list[Any]]:
+ if not statuses:
+ return "", []
+ clauses: list[str] = []
+ params: list[Any] = []
+ for status in statuses:
+ value = str(status).strip().lower()
+ if not value:
+ continue
+ if value in {"success", "ok"}:
+ clauses.append("(status_code >= 200 AND status_code < 400)")
+ elif value == "2xx":
+ clauses.append("(status_code >= 200 AND status_code < 300)")
+ elif value == "3xx":
+ clauses.append("(status_code >= 300 AND status_code < 400)")
+ elif value in {"error", "failed"}:
+ clauses.append("status_code >= 400")
+ elif value.endswith("xx") and len(value) == 3 and value[0].isdigit():
+ start = int(value[0]) * 100
+ clauses.append("(status_code >= ? AND status_code < ?)")
+ params.extend([start, start + 100])
+ else:
+ clauses.append("status_code = ?")
+ params.append(safe_int(value))
+ if not clauses:
+ return "", []
+ return "(" + " OR ".join(clauses) + ")", params
diff --git a/openviking/observability/usage_audit/store.py b/openviking/observability/usage_audit/store.py
new file mode 100644
index 000000000..2895fd84d
--- /dev/null
+++ b/openviking/observability/usage_audit/store.py
@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Store interfaces for product usage and audit projections."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, Sequence
+
+from openviking.observability.events import ObservabilityEvent
+
+
+class UsageAuditStore(Protocol):
+ """Persistence contract for product usage/audit data."""
+
+ async def initialize(self) -> None:
+ """Initialize the store."""
+
+ async def close(self) -> None:
+ """Close the store."""
+
+ async def record_batch(self, events: Sequence[ObservabilityEvent]) -> None:
+ """Persist a batch of observability events."""
+
+ async def get_today_tokens(self, *, account_id: str, date: str) -> dict[str, int]:
+ """Return token totals for one account and date."""
+
+ async def get_today_retrievals(self, *, account_id: str, date: str) -> dict[str, int]:
+ """Return successful find/search counts for one account and date."""
+
+ async def get_agent_overview(
+ self, *, account_id: str, date: str, limit: int = 5
+ ) -> dict[str, Any]:
+ """Return distinct agent count and recent agents for one account/date."""
+
+ async def get_token_series(
+ self, *, account_id: str, start_date: str, end_date: str, bucket: str
+ ) -> list[dict[str, Any]]:
+ """Return token series rows for a date range."""
+
+ async def get_context_commit_heatmap(
+ self, *, account_id: str, start_date: str, end_date: str, bucket: str
+ ) -> list[dict[str, Any]]:
+ """Return context write bucket rows for a date range."""
+
+ async def query_audit_logs(
+ self,
+ *,
+ account_id: str,
+ request_id: str | None = None,
+ statuses: list[str] | None = None,
+ api_types: list[str] | None = None,
+ page: int = 1,
+ page_size: int = 10,
+ ) -> dict[str, Any]:
+ """Query request audit rows with summary stats."""
diff --git a/openviking/observability/usage_audit/subscriber.py b/openviking/observability/usage_audit/subscriber.py
new file mode 100644
index 000000000..e68045375
--- /dev/null
+++ b/openviking/observability/usage_audit/subscriber.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Event bus subscriber for Usage/Audit persistence."""
+
+from __future__ import annotations
+
+from openviking.observability.events import ObservabilityEvent
+
+from .worker import UsageAuditWorker
+
+
+class UsageAuditSubscriber:
+ """Small sync adapter from event bus fan-out to the async worker queue."""
+
+ def __init__(self, worker: UsageAuditWorker) -> None:
+ self._worker = worker
+
+ def __call__(self, event: ObservabilityEvent) -> None:
+ self._worker.enqueue(event)
diff --git a/openviking/observability/usage_audit/time.py b/openviking/observability/usage_audit/time.py
new file mode 100644
index 000000000..4404ce159
--- /dev/null
+++ b/openviking/observability/usage_audit/time.py
@@ -0,0 +1,22 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Time helpers for Usage/Audit projections."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone, tzinfo
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_usage_timezone(timezone_name: str) -> tzinfo:
+ """Resolve configured Usage/Audit timezone with local fallback."""
+ if not timezone_name or timezone_name == "local":
+ return datetime.now().astimezone().tzinfo or timezone.utc
+ try:
+ return ZoneInfo(timezone_name)
+ except ZoneInfoNotFoundError:
+ logger.warning("Unknown usage_audit timezone %s; falling back to local", timezone_name)
+ return datetime.now().astimezone().tzinfo or timezone.utc
diff --git a/openviking/observability/usage_audit/worker.py b/openviking/observability/usage_audit/worker.py
new file mode 100644
index 000000000..869ad0c0e
--- /dev/null
+++ b/openviking/observability/usage_audit/worker.py
@@ -0,0 +1,158 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Background worker for Usage/Audit event persistence."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import suppress
+
+from openviking.observability.events import ObservabilityEvent
+
+from .store import UsageAuditStore
+
+logger = logging.getLogger(__name__)
+
+
+class UsageAuditWorker:
+ """Best-effort async batch writer for usage/audit events."""
+
+ def __init__(
+ self,
+ store: UsageAuditStore,
+ *,
+ queue_size: int = 10_000,
+ batch_size: int = 500,
+ flush_interval_seconds: float = 1.0,
+ ) -> None:
+ self._store = store
+ self._queue_size = max(int(queue_size), 1)
+ self._batch_size = max(int(batch_size), 1)
+ self._flush_interval_seconds = max(float(flush_interval_seconds), 0.1)
+ self._queue: asyncio.Queue[ObservabilityEvent] | None = None
+ self._loop: asyncio.AbstractEventLoop | None = None
+ self._task: asyncio.Task | None = None
+ self._current_batch: list[ObservabilityEvent] | None = None
+ self._closed = False
+ self.dropped_count = 0
+
+ async def start(self) -> None:
+ """Start the background flush loop."""
+ if self._task is not None:
+ return
+ self._loop = asyncio.get_running_loop()
+ self._queue = asyncio.Queue(maxsize=self._queue_size)
+ self._closed = False
+ self._task = asyncio.create_task(self._run(), name="openviking-usage-audit-worker")
+
+ def enqueue(self, event: ObservabilityEvent) -> None:
+ """Try to enqueue one event without blocking the caller."""
+ if self._closed or self._queue is None or self._loop is None:
+ self.dropped_count += 1
+ return
+
+ try:
+ running_loop = asyncio.get_running_loop()
+ except RuntimeError:
+ running_loop = None
+
+ if running_loop is self._loop:
+ self._enqueue_nowait(event)
+ return
+
+ self._loop.call_soon_threadsafe(self._enqueue_nowait, event)
+
+ def _enqueue_nowait(self, event: ObservabilityEvent) -> None:
+ queue = self._queue
+ if self._closed or queue is None:
+ self.dropped_count += 1
+ return
+ try:
+ queue.put_nowait(event)
+ except asyncio.QueueFull:
+ self.dropped_count += 1
+
+ async def _run(self) -> None:
+ while not self._closed:
+ batch: list[ObservabilityEvent] = []
+ try:
+ assert self._queue is not None
+ event = await asyncio.wait_for(
+ self._queue.get(),
+ timeout=self._flush_interval_seconds,
+ )
+ batch.append(event)
+ while len(batch) < self._batch_size:
+ try:
+ batch.append(self._queue.get_nowait())
+ except asyncio.QueueEmpty:
+ break
+ except asyncio.TimeoutError:
+ continue
+ except asyncio.CancelledError:
+ raise
+ except Exception as exc: # noqa: BLE001
+ logger.warning("Usage/Audit worker loop error: %s", exc)
+ continue
+
+ self._current_batch = batch
+ try:
+ await self._flush(batch)
+ except asyncio.CancelledError:
+ logger.warning(
+ "Usage/Audit worker cancelled with %d in-flight events",
+ len(batch),
+ )
+ raise
+ else:
+ self._current_batch = None
+
+ async def _flush(self, batch: list[ObservabilityEvent]) -> None:
+ if not batch:
+ return
+ try:
+ await self._store.record_batch(batch)
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "Usage/Audit batch flush failed: %s",
+ exc,
+ exc_info=logger.isEnabledFor(logging.DEBUG),
+ )
+
+ async def close(self, *, timeout_seconds: float = 3.0) -> None:
+ """Stop the worker and flush remaining queued events."""
+ self._closed = True
+ task = self._task
+ if task is not None:
+ try:
+ await asyncio.wait_for(asyncio.shield(task), timeout=timeout_seconds)
+ except asyncio.TimeoutError:
+ if self._current_batch:
+ logger.warning(
+ "Usage/Audit shutdown waiting for %d in-flight events",
+ len(self._current_batch),
+ )
+ await task
+ else:
+ task.cancel()
+ with suppress(asyncio.CancelledError):
+ await task
+ self._task = None
+
+ queue = self._queue
+ if queue is None:
+ return
+
+ remaining: list[ObservabilityEvent] = []
+ while True:
+ try:
+ remaining.append(queue.get_nowait())
+ except asyncio.QueueEmpty:
+ break
+
+ if remaining:
+ try:
+ await asyncio.wait_for(self._flush(remaining), timeout=timeout_seconds)
+ except asyncio.TimeoutError:
+ logger.warning("Usage/Audit shutdown flush timed out")
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 3bb3dae77..1561f95fe 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -30,6 +30,7 @@ from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Respo
from openviking.server.routers import (
admin_router,
bot_router,
+ console_router,
content_router,
debug_router,
filesystem_router,
@@ -214,10 +215,12 @@ def create_app(
from openviking.metrics.global_api import (
init_metrics_from_server_config,
)
+ from openviking.observability.usage_audit import init_usage_audit_from_server_config
init_metrics_from_server_config(config, app=app, service=service)
if config.observability.metrics.enabled:
logger.info("Prometheus metrics enabled at /metrics")
+ await init_usage_audit_from_server_config(config, app=app, service=service)
# Initialize OAuth 2.1 store + provider when enabled in OpenViking config.
# The store + provider instances were already constructed at app
@@ -273,7 +276,9 @@ def create_app(
# Cleanup
from openviking.metrics.global_api import shutdown_metrics_async
+ from openviking.observability.usage_audit import shutdown_usage_audit
+ await shutdown_usage_audit(app=app)
await shutdown_metrics_async(app=app)
task_tracker.stop_cleanup_loop()
if oauth_gc_task is not None:
@@ -472,6 +477,7 @@ def create_app(
app.include_router(resources_router)
app.include_router(filesystem_router)
app.include_router(content_router)
+ app.include_router(console_router)
app.include_router(search_router)
app.include_router(relations_router)
app.include_router(privacy_configs_router)
diff --git a/openviking/server/config.py b/openviking/server/config.py
index c8c054e5e..c198b14cc 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -3,7 +3,7 @@
"""Server configuration for OpenViking HTTP Server."""
import sys
-from typing import Dict, List, Optional
+from typing import Dict, List, Literal, Optional
from pydantic import BaseModel, Field, ValidationError
@@ -85,10 +85,30 @@ class MetricsConfig(BaseModel):
model_config = {"extra": "forbid"}
+class UsageAuditConfig(BaseModel):
+ """Product usage and audit projection configuration."""
+
+ enabled: bool = True
+ backend: Literal["sqlite"] = "sqlite"
+ sqlite_path: Optional[str] = None
+ queue_size: int = Field(10_000, gt=0)
+ batch_size: int = Field(500, gt=0)
+ flush_interval_seconds: float = Field(1.0, gt=0)
+ shutdown_flush_timeout_seconds: float = Field(3.0, gt=0)
+ usage_retention_days: int = Field(14, ge=0)
+ audit_retention_days: int = Field(7, ge=0)
+ audit_retention_per_account: int = Field(1000, ge=0)
+ timezone: str = "local"
+ inventory_ttl_seconds: float = Field(10.0, ge=0)
+
+ model_config = {"extra": "forbid"}
+
+
class ObservabilityConfig(BaseModel):
"""Server-side observability configuration."""
metrics: MetricsConfig = Field(default_factory=MetricsConfig)
+ usage_audit: UsageAuditConfig = Field(default_factory=UsageAuditConfig)
traces: OTelExporterConfig = Field(default_factory=OTelExporterConfig)
logs: OTelExporterConfig = Field(default_factory=OTelExporterConfig)
diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.py
index ec966483d..11a2a0f49 100644
--- a/openviking/server/routers/__init__.py
+++ b/openviking/server/routers/__init__.py
@@ -4,6 +4,7 @@
from openviking.server.routers.admin import router as admin_router
from openviking.server.routers.bot import router as bot_router
+from openviking.server.routers.console import router as console_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
@@ -27,6 +28,7 @@ __all__ = [
"resources_router",
"filesystem_router",
"content_router",
+ "console_router",
"search_router",
"relations_router",
"sessions_router",
diff --git a/openviking/server/routers/console.py b/openviking/server/routers/console.py
new file mode 100644
index 000000000..1b13d4143
--- /dev/null
+++ b/openviking/server/routers/console.py
@@ -0,0 +1,123 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Console BFF endpoints for usage and audit data."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Query, Request
+
+from openviking.server.auth import require_role
+from openviking.server.identity import RequestContext, Role
+from openviking.server.models import Response
+
+router = APIRouter(prefix="/api/v1/console", tags=["console"])
+
+
+def _split_multi(values: Optional[list[str]]) -> list[str]:
+ if not values:
+ return []
+ result: list[str] = []
+ for value in values:
+ result.extend(part.strip() for part in str(value).split(",") if part.strip())
+ return result
+
+
+def _runtime_service(request: Request):
+ runtime = getattr(request.app.state, "usage_audit_runtime", None)
+ if runtime is None:
+ return None
+ return runtime.api_service
+
+
+def _ok_response(result):
+ return Response(status="ok", result=result).model_dump(exclude_none=True)
+
+
+def _disabled_response():
+ return _ok_response(
+ {
+ "enabled": False,
+ "message": "Usage/Audit is disabled or not initialized.",
+ }
+ )
+
+
[email protected]("/dashboard/summary")
+async def dashboard_summary(
+ request: Request,
+ _ctx: RequestContext = require_role(Role.ROOT, Role.ADMIN),
+):
+ """Return Dashboard top-card data."""
+ service = _runtime_service(request)
+ if service is None:
+ return _disabled_response()
+ return _ok_response(await service.dashboard_summary(_ctx))
+
+
+async def token_series(
+ request: Request,
+ start_date: str = Query(..., description="Start date in YYYY-MM-DD format"),
+ end_date: str = Query(..., description="End date in YYYY-MM-DD format"),
+ bucket: str = Query("day", pattern="^(day)$"),
+ _ctx: RequestContext = require_role(Role.ROOT, Role.ADMIN),
+):
+ """Return token usage trend for a date range."""
+ service = _runtime_service(request)
+ if service is None:
+ return _disabled_response()
+ result = await service.token_series(
+ ctx=_ctx,
+ start_date=start_date,
+ end_date=end_date,
+ bucket=bucket,
+ )
+ return _ok_response(result)
+
+
[email protected]("/context-commits")
+async def context_commits(
+ request: Request,
+ start_date: str = Query(..., description="Start date in YYYY-MM-DD format"),
+ end_date: str = Query(..., description="End date in YYYY-MM-DD format"),
+ bucket: str = Query("hour", pattern="^(hour|4h)$"),
+ _ctx: RequestContext = require_role(Role.ROOT, Role.ADMIN),
+):
+ """Return context write heatmap rows for a date range."""
+ service = _runtime_service(request)
+ if service is None:
+ return _disabled_response()
+ result = await service.context_commits(
+ ctx=_ctx,
+ start_date=start_date,
+ end_date=end_date,
+ bucket=bucket,
+ )
+ return _ok_response(result)
+
+
+async def audit_logs(
+ request: Request,
+ page: int = Query(1, ge=1),
+ page_size: int = Query(10, ge=1, le=100),
+ request_id: Optional[str] = Query(None),
+ status: Optional[list[str]] = Query(None),
+ api_type: Optional[list[str]] = Query(None),
+ _ctx: RequestContext = require_role(Role.ROOT, Role.ADMIN),
+):
+ """Return filtered request audit logs."""
+ service = _runtime_service(request)
+ if service is None:
+ return _disabled_response()
+ result = await service.audit_logs(
+ ctx=_ctx,
+ request_id=request_id,
+ statuses=_split_multi(status),
+ api_types=_split_multi(api_type),
+ page=page,
+ page_size=page_size,
+ )
+ return _ok_response(result)
diff --git a/tests/metrics/integration/test_http_metrics.py b/tests/metrics/integration/test_http_metrics.py
index 42c877dfd..40478058f 100644
--- a/tests/metrics/integration/test_http_metrics.py
+++ b/tests/metrics/integration/test_http_metrics.py
@@ -21,7 +21,7 @@ from openviking.observability.context import (
reset_root_observability_context,
)
from openviking.observability.http_observability_middleware import (
- _INFLIGHT,
+ _INFLIGHT_COUNTER,
_get_route_template,
_inflight_delta,
create_http_observability_middleware,
@@ -146,13 +146,13 @@ def test_get_route_template_uses_low_cardinality_fallback_for_unmatched_route():
def test_inflight_delta_removes_zero_value_entries():
- _INFLIGHT.clear()
+ _INFLIGHT_COUNTER.clear()
assert _inflight_delta("/api/v1/resources", None, +1) == 1
- assert _INFLIGHT[("/api/v1/resources", None)] == 1
+ assert _INFLIGHT_COUNTER.get("/api/v1/resources", None) == 1
assert _inflight_delta("/api/v1/resources", None, -1) == 0
- assert ("/api/v1/resources", None) not in _INFLIGHT
+ assert _INFLIGHT_COUNTER.get("/api/v1/resources", None) == 0
def test_http_metrics_module_exposes_only_unified_middleware_entrypoint():
@@ -186,13 +186,12 @@ def test_http_metrics_middleware_emits_authenticated_account_id(monkeypatch):
request_events = [payload for event_name, payload in captured if event_name == "http.request"]
assert request_events
- assert request_events[0] == {
- "method": "POST",
- "route": "/api/v1/resources",
- "status": "200",
- "duration_seconds": request_events[0]["duration_seconds"],
- "account_id": "acct-real",
- }
+ assert request_events[0]["method"] == "POST"
+ assert request_events[0]["route"] == "/api/v1/resources"
+ assert request_events[0]["status"] == "200"
+ assert request_events[0]["account_id"] == "acct-real"
+ assert request_events[0]["request_id"]
+ assert request_events[0]["url_path"] == "/api/v1/resources"
assert isinstance(request_events[0]["duration_seconds"], float)
assert request_events[0]["duration_seconds"] >= 0.0
assert any(
@@ -285,19 +284,19 @@ def test_http_metrics_middleware_uses_route_bound_during_call_next(monkeypatch):
assert request_events[0]["route"] == "/api/v1/sessions/{session_id}"
-def test_http_metrics_middleware_logs_debug_when_metrics_write_fails(monkeypatch):
+def test_http_metrics_middleware_logs_error_when_metrics_write_fails(monkeypatch):
middleware = create_http_observability_middleware()
- debug_calls: list[tuple[str, tuple, dict]] = []
+ error_calls: list[tuple[str, tuple, dict]] = []
def _boom(**_kwargs):
raise RuntimeError("metrics write failed")
- def _debug(message, *args, **kwargs):
- debug_calls.append((message, args, kwargs))
+ def _error(message, *args, **kwargs):
+ error_calls.append((message, args, kwargs))
monkeypatch.setattr(HttpRequestLifecycleDataSource, "set_inflight", staticmethod(_boom))
monkeypatch.setattr(http_middleware.logger, "isEnabledFor", lambda _level: True)
- monkeypatch.setattr(http_middleware.logger, "debug", _debug)
+ monkeypatch.setattr(http_middleware.logger, "error", _error)
monkeypatch.setattr(http_middleware, "maybe_start_root_span", lambda _req, _attrs: None)
async def resources_handler(request: Request):
@@ -316,9 +315,10 @@ def test_http_metrics_middleware_logs_debug_when_metrics_write_fails(monkeypatch
assert resp.status_code == 200
assert any(
- message == "http metrics write failed: %s" for message, _args, _kwargs in debug_calls
+ message.startswith("Unexpected error in http.inflight")
+ for message, _args, _kwargs in error_calls
)
- assert any("http.inflight" in str(args) for _message, args, _kwargs in debug_calls)
+ assert any("metrics write failed" in str(args) for _message, args, _kwargs in error_calls)
class _DummyVLM(VLMBase):
diff --git a/tests/misc/test_console_proxy.py b/tests/misc/test_console_proxy.py
new file mode 100644
index 000000000..0b56b267b
--- /dev/null
+++ b/tests/misc/test_console_proxy.py
@@ -0,0 +1,57 @@
+import httpx
+import pytest
+
+from openviking.console.app import create_console_app
+from openviking.console.config import ConsoleConfig
+
+
+async def test_console_bff_proxy_forwards_console_routes():
+ async def handler(request: httpx.Request) -> httpx.Response:
+ assert request.method == "GET"
+ assert request.url.path == "/api/v1/console/dashboard/summary"
+ assert request.url.query == b"range=today"
+ assert request.headers["x-api-key"] == "test-key"
+ return httpx.Response(
+ status_code=200,
+ json={"status": "ok", "result": {"enabled": True}},
+ headers={"x-request-id": "req-console"},
+ )
+
+ app = create_console_app(
+ config=ConsoleConfig(openviking_base_url="http://openviking.test"),
+ upstream_transport=httpx.MockTransport(handler),
+ )
+ transport = httpx.ASGITransport(app=app)
+
+ async with httpx.AsyncClient(transport=transport, base_url="http://console.test") as client:
+ response = await client.get(
+ "/console/api/v1/ov/console/dashboard/summary?range=today",
+ headers={"x-api-key": "test-key"},
+ )
+
+ assert response.status_code == 200
+ assert response.headers["x-request-id"] == "req-console"
+ assert response.json() == {"status": "ok", "result": {"enabled": True}}
+
+
+async def test_console_bff_proxy_rejects_path_traversal():
+ called = False
+
+ async def handler(request: httpx.Request) -> httpx.Response:
+ nonlocal called
+ called = True
+ return httpx.Response(status_code=500)
+
+ app = create_console_app(
+ config=ConsoleConfig(openviking_base_url="http://openviking.test"),
+ upstream_transport=httpx.MockTransport(handler),
+ )
+ transport = httpx.ASGITransport(app=app)
+
+ async with httpx.AsyncClient(transport=transport, base_url="http://console.test") as client:
+ response = await client.get("/console/api/v1/ov/console/%2e%2e/admin/accounts")
+
+ assert response.status_code == 404
+ assert called is False
diff --git a/tests/observability/test_console_router.py b/tests/observability/test_console_router.py
new file mode 100644
index 000000000..909aeaf9c
--- /dev/null
+++ b/tests/observability/test_console_router.py
@@ -0,0 +1,129 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from openviking.server.auth import get_request_context
+from openviking.server.identity import RequestContext, Role
+from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Response
+from openviking.server.routers.console import router as console_router
+from openviking_cli.exceptions import InvalidArgumentError, OpenVikingError
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _ctx(role: Role = Role.ADMIN) -> RequestContext:
+ return RequestContext(
+ user=UserIdentifier(account_id="acct-1", user_id="user-1", agent_id="agent-1"),
+ role=role,
+ )
+
+
+def _admin_ctx() -> RequestContext:
+ return _ctx(Role.ADMIN)
+
+
+def _user_ctx() -> RequestContext:
+ return _ctx(Role.USER)
+
+
+def _app_with_runtime(runtime=None, *, request_context=_admin_ctx) -> FastAPI:
+ app = FastAPI()
+ app.include_router(console_router)
+ app.state.usage_audit_runtime = runtime
+ app.dependency_overrides[get_request_context] = request_context
+
+ @app.exception_handler(OpenVikingError)
+ async def openviking_error_handler(_, exc: OpenVikingError):
+ return JSONResponse(
+ status_code=ERROR_CODE_TO_HTTP_STATUS.get(exc.code, 500),
+ content=Response(
+ status="error",
+ error=ErrorInfo(code=exc.code, message=exc.message, details=exc.details),
+ ).model_dump(),
+ )
+
+ return app
+
+
+class FakeConsoleService:
+ def __init__(self) -> None:
+ self.audit_call = None
+
+ async def token_series(self, **kwargs):
+ raise InvalidArgumentError("bad date range")
+
+ async def audit_logs(self, **kwargs):
+ self.audit_call = kwargs
+ return {"total": 0, "success_rate": 0.0, "page": 2, "page_size": 20, "items": []}
+
+
+class FakeRuntime:
+ def __init__(self, api_service) -> None:
+ self.api_service = api_service
+
+
+async def test_console_router_returns_disabled_when_usage_audit_not_initialized():
+ transport = httpx.ASGITransport(app=_app_with_runtime(None))
+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.get("/api/v1/console/dashboard/summary")
+
+ assert response.status_code == 200
+ assert response.json()["result"]["enabled"] is False
+
+
+async def test_console_router_splits_audit_filters():
+ service = FakeConsoleService()
+ transport = httpx.ASGITransport(app=_app_with_runtime(FakeRuntime(service)))
+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.get(
+ "/api/v1/console/audit",
+ params={
+ "page": "2",
+ "page_size": "20",
+ "status": ["success,error", "5xx"],
+ "api_type": "search.find,sessions",
+ },
+ )
+
+ assert response.status_code == 200
+ assert response.json()["status"] == "ok"
+ assert service.audit_call["ctx"].account_id == "acct-1"
+ assert service.audit_call["statuses"] == ["success", "error", "5xx"]
+ assert service.audit_call["api_types"] == ["search.find", "sessions"]
+ assert service.audit_call["page"] == 2
+ assert service.audit_call["page_size"] == 20
+
+
+async def test_console_router_rejects_regular_user():
+ service = FakeConsoleService()
+ transport = httpx.ASGITransport(
+ app=_app_with_runtime(FakeRuntime(service), request_context=_user_ctx)
+ )
+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.get("/api/v1/console/audit")
+
+ assert response.status_code == 403
+ assert response.json()["error"]["code"] == "PERMISSION_DENIED"
+ assert service.audit_call is None
+
+
+async def test_console_router_invalid_arguments_return_http_400():
+ service = FakeConsoleService()
+ transport = httpx.ASGITransport(app=_app_with_runtime(FakeRuntime(service)))
+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.get(
+ "/api/v1/console/tokens",
+ params={"start_date": "2026-05-12", "end_date": "2026-05-01"},
+ )
+
+ assert response.status_code == 400
+ assert response.json()["error"]["code"] == "INVALID_ARGUMENT"
diff --git a/tests/observability/test_events.py b/tests/observability/test_events.py
new file mode 100644
index 000000000..a5ef7ac01
--- /dev/null
+++ b/tests/observability/test_events.py
@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+from openviking.metrics.datasources.base import EventMetricDataSource
+from openviking.observability.context import (
+ bind_root_observability_context,
+ reset_root_observability_context,
+)
+from openviking.observability.events import (
+ ObservabilityEvent,
+ register_event_subscriber,
+ reset_event_bus_for_tests,
+ try_publish_event,
+)
+from openviking.telemetry.span_models import RootSpanAttributes
+
+
+def test_event_bus_fans_out_and_enriches_root_metadata():
+ reset_event_bus_for_tests()
+ seen_a: list[ObservabilityEvent] = []
+ seen_b: list[ObservabilityEvent] = []
+ register_event_subscriber("a", seen_a.append)
+ register_event_subscriber("b", seen_b.append)
+
+ root = RootSpanAttributes(
+ http_method="GET",
+ http_route="/api/v1/demo",
+ request_id="req-1",
+ account_id="acct-1",
+ user_id="user-1",
+ agent_id="agent-1",
+ )
+ token = bind_root_observability_context(root)
+ try:
+ try_publish_event("demo.event", {"value": 1})
+ finally:
+ reset_root_observability_context(token)
+ reset_event_bus_for_tests()
+
+ assert len(seen_a) == 1
+ assert len(seen_b) == 1
+ assert seen_a[0].event_name == "demo.event"
+ assert seen_a[0].payload == {"value": 1}
+ assert seen_a[0].request_id == "req-1"
+ assert seen_a[0].account_id == "acct-1"
+ assert seen_a[0].user_id == "user-1"
+ assert seen_a[0].agent_id == "agent-1"
+
+
+def test_metric_datasource_publishes_to_shared_bus_without_metrics_init():
+ reset_event_bus_for_tests()
+ seen: list[ObservabilityEvent] = []
+ register_event_subscriber("usage-audit-test", seen.append)
+ try:
+ EventMetricDataSource._emit("demo.metric", {"value": 3})
+ finally:
+ reset_event_bus_for_tests()
+
+ assert len(seen) == 1
+ assert seen[0].event_name == "demo.metric"
+ assert seen[0].payload == {"value": 3}
diff --git a/tests/observability/test_usage_audit_inventory.py b/tests/observability/test_usage_audit_inventory.py
new file mode 100644
index 000000000..7ba4a0988
--- /dev/null
+++ b/tests/observability/test_usage_audit_inventory.py
@@ -0,0 +1,94 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from openviking.observability.usage_audit.inventory import ContextInventoryProvider
+from openviking.pyagfs.exceptions import AGFSNotFoundError
+from openviking.server.identity import RequestContext, Role
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _ctx() -> RequestContext:
+ return RequestContext(
+ user=UserIdentifier(account_id="acct-1", user_id="user-1", agent_id="agent-1"),
+ role=Role.USER,
+ )
+
+
+class FakeFSService:
+ def __init__(self) -> None:
+ self.calls = []
+
+ async def stat(self, uri, *, ctx):
+ self.calls.append((uri, ctx))
+ return {
+ "viking://resources": {"count": 2},
+ "viking://agent/agent-1/skills": {"count": 3},
+ "viking://user/user-1/memories": {"count": 5},
+ "viking://agent/agent-1/memories": {"count": 7},
+ }[uri]
+
+
+class FailingFSService:
+ async def stat(self, uri, *, ctx):
+ raise RuntimeError(f"stat unavailable for {uri}")
+
+
+class MissingFSService:
+ async def stat(self, uri, *, ctx):
+ raise AGFSNotFoundError(uri)
+
+
+async def test_context_inventory_counts_from_stat():
+ fs = FakeFSService()
+ provider = ContextInventoryProvider(
+ SimpleNamespace(fs=fs),
+ ttl_seconds=0,
+ )
+ ctx = _ctx()
+
+ counts = await provider.get_counts(ctx)
+
+ assert counts == {"files": 2, "skills": 3, "memories": 12, "total": 17}
+ assert len(fs.calls) == 4
+ assert {uri for uri, call_ctx in fs.calls if call_ctx is ctx} == {
+ "viking://resources",
+ "viking://agent/agent-1/skills",
+ "viking://user/user-1/memories",
+ "viking://agent/agent-1/memories",
+ }
+
+
+async def test_context_inventory_treats_missing_roots_as_empty():
+ provider = ContextInventoryProvider(
+ SimpleNamespace(fs=MissingFSService()),
+ ttl_seconds=0,
+ )
+
+ with patch("openviking.observability.usage_audit.inventory.logger.warning") as warning:
+ counts = await provider.get_counts(_ctx())
+
+ assert counts == {"files": 0, "skills": 0, "memories": 0, "total": 0}
+ warning.assert_not_called()
+
+
+async def test_context_inventory_warns_on_unexpected_stat_failures():
+ provider = ContextInventoryProvider(
+ SimpleNamespace(fs=FailingFSService()),
+ ttl_seconds=0,
+ )
+
+ with patch("openviking.observability.usage_audit.inventory.logger.warning") as warning:
+ counts = await provider.get_counts(_ctx())
+
+ assert counts == {"files": 0, "skills": 0, "memories": 0, "total": 0}
+ warning.assert_called()
diff --git a/tests/observability/test_usage_audit_runtime.py b/tests/observability/test_usage_audit_runtime.py
new file mode 100644
index 000000000..5da8d0f7c
--- /dev/null
+++ b/tests/observability/test_usage_audit_runtime.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from openviking.observability.events import reset_event_bus_for_tests, try_publish_event
+from openviking.observability.usage_audit import (
+ init_usage_audit_from_server_config,
+ shutdown_usage_audit,
+)
+from openviking.server.config import ObservabilityConfig, ServerConfig, UsageAuditConfig
+
+
+async def test_usage_audit_runtime_subscribes_to_shared_event_bus(tmp_path):
+ reset_event_bus_for_tests()
+ app = SimpleNamespace(state=SimpleNamespace())
+ config = ServerConfig(
+ observability=ObservabilityConfig(
+ usage_audit=UsageAuditConfig(
+ sqlite_path=str(tmp_path / "usage.sqlite3"),
+ flush_interval_seconds=0.1,
+ timezone="UTC",
+ )
+ )
+ )
+ runtime = await init_usage_audit_from_server_config(config, app=app, service=object())
+ assert runtime is not None
+ try:
+ try_publish_event(
+ "http.request",
+ {
+ "request_id": "req-runtime",
+ "account_id": "acct-runtime",
+ "user_id": "user-runtime",
+ "agent_id": "agent-runtime",
+ "method": "POST",
+ "route": "/api/v1/search/find",
+ "status": "200",
+ "duration_seconds": 0.01,
+ },
+ )
+ await runtime.worker.close(timeout_seconds=1.0)
+
+ retrievals = await runtime.store.get_today_retrievals(
+ account_id="acct-runtime",
+ date=runtime.api_service.today(),
+ )
+ audit = await runtime.store.query_audit_logs(account_id="acct-runtime")
+ finally:
+ await shutdown_usage_audit(app=app)
+ reset_event_bus_for_tests()
+
+ assert retrievals["find"] == 1
+ assert audit["total"] == 1
+ assert audit["items"][0]["request_id"] == "req-runtime"
diff --git a/tests/observability/test_usage_audit_store.py b/tests/observability/test_usage_audit_store.py
new file mode 100644
index 000000000..32976421f
--- /dev/null
+++ b/tests/observability/test_usage_audit_store.py
@@ -0,0 +1,227 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+
+from openviking.observability.events import ObservabilityEvent
+from openviking.observability.usage_audit.sqlite_store import SQLiteUsageAuditStore
+
+
+def _event(event_name: str, payload: dict, *, agent_id: str | None = None) -> ObservabilityEvent:
+ return ObservabilityEvent(
+ event_name=event_name,
+ payload=payload,
+ timestamp=datetime(2026, 5, 12, 1, 2, 3, tzinfo=timezone.utc),
+ request_id=payload.get("request_id"),
+ account_id="acct-1",
+ user_id="user-1",
+ agent_id=agent_id,
+ )
+
+
+async def test_sqlite_usage_audit_store_aggregates_dashboard_data(tmp_path):
+ store = SQLiteUsageAuditStore(tmp_path / "usage.sqlite3", timezone_name="UTC")
+ await store.initialize()
+ try:
+ await store.record_batch(
+ [
+ _event(
+ "vlm.call",
+ {
+ "provider": "p",
+ "model_name": "m",
+ "prompt_tokens": 3,
+ "completion_tokens": 2,
+ },
+ ),
+ _event(
+ "embedding.call",
+ {
+ "provider": "p",
+ "model_name": "e",
+ "prompt_tokens": 5,
+ "completion_tokens": 0,
+ },
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-find",
+ "method": "POST",
+ "route": "/api/v1/search/find",
+ "status": "200",
+ "duration_seconds": 0.1,
+ },
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-message",
+ "method": "POST",
+ "route": "/api/v1/sessions/{session_id}/messages",
+ "status": "200",
+ "duration_seconds": 0.1,
+ },
+ agent_id="agent-1",
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-console",
+ "method": "GET",
+ "route": "/api/v1/console/dashboard/summary",
+ "status": "200",
+ "duration_seconds": 0.01,
+ },
+ agent_id="agent-1",
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-docs",
+ "method": "GET",
+ "route": "/docs",
+ "status": "200",
+ "duration_seconds": 0.01,
+ },
+ agent_id="agent-1",
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-favicon",
+ "method": "GET",
+ "route": "/favicon.ico",
+ "status": "200",
+ "duration_seconds": 0.01,
+ },
+ agent_id="agent-1",
+ ),
+ ]
+ )
+
+ assert await store.get_today_tokens(account_id="acct-1", date="2026-05-12") == {
+ "vlm_input": 3,
+ "vlm_output": 2,
+ "embedding_input": 5,
+ "total": 10,
+ }
+ assert await store.get_today_retrievals(account_id="acct-1", date="2026-05-12") == {
+ "find": 1,
+ "search": 0,
+ "total": 1,
+ }
+ commits = await store.get_context_commit_heatmap(
+ account_id="acct-1",
+ start_date="2026-05-12",
+ end_date="2026-05-12",
+ bucket="hour",
+ )
+ assert any(row["hour"] == 1 and row["session_add_message"] == 1 for row in commits)
+ agents = await store.get_agent_overview(
+ account_id="acct-1",
+ date="2026-05-12",
+ )
+ assert agents["total"] == 1
+ assert agents["items"][0]["agent_id"] == "agent-1"
+ audit = await store.query_audit_logs(account_id="acct-1")
+ assert audit["total"] == 2
+ assert audit["success_rate"] == 1.0
+ assert {item["api_type"] for item in audit["items"]} == {"search.find", "sessions"}
+ finally:
+ await store.close()
+
+
+async def test_sqlite_usage_audit_store_trims_audit_per_account(tmp_path):
+ store = SQLiteUsageAuditStore(
+ tmp_path / "usage.sqlite3",
+ audit_retention_per_account=2,
+ timezone_name="UTC",
+ )
+ await store.initialize()
+ try:
+ await store.record_batch(
+ [
+ _event(
+ "http.request",
+ {
+ "request_id": f"req-{idx}",
+ "method": "GET",
+ "route": "/api/v1/system/status",
+ "status": "200",
+ "duration_seconds": 0.01,
+ },
+ )
+ for idx in range(3)
+ ]
+ )
+ audit = await store.query_audit_logs(account_id="acct-1", page_size=10)
+ assert audit["total"] == 2
+ assert [item["request_id"] for item in audit["items"]] == ["req-2", "req-1"]
+ finally:
+ await store.close()
+
+
+async def test_sqlite_usage_audit_store_success_filter_includes_3xx(tmp_path):
+ store = SQLiteUsageAuditStore(tmp_path / "usage.sqlite3", timezone_name="UTC")
+ await store.initialize()
+ try:
+ await store.record_batch(
+ [
+ _event(
+ "http.request",
+ {
+ "request_id": "req-200",
+ "method": "GET",
+ "route": "/api/v1/system/status",
+ "status": "200",
+ "duration_seconds": 0.01,
+ },
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-302",
+ "method": "GET",
+ "route": "/api/v1/system/status",
+ "status": "302",
+ "duration_seconds": 0.01,
+ },
+ ),
+ _event(
+ "http.request",
+ {
+ "request_id": "req-500",
+ "method": "GET",
+ "route": "/api/v1/system/status",
+ "status": "500",
+ "duration_seconds": 0.01,
+ },
+ ),
+ ]
+ )
+
+ success = await store.query_audit_logs(
+ account_id="acct-1",
+ statuses=["success"],
+ page_size=10,
+ )
+ explicit_2xx = await store.query_audit_logs(
+ account_id="acct-1",
+ statuses=["2xx"],
+ page_size=10,
+ )
+
+ assert success["total"] == 2
+ assert {item["request_id"] for item in success["items"]} == {"req-200", "req-302"}
+ assert explicit_2xx["total"] == 1
+ assert explicit_2xx["items"][0]["request_id"] == "req-200"
+ finally:
+ await store.close()
diff --git a/tests/observability/test_usage_audit_worker.py b/tests/observability/test_usage_audit_worker.py
new file mode 100644
index 000000000..57f3a8a4e
--- /dev/null
+++ b/tests/observability/test_usage_audit_worker.py
@@ -0,0 +1,70 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+import asyncio
+from typing import Sequence
+
+import pytest
+
+from openviking.observability.events import ObservabilityEvent
+from openviking.observability.usage_audit.worker import UsageAuditWorker
+
+
+class FakeStore:
+ def __init__(self) -> None:
+ self.batches: list[list[ObservabilityEvent]] = []
+
+ async def record_batch(self, events: Sequence[ObservabilityEvent]) -> None:
+ self.batches.append(list(events))
+
+
+class SlowFirstFlushStore:
+ def __init__(self) -> None:
+ self.batches: list[list[ObservabilityEvent]] = []
+ self.calls = 0
+ self.started = asyncio.Event()
+
+ async def record_batch(self, events: Sequence[ObservabilityEvent]) -> None:
+ self.calls += 1
+ if self.calls == 1:
+ self.started.set()
+ await asyncio.sleep(0.05)
+ self.batches.append(list(events))
+
+
+async def test_usage_audit_worker_close_flushes_queued_events():
+ store = FakeStore()
+ worker = UsageAuditWorker(
+ store,
+ queue_size=10,
+ batch_size=10,
+ flush_interval_seconds=1.0,
+ )
+ await worker.start()
+ worker.enqueue(ObservabilityEvent(event_name="demo", payload={"value": 1}))
+
+ await worker.close(timeout_seconds=0.2)
+
+ assert [[event.event_name for event in batch] for batch in store.batches] == [["demo"]]
+
+
+async def test_usage_audit_worker_close_waits_for_inflight_batch_after_timeout():
+ store = SlowFirstFlushStore()
+ worker = UsageAuditWorker(
+ store,
+ queue_size=10,
+ batch_size=10,
+ flush_interval_seconds=1.0,
+ )
+ await worker.start()
+ worker.enqueue(ObservabilityEvent(event_name="demo", payload={"value": 1}))
+ await asyncio.wait_for(store.started.wait(), timeout=1.0)
+
+ await worker.close(timeout_seconds=0.01)
+
+ assert store.calls == 1
+ assert [[event.event_name for event in batch] for batch in store.batches] == [["demo"]]