Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(console): 增加 Usage/Audit Dashboard BFF (#2016)
Qin Haojie9d36b2fd833d
diff --git a/openviking/console/app.py b/openviking/console/app.pyindex 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.pyindex 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-pathrestricted to Collector implementations.diff --git a/openviking/metrics/datasources/base.py b/openviking/metrics/datasources/base.pyindex 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):@staticmethoddef _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.pyindex 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 theauthenticated 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)@staticmethoddef 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.pyindex 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.pyindex 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 inspectimport threadingfrom 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 ServerConfigfrom 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.pynew file mode 100644index 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 _subscriberdiff --git a/openviking/observability/http_observability_middleware.py b/openviking/observability/http_observability_middleware.pyindex 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.mdnew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 0diff --git a/openviking/observability/usage_audit/projection.py b/openviking/observability/usage_audit/projection.pynew file mode 100644index 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.pynew file mode 100644index 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 = Nonediff --git a/openviking/observability/usage_audit/schema.py b/openviking/observability/usage_audit/schema.pynew file mode 100644index 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.pynew file mode 100644index 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) + ")", paramsdiff --git a/openviking/observability/usage_audit/store.py b/openviking/observability/usage_audit/store.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.utcdiff --git a/openviking/observability/usage_audit/worker.py b/openviking/observability/usage_audit/worker.pynew file mode 100644index 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.pyindex 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, Respofrom 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_configinit_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(# Cleanupfrom 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.pyindex 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, Optionalfrom 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__.pyindex 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_routerfrom openviking.server.routers.bot import router as bot_router+from openviking.server.routers.console import router as console_routerfrom openviking.server.routers.content import router as content_routerfrom openviking.server.routers.debug import router as debug_routerfrom openviking.server.routers.filesystem import router as filesystem_router@@ -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.pynew file mode 100644index 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))++[email protected]("/tokens")+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)++[email protected]("/audit")+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.pyindex 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) == 1assert _inflight_delta("/api/v1/resources", None, -1) == 0- assert ("/api/v1/resources", None) not in _INFLIGHT+ assert _INFLIGHT_COUNTER.get("/api/v1/resources", None) == 0def 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.0assert 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(monkeypatchassert resp.status_code == 200assert 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.pynew file mode 100644index 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 Falsediff --git a/tests/observability/test_console_router.py b/tests/observability/test_console_router.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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"]]