stacklok / stacklok/toolhive

[vMCP] Expose active backend sessions on health endpoint

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

Nobody has claimed this yet.

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

Description

Depends on #3866

Session lifecycle events and periodic session counts should be logged for operational debugging and compliance auditing when sessionManagementV2 is enabled.

Required logging

On session creation (CreateSession):

  • Log at Info level with: session ID, backend count, backend names

On session termination/expiry (Terminate):

  • Log at Info level with: session ID, backend count

Periodic active session summary (every 1 minute):

  • Log at Info level with: total active session count, per-backend session counts

Implementation

  • Manager.CreateSession(): log at Info when a session is fully created
  • Manager.Terminate(): log at Info with backend count for MultiSessions; log placeholder termination separately
  • Manager.StartPeriodicLogging(ctx, interval): background goroutine that calls internal logActiveSessions() on a ticker
  • logActiveSessions(): iterates sessions via Range(), aggregates per-backend counts, logs summary
  • Called from Server.Start() when SessionManagementV2 is enabled, with a 1-minute default interval

Acceptance Criteria

  • Session creation is logged at Info with session ID, backend count, and backend names
  • Session termination is logged at Info with session ID and backend count
  • Active sessions are periodically logged at Info with total count and per-backend counts
  • No session IDs or backend session IDs are exposed over the network (logging only, to operators)
  • The periodic logger stops when the server context is cancelled
  • The implementation degrades gracefully with distributed storage backends (logs a one-time warning)

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 session manager methods Manager.CreateSession(), Manager.Terminate(), Range(), and Server.Start(), then inspect the RFC and dependency issue #3866 for lifecycle context. Implement and verify creation, termination, periodic aggregation, cancellation, and distributed-storage warning behavior against the listed acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend, observability
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.