stacklok / stacklok/toolhive

[vMCP] Add observability for session lifecycle (Phase 4)

Open
#3,873 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

audit enhancement logging telemetry vmcp
Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Depends on #3872

Add comprehensive telemetry for the new session lifecycle to support performance validation, debugging, and operational monitoring.

Audit logs: emit a session_created event per session containing session ID, count of successfully initialized backends, count of failed backends, and the map of backend session IDs.

Metrics:

  • vmcp_session_backend_init_duration_seconds — histogram by backend
  • vmcp_session_backend_init_success_total — counter by backend
  • vmcp_session_backend_init_failure_total — counter by backend with reason label
  • vmcp_session_tool_call_duration_seconds — histogram (demonstrates latency improvement)
  • vmcp_active_sessions — gauge tracking current number of active vMCP sessions
  • vmcp_backend_connections_total — counter of total backend connections opened
  • vmcp_sessions_rejected_total — counter of sessions rejected (e.g. due to limit enforcement), with reason label

Traces: distributed trace spanning session creation through first tool call.

Files: pkg/vmcp/session/default_session.go, pkg/vmcp/session/factory.go

Acceptance Criteria
  • session_created audit log event is emitted on every session creation with session ID, backend counts, and backend session ID map
  • All seven metrics are emitted with correct labels
  • vmcp_active_sessions reflects the real-time count of active sessions and decrements on session termination or expiry
  • vmcp_sessions_rejected_total is incremented whenever a session is rejected, with a reason label (e.g. global_limit, per_client_limit)
  • Distributed traces span from session creation through the first tool call
  • No credentials or sensitive data appear in logs, metrics, or traces
  • Tests verify audit log fields, metric emission, and trace presence

RFC: THV-0038 — Session-scoped client lifecycle

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked THV-0038 RFC, then inspect pkg/vmcp/session/default_session.go and pkg/vmcp/session/factory.go to understand the session lifecycle and instrumentation points. Done means all seven metrics, the session_created audit event, lifecycle-spanning trace, sensitive-data safeguards, and tests for logs, metrics, and traces satisfy the acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.