Skip to content

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

feat(server): 增加 Request ID 日志关联 (#3572)

Qin Haojie8d087c0e3975
diff --git a/openviking/observability/http_observability_middleware.py b/openviking/observability/http_observability_middleware.py
index 2f2507b47..2ab88ba8b 100644
--- a/openviking/observability/http_observability_middleware.py
+++ b/openviking/observability/http_observability_middleware.py
@@ -14,7 +14,6 @@ from __future__ import annotations
import logging
import threading
import time
-import uuid
from contextlib import nullcontext
from dataclasses import dataclass
from typing import Any, Awaitable, Callable, ContextManager, Optional
@@ -827,7 +826,7 @@ def create_http_observability_middleware() -> Callable[[Request, Callable], Resp
raw_path = str(request.url.path)
raw_query = request.url.query or None
route_template = _get_route_template(request)
- request_id = request.headers.get("x-request-id") or str(uuid.uuid4())
+ request_id = request.state.request_id
# Create root span attributes
root_attrs = create_root_span_attributes(
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 8e171495e..f1c0a5c0f 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -15,6 +15,7 @@ from fastapi.exceptions import RequestValidationError
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse, JSONResponse, RedirectResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.middleware.exceptions import ExceptionMiddleware
from openviking.server.config import (
ServerConfig,
@@ -27,6 +28,7 @@ from openviking.server.error_mapping import map_exception
from openviking.server.identity import Role
from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Response
from openviking.server.profile_middleware import create_profile_http_middleware
+from openviking.server.request_id import REQUEST_ID_HEADER, RequestIdMiddleware
from openviking.server.routers import (
admin_router,
bot_router,
@@ -334,15 +336,6 @@ def create_app(
app.state.api_key_manager = None
set_server_config(config)
- # Add CORS middleware
- app.add_middleware(
- CORSMiddleware,
- allow_origins=config.cors_origins,
- allow_credentials=True,
- allow_methods=["*"],
- allow_headers=["*"],
- )
-
# Body dump middleware must be registered BEFORE observability so it ends up
# nested inside the trace span (in Starlette, middleware added later wraps
# earlier-added ones — so earlier registration = inner layer).
@@ -478,8 +471,7 @@ def create_app(
)
# Catch-all for unhandled exceptions so clients always get JSON
- @app.exception_handler(Exception)
- async def general_error_handler(request: Request, exc: Exception):
+ async def general_error_handler(_request: Request, exc: Exception):
mapped = map_exception(exc)
if mapped is not None:
http_status = ERROR_CODE_TO_HTTP_STATUS.get(mapped.code, 500)
@@ -512,6 +504,19 @@ def create_app(
).model_dump(),
)
+ # Keep exception rendering inside the request-ID and CORS layers. This lets
+ # those middleware own their response headers without special error paths.
+ app.add_middleware(ExceptionMiddleware, handlers={Exception: general_error_handler})
+ app.add_middleware(RequestIdMiddleware)
+ app.add_middleware(
+ CORSMiddleware,
+ allow_origins=config.cors_origins,
+ allow_credentials=True,
+ allow_methods=["*"],
+ allow_headers=["*"],
+ expose_headers=[REQUEST_ID_HEADER],
+ )
+
# Configure Bot API if --with-bot is enabled
if config.with_bot:
import openviking.server.routers.bot as bot_module
diff --git a/openviking/server/request_id.py b/openviking/server/request_id.py
new file mode 100644
index 000000000..74b82bc80
--- /dev/null
+++ b/openviking/server/request_id.py
@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Request ID handling for the OpenViking HTTP server."""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+import uuid
+
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from openviking_cli.utils.logger import bind_log_request_id
+
+REQUEST_ID_HEADER = "X-Request-ID"
+_REQUEST_ID_HEADER_BYTES = b"x-request-id"
+_REQUEST_ID_PATTERN = re.compile(r"[A-Za-z0-9._:-]{1,128}")
+_IGNORED_COMPLETION_ROUTES = frozenset({"/health", "/ready", "/metrics"})
+
+_completion_logger = logging.getLogger("openviking.observability.http")
+
+
+def _resolve_request_id(scope: Scope) -> tuple[str, bool]:
+ values = [
+ value
+ for name, value in scope["headers"]
+ if name.lower() == _REQUEST_ID_HEADER_BYTES
+ ]
+ invalid = bool(values)
+ if len(values) == 1:
+ try:
+ value = values[0].decode("ascii")
+ except UnicodeDecodeError:
+ pass
+ else:
+ if _REQUEST_ID_PATTERN.fullmatch(value):
+ return value, False
+ return str(uuid.uuid4()), invalid
+
+
+def _route_template(scope: Scope) -> str:
+ route = scope.get("route")
+ path = getattr(route, "path", None)
+ return str(path) if path else "/__unmatched__"
+
+
+class RequestIdMiddleware:
+ """Validate, bind, return, and log one request ID per HTTP request."""
+
+ def __init__(self, app: ASGIApp) -> None:
+ self.app = app
+
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+ if scope["type"] != "http":
+ await self.app(scope, receive, send)
+ return
+
+ started_at = time.perf_counter()
+ request_id, invalid = _resolve_request_id(scope)
+ scope.setdefault("state", {})["request_id"] = request_id
+ method = scope["method"]
+ status_code = 500
+
+ async def send_with_request_id(message: Message) -> None:
+ nonlocal status_code
+ if message["type"] == "http.response.start":
+ status_code = int(message["status"])
+ headers = [
+ (name, value)
+ for name, value in message.get("headers", [])
+ if name.lower() != _REQUEST_ID_HEADER_BYTES
+ ]
+ headers.append((_REQUEST_ID_HEADER_BYTES, request_id.encode("ascii")))
+ message = {**message, "headers": headers}
+ await send(message)
+
+ with bind_log_request_id(request_id):
+ try:
+ if invalid:
+ response = JSONResponse(
+ status_code=400,
+ content={
+ "status": "error",
+ "error": {
+ "code": "INVALID_ARGUMENT",
+ "message": (
+ "X-Request-ID must be supplied once and contain 1-128 "
+ "characters from [A-Za-z0-9._:-]"
+ ),
+ },
+ },
+ )
+ await response(scope, receive, send_with_request_id)
+ else:
+ await self.app(scope, receive, send_with_request_id)
+ finally:
+ if scope["path"] not in _IGNORED_COMPLETION_ROUTES:
+ duration_ms = (time.perf_counter() - started_at) * 1000
+ route = _route_template(scope)
+ _completion_logger.info(
+ "HTTP request completed method=%s route=%s status=%d duration_ms=%.1f",
+ method,
+ route,
+ status_code,
+ duration_ms,
+ extra={
+ "http_method": method,
+ "http_route": route,
+ "http_status_code": status_code,
+ "duration_ms": duration_ms,
+ },
+ )
diff --git a/openviking_cli/utils/logger.py b/openviking_cli/utils/logger.py
index cf72811f5..43ce71d7a 100644
--- a/openviking_cli/utils/logger.py
+++ b/openviking_cli/utils/logger.py
@@ -5,6 +5,7 @@ Logging utilities for OpenViking.
"""
import atexit
+import contextvars
import logging
import queue
import sys
@@ -12,7 +13,7 @@ import threading
from contextlib import contextmanager
from logging.handlers import QueueHandler, QueueListener, TimedRotatingFileHandler
from pathlib import Path
-from typing import Any, Optional, Tuple
+from typing import Any, Iterator, Optional, Tuple
from uuid import uuid4
from openviking.observability.context import (
@@ -73,6 +74,21 @@ _std_stream_handlers: dict[str, Tuple[QueueListener, logging.Handler]] = {}
_std_stream_handlers_lock = threading.RLock()
_std_stream_atexit_registered = False
+_request_id_context: contextvars.ContextVar[str] = contextvars.ContextVar(
+ "openviking_log_request_id", default=""
+)
+
+
+@contextmanager
+def bind_log_request_id(request_id: str) -> Iterator[None]:
+ """Bind a request ID to logs emitted in the current execution context."""
+
+ token = _request_id_context.set(request_id)
+ try:
+ yield
+ finally:
+ _request_id_context.reset(token)
+
def _get_log_context() -> dict[str, Any]:
"""
@@ -441,6 +457,17 @@ class TraceContextFilter(logging.Filter):
return True
+class _RequestIdLoggingFilter(logging.Filter):
+ """Inject and render the request ID bound by the HTTP server."""
+
+ def filter(self, record: logging.LogRecord) -> bool:
+ request_id = _request_id_context.get()
+ record.request_id = request_id
+ if request_id:
+ record.msg = f"[request_id={request_id}] {record.msg}"
+ return True
+
+
class LogToSpanEventFilter(logging.Filter):
"""
Log filter that automatically maps log records to OTel span events.
@@ -748,12 +775,10 @@ def _build_standard_handler(
real = getattr(handler, "_ov_real_handler", None)
if real is not None:
real.setFormatter(logging.Formatter("%(message)s"))
- handler.setFormatter(logging.Formatter(format_string))
- _add_trace_id_filter(handler)
- return handler
handler.setFormatter(logging.Formatter(format_string))
_add_trace_id_filter(handler)
+ handler.addFilter(_RequestIdLoggingFilter())
return handler
diff --git a/tests/metrics/integration/test_account_dimension.py b/tests/metrics/integration/test_account_dimension.py
index 1e9d4d0f7..cef8e078d 100644
--- a/tests/metrics/integration/test_account_dimension.py
+++ b/tests/metrics/integration/test_account_dimension.py
@@ -43,6 +43,7 @@ def _build_test_app(middleware_factory, *, route_path: str, handler):
@app.middleware("http")
async def middleware_entry(request, call_next):
+ request.state.request_id = "test-request"
return await middleware_factory(request, call_next)
app.get(route_path)(handler)
diff --git a/tests/metrics/integration/test_http_metrics.py b/tests/metrics/integration/test_http_metrics.py
index 40478058f..2d4cb02ba 100644
--- a/tests/metrics/integration/test_http_metrics.py
+++ b/tests/metrics/integration/test_http_metrics.py
@@ -40,6 +40,7 @@ def _build_test_app(middleware_factory, *, route_path: str, method: str, handler
@app.middleware("http")
async def middleware_entry(request, call_next):
+ request.state.request_id = "test-request"
return await middleware_factory(request, call_next)
if method == "GET":
diff --git a/tests/server/test_request_id.py b/tests/server/test_request_id.py
new file mode 100644
index 000000000..9cc9503e2
--- /dev/null
+++ b/tests/server/test_request_id.py
@@ -0,0 +1,201 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Request ID validation, propagation, and logging tests."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from types import SimpleNamespace
+from uuid import UUID
+
+import httpx
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from openviking.observability.context import get_root_observability_context
+from openviking.observability.http_observability_middleware import (
+ create_http_observability_middleware,
+)
+from openviking.server.app import create_app
+from openviking.server.config import ServerConfig
+from openviking.server.request_id import REQUEST_ID_HEADER, RequestIdMiddleware
+
+
+class _CaptureHandler(logging.Handler):
+ def __init__(self, records: list[logging.LogRecord]) -> None:
+ super().__init__()
+ self._records = records
+
+ def emit(self, record: logging.LogRecord) -> None:
+ self._records.append(record)
+
+
+def _make_test_app() -> FastAPI:
+ app = FastAPI()
+ observability_middleware = create_http_observability_middleware()
+
+ @app.middleware("http")
+ async def add_observability(request, call_next):
+ return await observability_middleware(request, call_next)
+
+ app.add_middleware(RequestIdMiddleware)
+ app.add_middleware(
+ CORSMiddleware,
+ allow_origins=["*"],
+ allow_methods=["*"],
+ allow_headers=["*"],
+ expose_headers=[REQUEST_ID_HEADER],
+ )
+ return app
+
+
+async def _request(app: FastAPI, path: str, **kwargs) -> httpx.Response:
+ transport = httpx.ASGITransport(app=app, raise_app_exceptions=False)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ return await client.get(path, **kwargs)
+
+
+def _assert_generated_request_id(value: str) -> None:
+ assert UUID(value).version == 4
+
+
+async def test_client_request_id_is_returned_and_reused_by_observability() -> None:
+ app = _make_test_app()
+
+ @app.get("/items/{item_id}")
+ async def item(item_id: str):
+ root = get_root_observability_context()
+ return {"item_id": item_id, "observability_request_id": root.request_id}
+
+ response = await _request(
+ app,
+ "/items/42",
+ headers={REQUEST_ID_HEADER: "resource-import-20260728-001"},
+ )
+
+ assert response.status_code == 200
+ assert response.headers[REQUEST_ID_HEADER] == "resource-import-20260728-001"
+ assert response.json()["observability_request_id"] == "resource-import-20260728-001"
+
+
+async def test_missing_request_id_generates_uuid_for_health_and_cors_exposes_it() -> None:
+ app = _make_test_app()
+
+ @app.get("/health")
+ async def health():
+ return {"status": "ok"}
+
+ response = await _request(
+ app,
+ "/health",
+ headers={"Origin": "https://example.test"},
+ )
+
+ assert response.status_code == 200
+ _assert_generated_request_id(response.headers[REQUEST_ID_HEADER])
+ assert REQUEST_ID_HEADER.lower() in response.headers["Access-Control-Expose-Headers"].lower()
+
+
+async def test_invalid_request_ids_are_rejected_without_logging_raw_values() -> None:
+ app = _make_test_app()
+ records: list[logging.LogRecord] = []
+ server_logger = logging.getLogger("openviking")
+
+ handler = _CaptureHandler(records)
+ server_logger.addHandler(handler)
+ try:
+ cases = [
+ [(REQUEST_ID_HEADER, "")],
+ [(REQUEST_ID_HEADER, "contains spaces")],
+ [(REQUEST_ID_HEADER, "x" * 129)],
+ [(REQUEST_ID_HEADER, "first"), (REQUEST_ID_HEADER, "second")],
+ ]
+ responses = [await _request(app, "/items", headers=headers) for headers in cases]
+ finally:
+ server_logger.removeHandler(handler)
+
+ assert all(response.status_code == 400 for response in responses)
+ assert all(response.json()["error"]["code"] == "INVALID_ARGUMENT" for response in responses)
+ for response in responses:
+ _assert_generated_request_id(response.headers[REQUEST_ID_HEADER])
+ completion_records = [
+ record for record in records if record.name == "openviking.observability.http"
+ ]
+ assert all(record.request_id for record in completion_records)
+ rendered = "\n".join(record.getMessage() for record in completion_records)
+ assert all(raw not in rendered for raw in ("contains spaces", "x" * 129, "first", "second"))
+
+
+async def test_unhandled_500_keeps_request_id_for_log_and_response() -> None:
+ app = create_app(config=ServerConfig(), service=SimpleNamespace())
+ records: list[logging.LogRecord] = []
+ server_logger = logging.getLogger("openviking")
+
+ handler = _CaptureHandler(records)
+ server_logger.addHandler(handler)
+
+ @app.get("/_request-id-test/boom")
+ async def boom():
+ raise RuntimeError("synthetic failure")
+
+ try:
+ response = await _request(
+ app,
+ "/_request-id-test/boom",
+ headers={REQUEST_ID_HEADER: "failed-request-001"},
+ )
+ finally:
+ server_logger.removeHandler(handler)
+
+ assert response.status_code == 500
+ assert response.headers[REQUEST_ID_HEADER] == "failed-request-001"
+ error_records = [
+ record
+ for record in records
+ if record.name == "openviking.server.app" and "Unhandled exception" in record.getMessage()
+ ]
+ assert len(error_records) == 1
+ assert error_records[0].request_id == "failed-request-001"
+ assert error_records[0].getMessage().startswith("[request_id=failed-request-001] ")
+
+
+async def test_concurrent_requests_do_not_mix_or_leak_request_ids() -> None:
+ app = _make_test_app()
+ records: list[logging.LogRecord] = []
+ server_logger = logging.getLogger("openviking")
+ business_logger = logging.getLogger("openviking.service.concurrent_test")
+
+ handler = _CaptureHandler(records)
+ server_logger.addHandler(handler)
+ gate = asyncio.Event()
+ arrivals = 0
+
+ @app.get("/work/{label}")
+ async def work(label: str):
+ nonlocal arrivals
+ arrivals += 1
+ if arrivals == 2:
+ gate.set()
+ await gate.wait()
+ business_logger.info("finished label=%s", label)
+ return {"label": label}
+
+ try:
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ first, second = await asyncio.gather(
+ client.get("/work/first", headers={REQUEST_ID_HEADER: "request-first"}),
+ client.get("/work/second", headers={REQUEST_ID_HEADER: "request-second"}),
+ )
+ finally:
+ server_logger.removeHandler(handler)
+
+ assert first.headers[REQUEST_ID_HEADER] == "request-first"
+ assert second.headers[REQUEST_ID_HEADER] == "request-second"
+ business_records = [record for record in records if record.name == business_logger.name]
+ assert {record.args[0]: record.request_id for record in business_records} == {
+ "first": "request-first",
+ "second": "request-second",
+ }
diff --git a/tests/telemetry/test_http_observability_middleware.py b/tests/telemetry/test_http_observability_middleware.py
index a7dea3b7c..05e15c0cf 100644
--- a/tests/telemetry/test_http_observability_middleware.py
+++ b/tests/telemetry/test_http_observability_middleware.py
@@ -60,6 +60,7 @@ def test_http_observability_middleware_updates_route_template_after_routing(monk
@app.middleware("http")
async def _mw(request, call_next):
+ request.state.request_id = "test-request"
return await http_mw(request, call_next)
@app.get("/hello")