zuplo · martyndavies · May 15, 2026
diff --git a/docs/analytics/access-and-entitlements.md b/docs/analytics/access-and-entitlements.md
@@ -0,0 +1,71 @@
+---
+title: "Access and Entitlements"
+sidebar_label: "Access & Entitlements"
+---
+
+## When to use this
+
+- Confirm whether your account can see advanced analytics.
+- Find out how many days of history you have access to.
+- Understand the trial banner or the demo mode link.
+
+## Plan requirements
+
+Advanced analytics must be enabled on your account. Without it, the Analytics
+page shows an upsell view with a **Contact Sales** call-to-action and no charts.
+
+## Free trial
+
+New accounts with advanced analytics enabled get an automatic free trial. The
+trial:
+
+- Runs for the same number of days as your account's retention window.
+- Shows a banner across the top of the Analytics page: "You're on a {N}-day
+  preview of Advanced Analytics, {N} days left."
+- Includes two call-to-actions: **View demo →** (loads the dashboard with sample
+  data) and **Contact sales**.
+
+Accounts on the legacy analytics version are not eligible for the trial. They
+continue to use the previous experience.
+
+:::note
+
+The trial banner notes that the charts may look sparse if your account hasn't
+yet generated much traffic. Use **View demo →** to see what a fully populated
+dashboard looks like.
+
+:::
+
+## Data retention
+
+Each account has an analytics history window measured in days. The window
+controls:
+
+- How far back you can scroll using the time-range picker.
+- Which presets in the picker are available. Presets longer than your window are
+  locked with an **Upgrade for [preset]** tooltip.
+- The maximum start and end values when you pick a custom range.
+
+If you need a longer window, contact your Zuplo account team.
+
+## Demo mode
+
+Append `?demo=true` to the Analytics URL, or click **View demo →** in the trial
+banner, to switch into demo mode. In demo mode:
+
+- Charts and tables are populated with synthetic sample data.
+- A persistent banner reads: "You're viewing the Advanced Analytics demo with
+  sample data. Your real analytics aren't shown here."
+
+Remove the `demo` parameter from the URL to return to your real data.
+
+## Scope: account vs project
+
+- **Account scope** aggregates across every project in the account. The Requests
+  tab adds **Project Name** and **Deployment Name** as breakdowns; click a
+  project name to drill into project scope.
+- **Project scope** filters to a single project and adds an **Environment**
+  selector (Working Copy, Production, Preview, Other) in the top bar.
+
+See [Shared controls](./shared-controls.md) for how scope affects filters and
+breakdowns.
diff --git a/docs/analytics/overview.md b/docs/analytics/overview.md
@@ -0,0 +1,65 @@
+---
+title: "Analytics"
+sidebar_label: "Overview"
+---
+
+Zuplo Analytics is the dashboard inside the Zuplo portal that shows how traffic
+moves through your gateway: request volume, latency, errors, who's calling you,
+and (when relevant) AI gateway and MCP gateway activity. It's the page you open
+when something looks off in production, when you're auditing spend, or when
+you're answering "is anyone actually using this endpoint?"
+
+## When to use this
+
+- Investigate a latency spike or error surge across all projects in your
+  account, or inside a single project.
+- Identify which API consumers, AI agents, or upstream origins drive the most
+  traffic or errors.
+- Track AI gateway token usage and cost, or MCP gateway and server activity.
+
+## How to access
+
+Open **Analytics** in the Zuplo portal sidebar. The page works at two scopes:
+
+- **Account scope**: aggregates across every project in your account. Open
+  [Account Analytics](https://portal.zuplo.com/+/account/analytics).
+- **Project scope**: open a project, then click **Analytics**. Filters to one
+  project and adds an **Environment** selector.
+
+## What's in this section
+
+- [Access and entitlements](./access-and-entitlements.md): plans, free trial,
+  demo mode, retention.
+- [Shared controls](./shared-controls.md): time range, filters, environment
+  selector, banners, URL state.
+- Tabs:
+  - [Requests](./tabs/requests.md): overall traffic, latency, errors.
+  - [Origins](./tabs/origins.md): backend performance.
+  - [Consumers](./tabs/consumers.md): per-consumer breakdowns.
+  - [Agents](./tabs/agents.md): classified AI agent traffic.
+  - [AI Gateway](./tabs/ai-gateway.md): LLM request volume, tokens, cost.
+  - [MCP Gateway](./tabs/mcp-gateway.md): virtual server routing, capability
+    invocations, upstream health.
+  - [MCP Server](./tabs/mcp-server.md): tool calls, resources, prompts on
+    Zuplo-hosted MCP servers.
+- Reference:
+  - [Metrics glossary](./reference/metrics-glossary.md): every KPI and
+    percentile defined once.
+  - [URL parameters](./reference/url-parameters.md): permalink reference.
+
+## Tab visibility
+
+You'll see a subset of tabs depending on your plan and project setup:
+
+| Tab         | When it appears                                                       |
+| ----------- | --------------------------------------------------------------------- |
+| Requests    | All accounts with advanced analytics enabled.                         |
+| Origins     | The project uses managed-edge origins.                                |
+| Consumers   | All accounts with advanced analytics enabled.                         |
+| Agents      | All accounts with advanced analytics enabled.                         |
+| AI Gateway  | The project type is **ai**.                                           |
+| MCP Gateway | The project type is **standard** and an MCP gateway is in use.        |
+| MCP Server  | The project type is **standard** and the project hosts an MCP server. |
+
+If you don't see Analytics at all, your account likely doesn't have advanced
+analytics enabled. See [Access and entitlements](./access-and-entitlements.md).
diff --git a/docs/analytics/reference/metrics-glossary.md b/docs/analytics/reference/metrics-glossary.md
@@ -0,0 +1,92 @@
+---
+title: "Metrics Glossary"
+sidebar_label: "Metrics Glossary"
+---
+
+This page defines every term used in the Analytics dashboards once. KPI tables
+on tab pages link here for depth.
+
+## HTTP status classes
+
+| Class | Meaning                                                                                         |
+| ----- | ----------------------------------------------------------------------------------------------- |
+| 2xx   | Success.                                                                                        |
+| 3xx   | Redirection.                                                                                    |
+| 4xx   | Client error. The caller sent something the gateway or backend rejected.                        |
+| 5xx   | Server error. The gateway, an upstream origin, or an MCP backend failed to fulfill the request. |
+
+## Error rates
+
+**Client error rate.** 4xx count divided by total requests in the window,
+expressed as a percentage.
+
+**Server error rate.** 5xx count divided by total requests in the window.
+
+**Request-weighted average.** When aggregating a rate across many entities
+(consumers, agents, origins), each entity's rate is weighted by its request
+count. A consumer with 100,000 requests at a 1% error rate contributes more than
+a consumer with 100 requests at a 50% error rate. Use the request-weighted
+figure to answer "what does the average request experience look like?"; use a
+simple unweighted average to answer "what does the average consumer experience
+look like?"
+
+## Latency
+
+**Avg latency.** Arithmetic mean response time. Sensitive to outliers.
+
+**P50 (median) latency.** Half of requests completed within this time.
+
+**P95 latency.** 95% of requests completed within this time. The other 5% took
+longer. P95 is the standard tail-latency metric.
+
+**P99 latency.** 99% of requests completed within this time. Useful for spotting
+outlier behavior that P95 may smooth over.
+
+**Latency distribution histogram.** Bands at P10, P50, P90, P95, P99. Clicking a
+band on the Requests tab filters to requests in that duration range.
+
+## Active edge instances
+
+Distinct gateway worker instances actively serving traffic in each interval. A
+rough indicator of how widely your traffic is distributed.
+
+## Active sessions (MCP Server)
+
+Distinct MCP sessions, estimated using HyperLogLog. The figure is approximate
+but monotonic within a single time window. Accurate enough for trend analysis,
+not for exact session counting.
+
+## Failure origin
+
+Classifies an error by where it originated:
+
+| Origin   | Meaning                                                    |
+| -------- | ---------------------------------------------------------- |
+| gateway  | The Zuplo gateway returned the error.                      |
+| upstream | A backend origin or MCP server returned the error.         |
+| client   | The client sent something invalid that caused the failure. |
+
+## Outcome class
+
+Used on MCP Gateway events:
+
+| Class             | Meaning                                                              |
+| ----------------- | -------------------------------------------------------------------- |
+| success           | Event completed normally.                                            |
+| application_error | Event failed due to an application-layer issue (e.g. invalid input). |
+| gateway_error     | The gateway itself returned an error.                                |
+| upstream_error    | An upstream MCP server returned an error.                            |
+
+## Tokens (AI Gateway)
+
+| Type       | Meaning                                                   |
+| ---------- | --------------------------------------------------------- |
+| Prompt     | Tokens in the request the gateway forwarded to the model. |
+| Completion | Tokens in the model's response.                           |
+| Embedding  | Tokens consumed by embedding requests.                    |
+
+## Estimated cost (AI Gateway)
+
+Computed from token usage × the model's published pricing. Does not include
+discounts, credits, or provider-side rounding. Use it for trend analysis, not
+invoice reconciliation.
diff --git a/docs/analytics/reference/url-parameters.md b/docs/analytics/reference/url-parameters.md
@@ -0,0 +1,66 @@
+---
+title: "URL Parameters"
+sidebar_label: "URL Parameters"
+---
+
+Every Analytics control persists to the URL. Copy the address bar to share any
+view.
+
+## When to use this
+
+- Build a permalink to a specific time window, filter set, or demo view.
+- Embed an Analytics link in a runbook, postmortem, or dashboard.
+- Understand what each query parameter does.
+
+## Parameters
+
+| Parameter      | Example                                                | Effect                                                                                    |
+| -------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `time`         | `?time=7d`                                             | Apply a preset. Values: `1h`, `6h`, `24h`, `3d`, `7d`, `14d`, `28d`, `60d`, `90d`.        |
+| `start`, `end` | `?start=2026-05-01T00:00:00Z&end=2026-05-15T00:00:00Z` | Custom range as ISO-8601 datetimes. Overrides `time` when both are present.               |
+| `filter`       | `?filter=httpStatus:class:5xx`                         | Add a filter as `<field>:<matchmode>:<value>`. Repeat the parameter for multiple filters. |
+| `demo`         | `?demo=true`                                           | Demo mode (sample data instead of your real analytics).                                   |
+| `preview`      | `?preview=1`                                           | Legacy preview mode.                                                                      |
+
+## Match modes for `filter`
+
+| Mode       | Meaning               | Example                            |
+| ---------- | --------------------- | ---------------------------------- |
+| equals     | Exact match.          | `filter=httpMethod:equals:POST`    |
+| contains   | Substring match.      | `filter=route:contains:/v1/users`  |
+| in         | Comma-separated list. | `filter=httpStatus:in:500,502,503` |
+| not        | Negation of equals.   | `filter=country:not:US`            |
+| class      | HTTP status class.    | `filter=httpStatus:class:5xx`      |
+| startsWith | String prefix.        | `filter=route:startsWith:/v1/`     |
+| endsWith   | String suffix.        | `filter=route:endsWith:.json`      |
+
+## Permalink examples
+
+Last 7 days of 5xx errors on a specific route:
+
+```
+?time=7d&filter=httpStatus:class:5xx&filter=route:startsWith:/v1/users
+```
+
+Custom range with two filters:
+
+```
+?start=2026-05-01T00:00:00Z&end=2026-05-08T00:00:00Z&filter=country:equals:US&filter=httpMethod:equals:POST
+```
+
+Open the demo:
+
+```
+?demo=true
+```
+
+## Sharing
+
+The recipient sees the same view, provided they have access to the project or
+account.
+
+## See also
+
+- [Shared controls](../shared-controls.md): what each control does in the UI.
+- [Metrics glossary](./metrics-glossary.md): definitions for the fields you can
+  filter on.