[enhance] nâng cấp dashboard và cơ chế tracking

[mrgoonie]

Proposal

Nâng cấp dashboard và cơ chế tracking để quan sát usage/cost/hiệu quả vận hành của GoClaw chi tiết hơn.

Các hướng chính:

• Đếm lượt requests.
• Đếm lượt sử dụng agent.
• Đếm lượt sử dụng skill.
• Đếm lượt sử dụng tools / MCP / runtime packages / CLI commands / connectors nếu phù hợp.
• Dashboard trực quan với các thống kê đầy đủ hơn.
• Theo dõi số tokens sử dụng, có thể filter theo:
  • từng agent
  • từng skill
  • từng tool
  • từng MCP server/tool
  • từng runtime package / command nếu có tracking được
  • khoảng thời gian
  • user / org / channel nếu phù hợp với permission model

Motivation

Hiện tại cần có visibility tốt hơn để:

• Biết agent nào được dùng nhiều.
• Biết skill/tool nào tạo nhiều usage/cost.
• Theo dõi token consumption theo chiều agent/skill/tool.
• Phát hiện spike bất thường hoặc misuse.
• Có số liệu để tối ưu UX, pricing, quota, billing, và vận hành.
• Hỗ trợ admin/debug khi user báo tốn token hoặc tool chạy nhiều.

Gợi ý dashboard metrics

Usage overview

• Total requests theo ngày/tuần/tháng.
• Active agents.
• Active users.
• Active channels.
• Total tool calls.
• Total skill activations.
• Total MCP calls.
• Total runtime package/CLI executions nếu có.

Token analytics

• Input tokens.
• Output tokens.
• Total tokens.
• Tokens by agent.
• Tokens by skill.
• Tokens by tool/MCP.
• Tokens by channel/session/user/org.
• Token trend over time.

Tool / skill analytics

• Top skills by usage.
• Top tools by call count.
• Top tools by token/cost impact nếu đo được.
• Error rate per tool/MCP.
• Latency per tool/MCP.
• Runtime package/CLI usage count.

Agent analytics

• Requests per agent.
• Tokens per agent.
• Tool calls per agent.
• Skill usage per agent.
• Success/failure/error distribution.
• Avg response time.

UI ideas

• Date range filter.
• Org/user/channel/agent filters.
• Drill-down từ overview → agent → session/request → tool calls.
• Export CSV/JSON.
• Charts:
  • time series usage/token trend
  • stacked bar tokens by agent/tool
  • top-N tables
  • error-rate cards
  • latency distribution

Open questions / cần thảo luận thêm

• Tracking granularity nên ở mức request/session/message/tool-call hay event stream?
• Có cần lưu raw prompt/response không, hay chỉ metadata để tránh privacy risk?
• Token attribution cho skill/tool nên tính thế nào khi skill chỉ là instruction layer còn model call là chung?
• MCP/tool cost attribution có cần chuẩn hoá schema riêng không?
• Runtime package tracking nên tính theo command execution, package import, hay tool call?
• Data retention bao lâu?
• Có cần quota/billing alert từ metrics này không?
• Dashboard permission model: admin thấy gì, owner thấy gì, shared agent member thấy gì?

Acceptance direction

Issue này là proposal/enhancement, cần thảo luận thêm chi tiết trước khi implement. Mục tiêu trước mắt là thống nhất schema tracking + dashboard UX + quyền truy cập dữ liệu.

[mrgoonie]

Plan handoff cho Issue #107 đã sẵn sàng.

Branch: codex/issue-107-usage-analytics-plan

Plan path:
/Users/duynguyen/.codex/worktrees/441c/goclaw/plans/260612-1530-issue-107-usage-event-analytics/plan.md

Reports:

• Brainstorm: plans/reports/260612-1529-issue-107-usage-analytics-brainstorm.md
• Validation: plans/260612-1530-issue-107-usage-event-analytics/reports/260612-1530-plan-validation.md
• Red-team: plans/260612-1530-issue-107-usage-event-analytics/reports/260612-1530-plan-red-team.md

Tóm tắt plan:

• Dùng approach B: thêm usage_events append-only + usage_event_rollups theo giờ, không nhồi thêm dimension mới vào usage_snapshots.
• V1 không có per-user analytics/filter.
• Skill usage chỉ count từ use_skill và slash-command activation.
• Runtime analytics count mọi runtime tool call qua canonical tool name, không parse shell/CLI command text.
• Giữ backward compatibility cho /v1/usage/timeseries, /v1/usage/breakdown, /v1/usage/summary.
• TDD phases: characterization tests -> schema/store dual DB -> telemetry attribution -> rollup/API -> dashboard -> docs/handoff.

Validation:

• ck plan validate --strict plans/260612-1530-issue-107-usage-event-analytics/plan.md pass: 6 phases, 0 errors, 0 warnings.
• Red-team accepted 8 findings; plan updated; unresolved questions: none.

Note: plans/ is gitignored in this repo, so the plan path above is workspace-local on the branch.

Label: ready to cook.

[mrgoonie]

Beta implementation ready for review.

Branch: codex/issue-107-usage-analytics-plan
PR: #176
Plan: /Users/duynguyen/.codex/worktrees/441c/goclaw/plans/260612-1530-issue-107-usage-event-analytics/plan.md (workspace-local; plans/ is gitignored)

Summary:

• Added append-only usage_events + hourly usage_event_rollups for PostgreSQL and SQLite.
• Counts use_skill, slash-command skill activation, regular tool calls, MCP tool calls, and all runtime tool calls via canonical tool names.
• No per-user event analytics; event endpoints reject user_id filter.
• Added /v1/usage/events/{summary,breakdown,timeseries} and Usage dashboard resource tabs.
• Metadata avoids raw prompts, tool args, outputs, and shell commands.

Validation passed:

• /usr/local/go/bin/go test ./...
• /usr/local/go/bin/go test -tags sqliteonly ./internal/store/sqlitestore
• /usr/local/go/bin/go vet ./...
• /usr/local/go/bin/go build ./...
• /usr/local/go/bin/go build -tags sqliteonly ./...
• pnpm -C ui/web build (passes; existing chunk-size warning only)

Label moving from ready to cook to ready to ship beta.