Skip to content

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

feat(server): add operation telemetry for session create/add_message/… (#1943)

Monday0158571f1ff8
diff --git a/openviking/async_client.py b/openviking/async_client.py
index c3f79802f..b68514577 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -128,7 +128,9 @@ class AsyncOpenViking:
await self._ensure_initialized()
return await self._client.session_exists(session_id)
- async def create_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+ async def create_session(
+ self, session_id: Optional[str] = None, telemetry: TelemetryRequest = False
+ ) -> Dict[str, Any]:
"""Create a new session.
Args:
@@ -136,7 +138,7 @@ class AsyncOpenViking:
If None, creates a new session with auto-generated ID.
"""
await self._ensure_initialized()
- return await self._client.create_session(session_id)
+ return await self._client.create_session(session_id, telemetry=telemetry)
async def list_sessions(self) -> List[Any]:
"""List all sessions."""
@@ -173,6 +175,7 @@ class AsyncOpenViking:
parts: list[dict] | None = None,
created_at: str | None = None,
role_id: str | None = None,
+ telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
"""Add a message to a session.
@@ -194,6 +197,7 @@ class AsyncOpenViking:
parts=parts,
created_at=created_at,
role_id=role_id,
+ telemetry=telemetry,
)
async def commit_session(
diff --git a/openviking/client/local.py b/openviking/client/local.py
index e8f800990..b080bb26a 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -399,13 +399,26 @@ class LocalClient(BaseClient):
# ============= Sessions =============
- async def create_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+ async def create_session(
+ self, session_id: Optional[str] = None, telemetry: TelemetryRequest = False
+ ) -> Dict[str, Any]:
"""Create a new session.
Args:
session_id: Optional session ID. If provided, creates a session with the given ID.
If None, creates a new session with auto-generated ID.
"""
+ execution = await run_with_telemetry(
+ operation="session.create",
+ telemetry=telemetry,
+ fn=lambda: self._create_session_impl(session_id),
+ )
+ return attach_telemetry_payload(
+ execution.result,
+ execution.telemetry,
+ )
+
+ async def _create_session_impl(self, session_id: Optional[str]) -> Dict[str, Any]:
await self._service.initialize_user_directories(self._ctx)
await self._service.initialize_agent_directories(self._ctx)
session = await self._service.sessions.create(self._ctx, session_id)
@@ -471,6 +484,7 @@ class LocalClient(BaseClient):
parts: Optional[List[Dict[str, Any]]] = None,
created_at: Optional[str] = None,
role_id: Optional[str] = None,
+ telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
"""Add a message to a session.
@@ -484,6 +498,32 @@ class LocalClient(BaseClient):
If both content and parts are provided, parts takes precedence.
"""
+ execution = await run_with_telemetry(
+ operation="session.add_message",
+ telemetry=telemetry,
+ fn=lambda: self._add_message_impl(
+ session_id,
+ role,
+ content,
+ parts,
+ created_at,
+ role_id,
+ ),
+ )
+ return attach_telemetry_payload(
+ execution.result,
+ execution.telemetry,
+ )
+
+ async def _add_message_impl(
+ self,
+ session_id: str,
+ role: str,
+ content: Optional[str],
+ parts: Optional[List[Dict[str, Any]]],
+ created_at: Optional[str],
+ role_id: Optional[str],
+ ) -> Dict[str, Any]:
from openviking.message.part import Part, TextPart, part_from_dict
session = await self._service.sessions.get(session_id, self._ctx, auto_create=True)
diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.py
index 08e662d4b..4c32a8e5c 100644
--- a/openviking/server/routers/sessions.py
+++ b/openviking/server/routers/sessions.py
@@ -15,6 +15,8 @@ from openviking.server.dependencies import get_service
from openviking.server.identity import AuthMode, RequestContext
from openviking.server.models import ErrorInfo, Response
from openviking.server.responses import error_response
+from openviking.server.telemetry import run_operation
+from openviking.telemetry import TelemetryRequest
router = APIRouter(prefix="/api/v1/sessions", tags=["sessions"])
logger = logging.getLogger(__name__)
@@ -67,6 +69,7 @@ class AddMessageRequest(BaseModel):
content: Optional[str] = None
parts: Optional[List[Dict[str, Any]]] = None
created_at: Optional[str] = None
+ telemetry: TelemetryRequest = False
@model_validator(mode="after")
def validate_content_or_parts(self) -> "AddMessageRequest":
@@ -86,6 +89,7 @@ class CreateSessionRequest(BaseModel):
"""Request model for creating a session."""
session_id: Optional[str] = None
+ telemetry: TelemetryRequest = False
def _to_jsonable(value: Any) -> Any:
@@ -109,7 +113,7 @@ def _request_auth_mode(request: Request) -> AuthMode:
@router.post("")
async def create_session(
- request: Optional[CreateSessionRequest] = None,
+ request: CreateSessionRequest = Body(default_factory=CreateSessionRequest),
_ctx: RequestContext = Depends(get_request_context),
):
"""Create a new session.
@@ -118,17 +122,22 @@ async def create_session(
If session_id is None, creates a new session with auto-generated ID.
"""
service = get_service()
- await service.initialize_user_directories(_ctx)
- await service.initialize_agent_directories(_ctx)
- session_id = request.session_id if request else None
- session = await service.sessions.create(_ctx, session_id)
- return Response(
- status="ok",
- result={
+
+ async def _create() -> dict[str, Any]:
+ await service.initialize_user_directories(_ctx)
+ await service.initialize_agent_directories(_ctx)
+ session = await service.sessions.create(_ctx, request.session_id)
+ return {
"session_id": session.session_id,
"user": session.user.to_dict(),
- },
+ }
+
+ execution = await run_operation(
+ operation="session.create",
+ telemetry=request.telemetry,
+ fn=_create,
)
+ return Response(status="ok", result=execution.result, telemetry=execution.telemetry)
@router.get("")
@@ -237,6 +246,7 @@ class CommitRequest(BaseModel):
"(default 10); compact path passes 0 to archive everything."
),
)
+ telemetry: TelemetryRequest = False
@router.post("/{session_id}/commit")
@@ -252,10 +262,18 @@ async def commit_session(
polling progress via ``GET /tasks/{task_id}``.
"""
service = get_service()
- result = await service.sessions.commit_async(
- session_id, _ctx, keep_recent_count=body.keep_recent_count
+ execution = await run_operation(
+ operation="session.commit",
+ telemetry=body.telemetry,
+ fn=lambda: service.sessions.commit_async(
+ session_id, _ctx, keep_recent_count=body.keep_recent_count
+ ),
)
- return Response(status="ok", result=result).model_dump(exclude_none=True)
+ return Response(
+ status="ok",
+ result=execution.result,
+ telemetry=execution.telemetry,
+ ).model_dump(exclude_none=True)
@router.post("/{session_id}/extract")
@@ -291,42 +309,47 @@ async def add_message(
Missing sessions are auto-created on first add.
"""
service = get_service()
- session = await service.sessions.get(session_id, _ctx, auto_create=True)
- role_id = _ctx.resolve_role_id(request.role, request.role_id)
-
- if request.parts is not None:
- # Resolve path variables in URIs within parts
- resolved_parts = []
- for p in request.parts:
- part_copy = dict(p)
- # Resolve uri in context parts
- if part_copy.get("type") == "context" and "uri" in part_copy:
- part_copy["uri"] = resolve_path_variables(part_copy["uri"])
- # Resolve tool_uri and skill_uri in tool parts
- if part_copy.get("type") == "tool":
- if "tool_uri" in part_copy:
- part_copy["tool_uri"] = resolve_path_variables(part_copy["tool_uri"])
- if "skill_uri" in part_copy:
- part_copy["skill_uri"] = resolve_path_variables(part_copy["skill_uri"])
- resolved_parts.append(part_copy)
- parts = [part_from_dict(p) for p in resolved_parts]
- else:
- parts = [TextPart(text=request.content or "")]
-
- # created_at 直接传递给 session (ISO string)
- session.add_message(
- request.role,
- parts,
- role_id=role_id,
- created_at=request.created_at,
- )
- return Response(
- status="ok",
- result={
+
+ async def _add() -> dict[str, Any]:
+ session = await service.sessions.get(session_id, _ctx, auto_create=True)
+ role_id = _ctx.resolve_role_id(request.role, request.role_id)
+
+ if request.parts is not None:
+ # Resolve path variables in URIs within parts
+ resolved_parts = []
+ for p in request.parts:
+ part_copy = dict(p)
+ # Resolve uri in context parts
+ if part_copy.get("type") == "context" and "uri" in part_copy:
+ part_copy["uri"] = resolve_path_variables(part_copy["uri"])
+ # Resolve tool_uri and skill_uri in tool parts
+ if part_copy.get("type") == "tool":
+ if "tool_uri" in part_copy:
+ part_copy["tool_uri"] = resolve_path_variables(part_copy["tool_uri"])
+ if "skill_uri" in part_copy:
+ part_copy["skill_uri"] = resolve_path_variables(part_copy["skill_uri"])
+ resolved_parts.append(part_copy)
+ parts = [part_from_dict(p) for p in resolved_parts]
+ else:
+ parts = [TextPart(text=request.content or "")]
+
+ session.add_message(
+ request.role,
+ parts,
+ role_id=role_id,
+ created_at=request.created_at,
+ )
+ return {
"session_id": session_id,
"message_count": len(session.messages),
- },
+ }
+
+ execution = await run_operation(
+ operation="session.add_message",
+ telemetry=request.telemetry,
+ fn=_add,
)
+ return Response(status="ok", result=execution.result, telemetry=execution.telemetry)
@router.post("/{session_id}/used")
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index 9cd9db772..db723f374 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -39,14 +39,16 @@ class SyncOpenViking:
"""Check whether a session exists in storage."""
return run_async(self._async_client.session_exists(session_id))
- def create_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+ def create_session(
+ self, session_id: Optional[str] = None, telemetry: TelemetryRequest = False
+ ) -> Dict[str, Any]:
"""Create a new session.
Args:
session_id: Optional session ID. If provided, creates a session with the given ID.
If None, creates a new session with auto-generated ID.
"""
- return run_async(self._async_client.create_session(session_id))
+ return run_async(self._async_client.create_session(session_id, telemetry=telemetry))
def list_sessions(self) -> List[Any]:
"""List all sessions."""
@@ -78,6 +80,7 @@ class SyncOpenViking:
parts: list[dict] | None = None,
created_at: str | None = None,
role_id: str | None = None,
+ telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
"""Add a message to a session.
@@ -92,7 +95,15 @@ class SyncOpenViking:
If both content and parts are provided, parts takes precedence.
"""
return run_async(
- self._async_client.add_message(session_id, role, content, parts, created_at, role_id)
+ self._async_client.add_message(
+ session_id,
+ role,
+ content,
+ parts,
+ created_at,
+ role_id,
+ telemetry,
+ )
)
def commit_session(
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index fa2d89288..1e13d6d6b 100644
--- a/openviking_cli/client/base.py
+++ b/openviking_cli/client/base.py
@@ -223,12 +223,15 @@ class BaseClient(ABC):
# ============= Sessions =============
@abstractmethod
- async def create_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+ async def create_session(
+ self, session_id: Optional[str] = None, telemetry: TelemetryRequest = False
+ ) -> Dict[str, Any]:
"""Create a new session.
Args:
session_id: Optional session ID. If provided, creates a session with the given ID.
If None, creates a new session with auto-generated ID.
+ telemetry: Whether to attach operation telemetry data to the result.
"""
...
@@ -275,6 +278,7 @@ class BaseClient(ABC):
parts: list[dict] | None = None,
created_at: str | None = None,
role_id: str | None = None,
+ telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
"""Add a message to a session.
@@ -285,6 +289,7 @@ class BaseClient(ABC):
parts: Parts array (full Part support: TextPart, ContextPart, ToolPart)
created_at: Message creation time (ISO format string)
role_id: Optional explicit actor identity. Omit to let the server derive it.
+ telemetry: Whether to attach operation telemetry data to the result.
If both content and parts are provided, parts takes precedence.
"""
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index 7ae0e8d5f..b7018346e 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -764,19 +764,27 @@ class AsyncHTTPClient(BaseClient):
# ============= Sessions =============
- async def create_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+ async def create_session(
+ self, session_id: Optional[str] = None, telemetry: TelemetryRequest = False
+ ) -> Dict[str, Any]:
"""Create a new session.
Args:
session_id: Optional session ID. If provided, creates a session with the given ID.
If None, creates a new session with auto-generated ID.
"""
- json_body = {"session_id": session_id} if session_id else {}
+ telemetry = self._validate_telemetry(telemetry)
+ json_body: Dict[str, Any] = {}
+ if session_id is not None:
+ json_body["session_id"] = session_id
+ if telemetry is not False:
+ json_body["telemetry"] = telemetry
response = await self._http.post(
"/api/v1/sessions",
json=json_body,
)
- return self._handle_response(response)
+ response_data = self._handle_response_data(response)
+ return self._attach_telemetry(response_data.get("result"), response_data)
async def list_sessions(self) -> List[Any]:
"""List all sessions."""
@@ -847,6 +855,7 @@ class AsyncHTTPClient(BaseClient):
parts: list[dict] | None = None,
created_at: str | None = None,
role_id: str | None = None,
+ telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
"""Add a message to a session.
@@ -860,6 +869,7 @@ class AsyncHTTPClient(BaseClient):
If both content and parts are provided, parts takes precedence.
"""
+ telemetry = self._validate_telemetry(telemetry)
payload: Dict[str, Any] = {"role": role}
if parts is not None:
payload["parts"] = parts
@@ -872,12 +882,15 @@ class AsyncHTTPClient(BaseClient):
payload["created_at"] = created_at
if role_id is not None:
payload["role_id"] = role_id
+ if telemetry is not False:
+ payload["telemetry"] = telemetry
response = await self._http.post(
f"/api/v1/sessions/{session_id}/messages",
json=payload,
)
- return self._handle_response(response)
+ response_data = self._handle_response_data(response)
+ return self._attach_telemetry(response_data.get("result"), response_data)
# ============= Pack =============
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
index 4e850cb03..e1a625bb8 100644
--- a/openviking_cli/client/sync_http.py
+++ b/openviking_cli/client/sync_http.py
@@ -82,14 +82,16 @@ class SyncHTTPClient:
"""Check whether a session exists in storage."""
return run_async(self._async_client.session_exists(session_id))
- def create_session(self, session_id: Optional[str] = None) -> Dict[str, Any]:
+ def create_session(
+ self, session_id: Optional[str] = None, telemetry: TelemetryRequest = False
+ ) -> Dict[str, Any]:
"""Create a new session.
Args:
session_id: Optional session ID. If provided, creates a session with the given ID.
If None, creates a new session with auto-generated ID.
"""
- return run_async(self._async_client.create_session(session_id))
+ return run_async(self._async_client.create_session(session_id, telemetry=telemetry))
def list_sessions(self) -> List[Any]:
"""List all sessions."""
@@ -119,6 +121,7 @@ class SyncHTTPClient:
parts: list[dict] | None = None,
created_at: str | None = None,
role_id: str | None = None,
+ telemetry: TelemetryRequest = False,
) -> Dict[str, Any]:
"""Add a message to a session.
@@ -133,7 +136,15 @@ class SyncHTTPClient:
If both content and parts are provided, parts takes precedence.
"""
return run_async(
- self._async_client.add_message(session_id, role, content, parts, created_at, role_id)
+ self._async_client.add_message(
+ session_id,
+ role,
+ content,
+ parts,
+ created_at,
+ role_id,
+ telemetry,
+ )
)
def get_task(self, task_id: str) -> Optional[Dict[str, Any]]: