8cabc0191c
- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook) - developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added - engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview) - OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update - VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added - .gitignore: exclude session artifacts, build artifacts, and agent workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
136 lines
4.0 KiB
Markdown
136 lines
4.0 KiB
Markdown
# Use the Analytics Dashboard
|
||
|
||
This guide explains how to query the three analytics endpoints to understand your organization's
|
||
token usage and agent activity patterns.
|
||
|
||
All analytics endpoints require Bearer token authentication and are scoped to the organization
|
||
embedded in your token.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
- A running AgentIdP instance
|
||
- A valid Bearer token with `organization_id` in its claims
|
||
- At least one agent registered and some token issuance activity
|
||
|
||
---
|
||
|
||
## Token issuance trend
|
||
|
||
`GET /api/v1/analytics/tokens`
|
||
|
||
Returns daily token issuance counts for the past N days (default 30, max 90). Use this to
|
||
track usage growth, identify traffic spikes, and plan capacity.
|
||
|
||
```bash
|
||
curl -s "http://localhost:3000/api/v1/analytics/tokens?days=30" \
|
||
-H "Authorization: Bearer $TOKEN" | jq .
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
|
||
"days": 30,
|
||
"data": [
|
||
{ "date": "2026-03-06", "count": 142 },
|
||
{ "date": "2026-03-07", "count": 198 },
|
||
{ "date": "2026-03-08", "count": 0 }
|
||
]
|
||
}
|
||
```
|
||
|
||
**Interpreting the data**: Each item in `data` is one calendar day (UTC) with the number of
|
||
tokens issued on that day. Days with zero issuance are included with `count: 0`. The array
|
||
is ordered chronologically, oldest first.
|
||
|
||
**Using it**: Compare day-over-day counts to identify growth or anomalies. A sudden spike in
|
||
`count` may indicate an agent retry loop or a credential leak. Zero-count days during expected
|
||
operation may indicate a deployment issue.
|
||
|
||
**Query parameter**: `days` — positive integer, max 90. Returns `400 VALIDATION_ERROR` if
|
||
exceeded.
|
||
|
||
```bash
|
||
# Last 7 days
|
||
curl -s "http://localhost:3000/api/v1/analytics/tokens?days=7" \
|
||
-H "Authorization: Bearer $TOKEN" | jq .
|
||
|
||
# Last 90 days (maximum)
|
||
curl -s "http://localhost:3000/api/v1/analytics/tokens?days=90" \
|
||
-H "Authorization: Bearer $TOKEN" | jq .
|
||
```
|
||
|
||
---
|
||
|
||
## Agent activity heatmap
|
||
|
||
`GET /api/v1/analytics/agents/activity`
|
||
|
||
Returns request counts grouped by day-of-week (0 = Sunday, 6 = Saturday) and hour (0–23, UTC).
|
||
Use this to identify peak usage windows for capacity planning and rate limit tuning.
|
||
|
||
```bash
|
||
curl -s "http://localhost:3000/api/v1/analytics/agents/activity" \
|
||
-H "Authorization: Bearer $TOKEN" | jq .
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
|
||
"data": [
|
||
{ "dow": 1, "hour": 9, "count": 54 },
|
||
{ "dow": 1, "hour": 10, "count": 87 },
|
||
{ "dow": 3, "hour": 14, "count": 201 }
|
||
]
|
||
}
|
||
```
|
||
|
||
**Interpreting the data**: `dow` is 0 (Sunday) through 6 (Saturday). `hour` is 0–23 UTC.
|
||
Only non-zero cells are returned — missing combinations had zero activity. Sort by `count`
|
||
descending to find your peak windows.
|
||
|
||
**Using it**: If most activity is on weekday mornings UTC, ensure your rate limit headroom
|
||
covers that window. If weekend activity is unexpectedly high, investigate which agents are
|
||
active.
|
||
|
||
---
|
||
|
||
## Per-agent usage summary
|
||
|
||
`GET /api/v1/analytics/agents`
|
||
|
||
Returns token issuance counts per agent for the current calendar month (UTC). Use this to
|
||
identify your most active agents and check if any single agent is consuming a
|
||
disproportionate share of your monthly token budget.
|
||
|
||
```bash
|
||
curl -s "http://localhost:3000/api/v1/analytics/agents" \
|
||
-H "Authorization: Bearer $TOKEN" | jq .
|
||
```
|
||
|
||
Response:
|
||
|
||
```json
|
||
{
|
||
"tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
|
||
"month": "2026-04",
|
||
"data": [
|
||
{ "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tokenCount": 312 },
|
||
{ "agentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "tokenCount": 87 }
|
||
]
|
||
}
|
||
```
|
||
|
||
**Interpreting the data**: Each item shows an agent UUID and the number of tokens it has
|
||
issued this month. The response covers the full current calendar month from day 1 to now.
|
||
It resets on the first day of each month.
|
||
|
||
**Using it**: Cross-reference `agentId` values against `GET /api/v1/agents` to identify which
|
||
agents by name. If one agent accounts for >80% of usage, investigate whether it is token
|
||
caching correctly or requesting tokens unnecessarily.
|