feat(069-A3): GET /api/v1/activity/usage endpoint#565
Merged
Conversation
Serve the actor-owned usage aggregate (spec 069 A2) over REST so the Web UI usage graphs (B1/B2) have a contract to consume. Reads the in-memory snapshot only — never a per-request full-log scan (SC-005). - contracts: UsageAggregateResponse + UsageToolStat / UsageOtherBucket / UsageTimeBucket. - handler: handleActivityUsage with window (24h/7d/all), server/tool/status membership filters (FR-008), sort (calls/resp_bytes/error_rate/p95), top-N + 'other' fold, empty-state 200 (FR-009), 400 on bad enum/top. avg_* computed over sized (non-zero-byte) calls only; tokens_saved echoed from ServerTokenMetrics (FR-007). Short-TTL read cache keyed on the query honours observability.usage_cache_ttl (FR-005, hot-reloaded per request). - controller: UsageSnapshot() exposed through server -> runtime -> ActivityService. - oas: swag-generated path + schemas; verify-oas-coverage passes. Windowing note: per-tool metrics are lifetime-cumulative (the A2 aggregate keeps cumulative per-tool rollups + global hourly timeline buckets, no per-tool-per-window data); window scopes the timeline span and filters the tool list to tools active within it. Exact per-tool windowed counts are a deferred follow-on (would need per-tool time buckets in the aggregate). Tests: TestActivityUsage_* (ranking/error_rate/avg-excludes-0-byte/window/ top-N/filters/empty-state/400) replay records through the real Apply path; TestActivityUsage_NoFullScanPerRequest is the SC-005 perf assertion. Related #745
Deploying mcpproxy-docs with
|
| Latest commit: |
f65d840
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://01e322eb.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://069-a3-activity-usage-endpoi.mcpproxy-docs.pages.dev |
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 26765067958 --repo smart-mcp-proxy/mcpproxy-go
|
This was referenced Jun 2, 2026
Dumbris
added a commit
that referenced
this pull request
Jun 2, 2026
) Spec 069 Stream B1 (T016–T017). Adds the Overview↔Usage switcher to the dashboard and the typed client for the A3 GET /api/v1/activity/usage endpoint (#565). - api: getActivityUsage(params) forwards only supplied filters (window/server/tool/status/top/sort); UsageAggregateResponse + UsageToolStat/UsageOtherBucket/UsageTimeBucket types mirror the contract. - Dashboard: tabbed Overview↔Usage switcher rendered with v-show (never v-if) so Overview state survives a switch-back (SC-006). Usage panel has a 24h/7d/all window selector, tokens-saved headline (FR-007), loading/error/empty states (FR-009) and a baseline per-tool rollup table; the rich charts arrive in B2 (T018–T022). - Lazy load: the aggregate is fetched on first Usage activation and on window change only, so the Overview first paint is never blocked (SC-004). - Tests (TDD): activity-usage.spec (client param forwarding) + dashboard-usage-switcher.spec (default tab, lazy fetch, v-show preserve, window refetch). All 91 frontend unit tests green; vue-tsc clean. Related #745
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Spec 069 A3 (MCP-750) — usage statistics endpoint
Backend stream A3:
GET /api/v1/activity/usage, serving the actor-owned usage aggregate (shipped in A2 / #560) over REST. This publishes the contract the frontend (B1/B2) consumes and unblocks those streams.Reads the in-memory snapshot only — never a per-request full-log scan (SC-005).
What's in it (tasks T011–T015, T024–T026)
UsageAggregateResponse+UsageToolStat/UsageOtherBucket/UsageTimeBucket.handleActivityUsage:window(24h/7d/all),server/tool/statusmembership filters (FR-008),sort(calls/resp_bytes/error_rate/p95),topN +otherfold.avg_resp_bytes/avg_req_bytesover sized (non-zero-byte) calls only →nullwhen none;tokens_savedechoed fromServerTokenMetrics(FR-007);token_source: "bytes"(FR-006).window/sort/statusenum or non-positivetop.observability.usage_cache_ttl(FR-005), read per request so it hot-reloads.UsageSnapshot()exposed throughserver → runtime → ActivityService.verify-oas-coverage.shpasses in CI.Design note — windowing semantics
The A2 aggregate keeps cumulative per-tool rollups + global hourly timeline buckets (no per-tool-per-window data). So:
windowscopes the timeline span and filters the tool list to tools active within it (bylast_used).Exact per-tool windowed counts are a deferred follow-on (would require per-tool time buckets in the aggregate). Documented in the contract type, the swagger description, and
tasks.md.Deviation from tasks.md
T013 suggested reusing
parseActivityFilters. That parser silently ignores bad input (no 400s) and handles unrelated pagination/detection filters. The usage endpoint needs strict enum validation for its own params (window/sort/top), so it uses a dedicatedparseUsageParamswhile keeping the sharedserver/tool/statusparam names consistent.Verification
go test ./internal/httpapi/— newTestActivityUsage_*green (ranking, error_rate, avg-excludes-0-byte, window, top-N, filters, empty-state, 400). Tests replay records through the realApplypath so latency/sized math is exercised, not mocked.TestActivityUsage_NoFullScanPerRequest— SC-005 perf assertion (handler never callsAggregateToolUsage).go test ./internal/runtime/... -race— all green (canary safe)../scripts/test-api-e2e.sh— 65/65 passed../scripts/run-linter.sh— 0 issues.tools: []/timeline: []; badwindow/top→ 400.Related #745
🤖 Generated with Claude Code