# Analytics

> Track per-tool, per-member, and per-workspace usage with built-in analytics for every tool call.

Every tool call through the workspace gateway is logged to Cloudflare Analytics Engine. You get full visibility into what tools are being called, by whom, how often, and how fast.

---

## What Gets Tracked

Every `tools/call` request records:

| Field | Description |
|-------|-------------|
| `token_id` | Which token made the call (identifies the member or integration) |
| `workspace_id` | Which workspace the call was routed through |
| `server_slug` | Which MCP server handled the call |
| `tool_name` | The specific tool that was called |
| `duration_ms` | How long the upstream server took to respond |
| `status` | Success or failure |
| `timestamp` | When the call occurred |

---

## Viewing Analytics

### Dashboard

Open your workspace in the Admin dashboard and click the **Analytics** tab. The dashboard shows:

**Overview Panel**
- Total tool calls (today, this week, this month)
- Success rate
- Average response time
- Active tokens

**Tool Breakdown**
- Calls per tool, sorted by frequency
- Average duration per tool
- Error rate per tool

**Member Activity**
- Calls per member (identified by token name)
- Most-used tools per member
- Activity timeline

**Server Health**
- Calls per server
- Average latency per server
- Error rate per server

---

## Use Cases

### Identify Popular Tools

See which tools your team uses most. This helps you decide which MCP servers are worth keeping, which need better configuration, and where to invest in custom tools.

### Debug Slow Tools

The duration breakdown shows which tools are slow. If a server consistently takes more than a few seconds, you may need to optimize it, increase its timeout, or replace it with a faster alternative.

### Monitor Bot Behavior

If a workspace powers a bot, analytics show exactly how the bot is using tools. You can see if the bot is calling the right tools, if it is making excessive calls, or if certain tools are failing.

### Track Team Usage

With per-member analytics, you can see who is using the workspace, how often, and which tools they rely on. This is useful for understanding adoption and identifying team members who might need help getting started.

### Billing Visibility

Tool calls count toward your plan's MCP proxy call limit. The analytics dashboard shows your current usage against your limit, so you can anticipate when you might need to upgrade.

---

## Analytics Retention

| Plan | Retention |
|------|-----------|
| Free | 7 days |
| Starter | 30 days |
| Pro | 90 days |
| Business | 1 year |
| Enterprise | Custom |

---

## Querying Analytics Programmatically

Analytics data is available through the Aerostack API for programmatic access:

```bash
# Get workspace analytics summary
curl https://api.aerostack.dev/api/community/mcp/workspaces/WORKSPACE_ID/analytics \
  -H "Authorization: Bearer YOUR_JWT"
```

The response includes aggregated metrics for the requested time range.

  Analytics are powered by Cloudflare Analytics Engine, which provides near-real-time data. There may be a delay of up to 30 seconds between a tool call and its appearance in analytics.

---

## Observability in the Dashboard

Beyond analytics, the dashboard provides a **Logs** view for real-time debugging:

- **Live log stream** -- see tool calls as they happen
- **Error details** -- view the full error message and upstream response for failed calls
- **Latency waterfall** -- understand where time is spent (gateway processing vs. upstream server)
- **Filter by tool, server, or member** -- narrow down to specific calls

This is particularly useful when setting up a new workspace or debugging why a tool is not working as expected.