zuplo 6.70.69 → 6.70.71
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/ai-gateway/getting-started.mdx +14 -9
- package/docs/ai-gateway/integrations/ai-sdk.mdx +17 -0
- package/docs/ai-gateway/introduction.mdx +12 -10
- package/docs/ai-gateway/providers.mdx +2 -0
- package/docs/analytics/access-and-entitlements.md +71 -0
- package/docs/analytics/overview.md +63 -0
- package/docs/analytics/reference/metrics-glossary.md +105 -0
- package/docs/analytics/reference/url-parameters.md +66 -0
- package/docs/analytics/shared-controls.md +121 -0
- package/docs/analytics/tabs/agents.md +88 -0
- package/docs/analytics/tabs/consumers.md +73 -0
- package/docs/analytics/tabs/graphql.md +77 -0
- package/docs/analytics/tabs/mcp.md +80 -0
- package/docs/analytics/tabs/origins.md +82 -0
- package/docs/analytics/tabs/requests.md +96 -0
- package/docs/articles/api-key-buckets.mdx +4 -2
- package/docs/articles/archiving-requests-to-storage.mdx +4 -4
- package/docs/articles/branch-based-deployments.mdx +10 -8
- package/docs/articles/ci-cd-github/basic-deployment.mdx +10 -1
- package/docs/articles/ci-cd-github/cleanup-on-branch-delete.mdx +52 -31
- package/docs/articles/ci-cd-github/deploy-and-test.mdx +14 -1
- package/docs/articles/ci-cd-github/local-testing.mdx +3 -1
- package/docs/articles/ci-cd-github/pr-preview-environments.mdx +53 -10
- package/docs/articles/custom-ci-cd-azure.mdx +1 -1
- package/docs/articles/custom-ci-cd-bitbucket.mdx +1 -1
- package/docs/articles/custom-ci-cd-circleci.mdx +1 -1
- package/docs/articles/custom-ci-cd-github.mdx +12 -3
- package/docs/articles/custom-ci-cd-gitlab.mdx +1 -1
- package/docs/articles/graphql.mdx +276 -0
- package/docs/articles/monetization/api-access.mdx +184 -0
- package/docs/articles/monetization/meters.mdx +4 -4
- package/docs/articles/monetization/monetization-policy.md +4 -1
- package/docs/articles/monetization/private-plans.md +3 -4
- package/docs/articles/monetization/stripe-integration.md +9 -0
- package/docs/articles/monetization/subscription-lifecycle.md +12 -11
- package/docs/articles/monorepo-deployment.mdx +37 -5
- package/docs/articles/opentelemetry.mdx +5 -2
- package/docs/articles/securing-the-gateway-with-client-mtls.mdx +68 -43
- package/docs/articles/step-1-setup-basic-gateway.mdx +1 -3
- package/docs/articles/step-2-add-rate-limiting.mdx +1 -1
- package/docs/articles/testing.mdx +1 -1
- package/docs/articles/troubleshooting.md +7 -3
- package/docs/articles/waf-ddos-akamai.md +35 -16
- package/docs/articles/waf-ddos-aws-waf-shield.mdx +35 -16
- package/docs/articles/waf-ddos-fastly.mdx +10 -7
- package/docs/cli/deploy.mdx +44 -9
- package/docs/cli/deploy.partial.mdx +44 -9
- package/docs/concepts/api-keys.md +2 -2
- package/docs/dev-portal/zudoku/components/callout.mdx +11 -18
- package/docs/dev-portal/zudoku/components/sidecar-box.mdx +131 -0
- package/docs/dev-portal/zudoku/configuration/api-catalog.md +62 -42
- package/docs/dev-portal/zudoku/configuration/api-reference.md +5 -4
- package/docs/dev-portal/zudoku/configuration/navigation.mdx +70 -7
- package/docs/dev-portal/zudoku/configuration/search.md +36 -0
- package/docs/dev-portal/zudoku/configuration/site.md +38 -0
- package/docs/dev-portal/zudoku/customization/colors-theme.mdx +51 -40
- package/docs/errors/rate-limit-exceeded.mdx +30 -3
- package/docs/guides/canary-routing-for-employees.mdx +103 -39
- package/docs/guides/modify-openapi-paths.mdx +3 -3
- package/docs/handlers/legacy-dev-portal-handler.mdx +1 -1
- package/docs/handlers/mcp-server.mdx +13 -11
- package/docs/handlers/url-forward.mdx +5 -1
- package/docs/handlers/url-rewrite.mdx +7 -2
- package/docs/handlers/websocket-handler.mdx +5 -1
- package/docs/mcp-gateway/observability/logging.mdx +19 -12
- package/docs/mcp-server/resources.mdx +27 -15
- package/docs/mcp-server/testing.mdx +0 -2
- package/docs/policies/_index.md +2 -0
- package/docs/policies/archive-request-azure-storage-inbound/doc.md +1 -1
- package/docs/policies/archive-response-azure-storage-outbound/doc.md +1 -1
- package/docs/policies/data-loss-prevention-inbound/doc.md +116 -0
- package/docs/policies/data-loss-prevention-inbound/intro.md +15 -0
- package/docs/policies/data-loss-prevention-inbound/schema.json +220 -0
- package/docs/policies/data-loss-prevention-outbound/doc.md +116 -0
- package/docs/policies/data-loss-prevention-outbound/intro.md +18 -0
- package/docs/policies/data-loss-prevention-outbound/schema.json +220 -0
- package/docs/policies/ip-restriction-inbound/policy.ts +1 -1
- package/docs/programmable-api/background-dispatcher.mdx +6 -8
- package/docs/programmable-api/http-problems.mdx +0 -18
- package/docs/programmable-api/jwt-service-plugin.mdx +131 -109
- package/docs/programmable-api/runtime-behaviors.mdx +4 -2
- package/docs/programmable-api/streaming-zone-cache.mdx +4 -6
- package/docs/programmable-api/web-crypto-apis.mdx +10 -6
- package/docs/programmable-api/zone-cache.mdx +1 -1
- package/docs/rate-limiting/combining-policies.mdx +293 -0
- package/docs/rate-limiting/dynamic-rate-limiting.mdx +240 -0
- package/docs/rate-limiting/getting-started.mdx +339 -0
- package/docs/rate-limiting/how-it-works.md +225 -0
- package/docs/rate-limiting/monitoring-and-troubleshooting.mdx +243 -0
- package/docs/{articles → rate-limiting}/per-user-rate-limits-using-db.mdx +39 -28
- package/package.json +4 -4
- package/docs/concepts/rate-limiting.md +0 -246
- package/docs/errors/get-head-body-error.mdx +0 -41
|
@@ -9,8 +9,8 @@ initial configuration to making your first LLM request through Zuplo.
|
|
|
9
9
|
## Prerequisites
|
|
10
10
|
|
|
11
11
|
- A Zuplo account (sign up free at [zuplo.com](https://zuplo.com))
|
|
12
|
-
- API keys for at least one LLM provider (OpenAI, Anthropic, Google
|
|
13
|
-
etc.)
|
|
12
|
+
- API keys for at least one LLM provider (OpenAI, Anthropic, Google, Mistral,
|
|
13
|
+
xAI, etc.)
|
|
14
14
|
- An application that needs to call LLM APIs
|
|
15
15
|
|
|
16
16
|
## Step 1: Create an AI Gateway Project
|
|
@@ -27,9 +27,9 @@ includes Apps, Teams, and a setup guide to help you get started.
|
|
|
27
27
|
|
|
28
28
|
## Step 2: Configure Providers
|
|
29
29
|
|
|
30
|
-
Providers are the LLM services (like OpenAI or
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
Providers are the LLM services (like OpenAI or Anthropic) that your applications
|
|
31
|
+
will use. You'll configure these once as an administrator, and your team members
|
|
32
|
+
can use them without needing direct access to provider API keys.
|
|
33
33
|
|
|
34
34
|
### Adding Your First Provider
|
|
35
35
|
|
|
@@ -43,13 +43,18 @@ team members can use them without needing direct access to provider API keys.
|
|
|
43
43
|
### Adding Additional Providers
|
|
44
44
|
|
|
45
45
|
Repeat the process above to add more providers. This allows your teams to switch
|
|
46
|
-
between providers (OpenAI,
|
|
46
|
+
between providers (OpenAI, Anthropic, etc.) without changing application code.
|
|
47
47
|
|
|
48
48
|
**Example providers you might add:**
|
|
49
49
|
|
|
50
50
|
- OpenAI (for GPT models)
|
|
51
|
-
-
|
|
52
|
-
-
|
|
51
|
+
- Anthropic (for Claude models)
|
|
52
|
+
- Google (for Gemini models)
|
|
53
|
+
- Mistral (for Mistral models)
|
|
54
|
+
- xAI (for Grok models)
|
|
55
|
+
|
|
56
|
+
See [AI Providers](./providers.mdx) for the full list of supported providers and
|
|
57
|
+
capabilities, including OpenAI-compatible custom providers.
|
|
53
58
|
|
|
54
59
|
## Step 3: Create a Team
|
|
55
60
|
|
|
@@ -202,7 +207,7 @@ Now that your AI Gateway is running, explore additional features:
|
|
|
202
207
|
### Switch Providers Without Code Changes
|
|
203
208
|
|
|
204
209
|
1. Go to your app settings
|
|
205
|
-
2. Change the **Provider** dropdown (for example, from OpenAI to
|
|
210
|
+
2. Change the **Provider** dropdown (for example, from OpenAI to Anthropic)
|
|
206
211
|
3. Select a new model
|
|
207
212
|
4. Click **Save Changes**
|
|
208
213
|
|
|
@@ -107,3 +107,20 @@ const { text } = await generateText({
|
|
|
107
107
|
prompt: "Write a one-sentence bedtime story about a unicorn.",
|
|
108
108
|
});
|
|
109
109
|
```
|
|
110
|
+
|
|
111
|
+
### xAI
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { createXai } from "@ai-sdk/xai";
|
|
115
|
+
import { generateText } from "ai";
|
|
116
|
+
|
|
117
|
+
const xai = createXai({
|
|
118
|
+
apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
|
|
119
|
+
baseURL: "https://my-ai-gateway.zuplo.app/v1",
|
|
120
|
+
});
|
|
121
|
+
|
|
122
|
+
const { text } = await generateText({
|
|
123
|
+
model: xai("grok-4"),
|
|
124
|
+
prompt: "Write a one-sentence bedtime story about a unicorn.",
|
|
125
|
+
});
|
|
126
|
+
```
|
|
@@ -4,16 +4,17 @@ sidebar_label: Introduction
|
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
Zuplo's AI Gateway acts as an intelligent proxy layer that sits between your
|
|
7
|
-
engineering team's applications and LLM providers like OpenAI,
|
|
8
|
-
and
|
|
9
|
-
providers, all requests flow through the Zuplo AI Gateway, which
|
|
10
|
-
responses while applying policies, controls, and monitoring.
|
|
7
|
+
engineering team's applications and LLM providers like OpenAI, Anthropic,
|
|
8
|
+
Google, Mistral, and xAI. Instead of your applications communicating directly
|
|
9
|
+
with these providers, all requests flow through the Zuplo AI Gateway, which
|
|
10
|
+
streams responses while applying policies, controls, and monitoring.
|
|
11
11
|
|
|
12
12
|
## Key Benefits
|
|
13
13
|
|
|
14
|
-
**Provider Independence**: Switch between LLM providers (OpenAI,
|
|
15
|
-
|
|
16
|
-
choice through the gateway rather than hard coding it
|
|
14
|
+
**Provider Independence**: Switch between LLM providers (OpenAI, Anthropic,
|
|
15
|
+
Google, Mistral, xAI, and more) dynamically without modifying application code.
|
|
16
|
+
Configure your provider choice through the gateway rather than hard coding it
|
|
17
|
+
into your applications.
|
|
17
18
|
|
|
18
19
|
**Cost Control**: Set spending limits at organization, team, and application
|
|
19
20
|
levels with hierarchical budgets that cascade down through your structure.
|
|
@@ -49,9 +50,10 @@ credentials.
|
|
|
49
50
|
### Multi-Provider Support
|
|
50
51
|
|
|
51
52
|
Configure multiple LLM providers within a single gateway project. Supported
|
|
52
|
-
providers include OpenAI
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
providers include OpenAI, Anthropic, Google, Mistral, xAI, and OpenAI-compatible
|
|
54
|
+
custom providers. See [AI Providers](./providers.mdx) for the full list of
|
|
55
|
+
providers and supported capabilities. Select which models are available to your
|
|
56
|
+
teams when configuring each provider.
|
|
55
57
|
|
|
56
58
|
### Team Hierarchy & Budgets
|
|
57
59
|
|
|
@@ -14,6 +14,7 @@ Zuplo currently supports the following AI providers:
|
|
|
14
14
|
- Anthropic
|
|
15
15
|
- Google
|
|
16
16
|
- Mistral
|
|
17
|
+
- xAI (Grok)
|
|
17
18
|
- OpenAI-compatible [Custom Providers](./custom-providers.mdx) (such as Qwen,
|
|
18
19
|
Kimi, etc)
|
|
19
20
|
|
|
@@ -25,6 +26,7 @@ The following capabilities are supported across providers:
|
|
|
25
26
|
| Anthropic | ✅ | ✅ | ✅ | ❌ |
|
|
26
27
|
| Google | ✅ | ✅ | ✅ | ❌ |
|
|
27
28
|
| Mistral | ✅ | ✅ | ✅ | ❌ |
|
|
29
|
+
| xAI | ✅ | ✅ | ✅ | ❌ |
|
|
28
30
|
| OpenAI-compatible (Custom) | ✅ | ✅ | ✅ | ❌ |
|
|
29
31
|
|
|
30
32
|
If you need support for additional providers or capabilities, please contact us
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Access and Entitlements"
|
|
3
|
+
sidebar_label: "Access & Entitlements"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## When to use this
|
|
7
|
+
|
|
8
|
+
- Confirm whether your account can see advanced analytics.
|
|
9
|
+
- Find out how many days of history you have access to.
|
|
10
|
+
- Understand the trial banner or the demo mode link.
|
|
11
|
+
|
|
12
|
+
## Plan requirements
|
|
13
|
+
|
|
14
|
+
Advanced analytics must be enabled on your account. Without it, the Analytics
|
|
15
|
+
page shows an upsell view with a **Contact Sales** call-to-action and no charts.
|
|
16
|
+
|
|
17
|
+
## Free trial
|
|
18
|
+
|
|
19
|
+
New accounts with advanced analytics enabled get an automatic free trial. The
|
|
20
|
+
trial:
|
|
21
|
+
|
|
22
|
+
- Runs for the same number of days as your account's retention window.
|
|
23
|
+
- Shows a banner across the top of the Analytics page: "You're on a {N}-day
|
|
24
|
+
preview of Advanced Analytics, {N} days left."
|
|
25
|
+
- Includes two call-to-actions: **View demo →** (loads the dashboard with sample
|
|
26
|
+
data) and **Contact sales**.
|
|
27
|
+
|
|
28
|
+
Accounts on the legacy analytics version are not eligible for the trial. They
|
|
29
|
+
continue to use the previous experience.
|
|
30
|
+
|
|
31
|
+
:::note
|
|
32
|
+
|
|
33
|
+
The trial banner notes that the charts may look sparse if your account hasn't
|
|
34
|
+
yet generated much traffic. Use **View demo →** to see what a fully populated
|
|
35
|
+
dashboard looks like.
|
|
36
|
+
|
|
37
|
+
:::
|
|
38
|
+
|
|
39
|
+
## Data retention
|
|
40
|
+
|
|
41
|
+
Each account has an analytics history window measured in days. The window
|
|
42
|
+
controls:
|
|
43
|
+
|
|
44
|
+
- How far back you can scroll using the time-range picker.
|
|
45
|
+
- Which presets in the picker are available. Presets longer than your window are
|
|
46
|
+
locked with an **Upgrade for [preset]** tooltip.
|
|
47
|
+
- The maximum start and end values when you pick a custom range.
|
|
48
|
+
|
|
49
|
+
If you need a longer window, contact your Zuplo account team.
|
|
50
|
+
|
|
51
|
+
## Demo mode
|
|
52
|
+
|
|
53
|
+
Append `?demo=true` to the Analytics URL, or click **View demo →** in the trial
|
|
54
|
+
banner, to switch into demo mode. In demo mode:
|
|
55
|
+
|
|
56
|
+
- Charts and tables are populated with synthetic sample data.
|
|
57
|
+
- A persistent banner reads: "You're viewing the Advanced Analytics demo with
|
|
58
|
+
sample data. Your real analytics aren't shown here."
|
|
59
|
+
|
|
60
|
+
Remove the `demo` parameter from the URL to return to your real data.
|
|
61
|
+
|
|
62
|
+
## Scope: account vs project
|
|
63
|
+
|
|
64
|
+
- **Account scope** aggregates across every project in the account. The Requests
|
|
65
|
+
tab adds **Project Name** and **Deployment Name** as breakdowns; click a
|
|
66
|
+
project name to drill into project scope.
|
|
67
|
+
- **Project scope** filters to a single project and adds an **Environment**
|
|
68
|
+
selector (Working Copy, Production, Preview, Other) in the top bar.
|
|
69
|
+
|
|
70
|
+
See [Shared controls](./shared-controls.md) for how scope affects filters and
|
|
71
|
+
breakdowns.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Analytics"
|
|
3
|
+
sidebar_label: "Overview"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Zuplo Analytics is the dashboard inside the Zuplo portal that shows how traffic
|
|
7
|
+
moves through your gateway: request volume, latency, errors, who's calling you,
|
|
8
|
+
and (when relevant) AI gateway and MCP gateway activity. It's the page you open
|
|
9
|
+
when something looks off in production, when you're auditing spend, or when
|
|
10
|
+
you're answering "is anyone actually using this endpoint?"
|
|
11
|
+
|
|
12
|
+
## When to use this
|
|
13
|
+
|
|
14
|
+
- Investigate a latency spike or error surge across all projects in your
|
|
15
|
+
account, or inside a single project.
|
|
16
|
+
- Identify which API consumers, AI agents, or upstream origins drive the most
|
|
17
|
+
traffic or errors.
|
|
18
|
+
- Track AI gateway token usage and cost, or MCP gateway and server activity.
|
|
19
|
+
|
|
20
|
+
## How to access
|
|
21
|
+
|
|
22
|
+
Open **Analytics** in the Zuplo portal sidebar. The page works at two scopes:
|
|
23
|
+
|
|
24
|
+
- **Account scope**: aggregates across every project in your account. Open
|
|
25
|
+
[Account Analytics](https://portal.zuplo.com/+/account/analytics).
|
|
26
|
+
- **Project scope**: open a project, then click **Analytics**. Filters to one
|
|
27
|
+
project and adds an **Environment** selector.
|
|
28
|
+
|
|
29
|
+
## What's in this section
|
|
30
|
+
|
|
31
|
+
- [Access and entitlements](./access-and-entitlements.md): plans, free trial,
|
|
32
|
+
demo mode, retention.
|
|
33
|
+
- [Shared controls](./shared-controls.md): time range, filters, environment
|
|
34
|
+
selector, banners, URL state.
|
|
35
|
+
- Tabs:
|
|
36
|
+
- [Requests](./tabs/requests.md): overall traffic, latency, errors.
|
|
37
|
+
- [Origins](./tabs/origins.md): backend performance.
|
|
38
|
+
- [Consumers](./tabs/consumers.md): per-consumer breakdowns.
|
|
39
|
+
- [Agents](./tabs/agents.md): classified AI agent traffic.
|
|
40
|
+
- [MCP](./tabs/mcp.md): virtual server routing, capability and tool
|
|
41
|
+
invocations, JSON-RPC methods, upstream health.
|
|
42
|
+
- [GraphQL](./tabs/graphql.md): operation volume, errors, resolver latency,
|
|
43
|
+
and query complexity.
|
|
44
|
+
- Reference:
|
|
45
|
+
- [Metrics glossary](./reference/metrics-glossary.md): every KPI and
|
|
46
|
+
percentile defined once.
|
|
47
|
+
- [URL parameters](./reference/url-parameters.md): permalink reference.
|
|
48
|
+
|
|
49
|
+
## Tab visibility
|
|
50
|
+
|
|
51
|
+
You'll see a subset of tabs depending on your plan and project setup:
|
|
52
|
+
|
|
53
|
+
| Tab | When it appears |
|
|
54
|
+
| --------- | ---------------------------------------------------------- |
|
|
55
|
+
| Requests | All accounts with advanced analytics enabled. |
|
|
56
|
+
| Origins | The project uses managed-edge origins. |
|
|
57
|
+
| Consumers | All accounts with advanced analytics enabled. |
|
|
58
|
+
| Agents | All accounts with advanced analytics enabled. |
|
|
59
|
+
| MCP | The project type is **standard** and the project uses MCP. |
|
|
60
|
+
| GraphQL | The project proxies a GraphQL API. |
|
|
61
|
+
|
|
62
|
+
If you don't see Analytics at all, your account likely doesn't have advanced
|
|
63
|
+
analytics enabled. See [Access and entitlements](./access-and-entitlements.md).
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Metrics Glossary"
|
|
3
|
+
sidebar_label: "Metrics Glossary"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
This page defines every term used in the Analytics dashboards once. KPI tables
|
|
7
|
+
on tab pages link here for depth.
|
|
8
|
+
|
|
9
|
+
## HTTP status classes
|
|
10
|
+
|
|
11
|
+
| Class | Meaning |
|
|
12
|
+
| ----- | ----------------------------------------------------------------------------------------------- |
|
|
13
|
+
| 2xx | Success. |
|
|
14
|
+
| 3xx | Redirection. |
|
|
15
|
+
| 4xx | Client error. The caller sent something the gateway or backend rejected. |
|
|
16
|
+
| 5xx | Server error. The gateway, an upstream origin, or an MCP backend failed to fulfill the request. |
|
|
17
|
+
|
|
18
|
+
## Error rates
|
|
19
|
+
|
|
20
|
+
**Client error rate.** 4xx count divided by total requests in the window,
|
|
21
|
+
expressed as a percentage.
|
|
22
|
+
|
|
23
|
+
**Server error rate.** 5xx count divided by total requests in the window.
|
|
24
|
+
|
|
25
|
+
**Request-weighted average.** When aggregating a rate across many entities
|
|
26
|
+
(consumers, agents, origins), each entity's rate is weighted by its request
|
|
27
|
+
count. A consumer with 100,000 requests at a 1% error rate contributes more than
|
|
28
|
+
a consumer with 100 requests at a 50% error rate. Use the request-weighted
|
|
29
|
+
figure to answer "what does the average request experience look like?"; use a
|
|
30
|
+
simple unweighted average to answer "what does the average consumer experience
|
|
31
|
+
look like?"
|
|
32
|
+
|
|
33
|
+
## Latency
|
|
34
|
+
|
|
35
|
+
**Avg latency.** Arithmetic mean response time. Sensitive to outliers.
|
|
36
|
+
|
|
37
|
+
**P50 (median) latency.** Half of requests completed within this time.
|
|
38
|
+
|
|
39
|
+
**P95 latency.** 95% of requests completed within this time. The other 5% took
|
|
40
|
+
longer. P95 is the standard tail-latency metric.
|
|
41
|
+
|
|
42
|
+
**P99 latency.** 99% of requests completed within this time. Useful for spotting
|
|
43
|
+
outlier behavior that P95 may smooth over.
|
|
44
|
+
|
|
45
|
+
**Latency distribution histogram.** Bands at P10, P50, P90, P95, P99. Clicking a
|
|
46
|
+
band on the Requests tab filters to requests in that duration range.
|
|
47
|
+
|
|
48
|
+
## Active edge instances
|
|
49
|
+
|
|
50
|
+
Distinct gateway worker instances actively serving traffic in each interval. A
|
|
51
|
+
rough indicator of how widely your traffic is distributed.
|
|
52
|
+
|
|
53
|
+
## Failure origin
|
|
54
|
+
|
|
55
|
+
Classifies an error by where it originated:
|
|
56
|
+
|
|
57
|
+
| Origin | Meaning |
|
|
58
|
+
| -------- | ---------------------------------------------------------- |
|
|
59
|
+
| gateway | The Zuplo gateway returned the error. |
|
|
60
|
+
| upstream | A backend origin or MCP server returned the error. |
|
|
61
|
+
| client | The client sent something invalid that caused the failure. |
|
|
62
|
+
|
|
63
|
+
## Outcome class
|
|
64
|
+
|
|
65
|
+
MCP events use these outcome classes:
|
|
66
|
+
|
|
67
|
+
| Class | Meaning |
|
|
68
|
+
| ----------------- | -------------------------------------------------------------------- |
|
|
69
|
+
| success | Event completed normally. |
|
|
70
|
+
| application_error | Event failed due to an application-layer issue (e.g. invalid input). |
|
|
71
|
+
| gateway_error | The gateway itself returned an error. |
|
|
72
|
+
| upstream_error | An upstream MCP server returned an error. |
|
|
73
|
+
|
|
74
|
+
## GraphQL operation types
|
|
75
|
+
|
|
76
|
+
| Type | Meaning |
|
|
77
|
+
| ------------ | -------------------------------------------- |
|
|
78
|
+
| Query | A read operation. |
|
|
79
|
+
| Mutation | A write operation. |
|
|
80
|
+
| Subscription | A long-lived operation that streams updates. |
|
|
81
|
+
|
|
82
|
+
## GraphQL error classes
|
|
83
|
+
|
|
84
|
+
The GraphQL tab groups errors by where they arise:
|
|
85
|
+
|
|
86
|
+
| Class | Meaning |
|
|
87
|
+
| ---------- | ---------------------------------------------------------------- |
|
|
88
|
+
| Resolver | A resolver threw while executing the operation. |
|
|
89
|
+
| Validation | The operation failed schema validation before execution. |
|
|
90
|
+
| Auth | An authentication or authorization check rejected the operation. |
|
|
91
|
+
|
|
92
|
+
## Resolver latency (GraphQL)
|
|
93
|
+
|
|
94
|
+
How long the operation spends executing resolvers, as opposed to **total
|
|
95
|
+
latency**, which also covers parsing, validation, and gateway policy time. A
|
|
96
|
+
total P95 well above the resolver P95 means the operation spends its time
|
|
97
|
+
outside your resolvers.
|
|
98
|
+
|
|
99
|
+
## Query complexity (GraphQL)
|
|
100
|
+
|
|
101
|
+
A score for how expensive a GraphQL operation is to execute. The score grows
|
|
102
|
+
with the fields and nesting the operation requests. The Operations table reports
|
|
103
|
+
the average and maximum complexity per operation. See
|
|
104
|
+
[Secure your GraphQL API](../../articles/graphql-security.mdx) for complexity
|
|
105
|
+
limits.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "URL Parameters"
|
|
3
|
+
sidebar_label: "URL Parameters"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Every Analytics control persists to the URL. Copy the address bar to share any
|
|
7
|
+
view.
|
|
8
|
+
|
|
9
|
+
## When to use this
|
|
10
|
+
|
|
11
|
+
- Build a permalink to a specific time window, filter set, or demo view.
|
|
12
|
+
- Embed an Analytics link in a runbook, postmortem, or dashboard.
|
|
13
|
+
- Understand what each query parameter does.
|
|
14
|
+
|
|
15
|
+
## Parameters
|
|
16
|
+
|
|
17
|
+
| Parameter | Example | Effect |
|
|
18
|
+
| -------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
|
|
19
|
+
| `time` | `?time=7d` | Apply a preset. Values: `1h`, `6h`, `24h`, `3d`, `7d`, `14d`, `28d`, `60d`, `90d`. |
|
|
20
|
+
| `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. |
|
|
21
|
+
| `filter` | `?filter=httpStatus:class:5xx` | Add a filter as `<field>:<matchmode>:<value>`. Repeat the parameter for multiple filters. |
|
|
22
|
+
| `demo` | `?demo=true` | Demo mode (sample data instead of your real analytics). |
|
|
23
|
+
| `preview` | `?preview=1` | Legacy preview mode. |
|
|
24
|
+
|
|
25
|
+
## Match modes for `filter`
|
|
26
|
+
|
|
27
|
+
| Mode | Meaning | Example |
|
|
28
|
+
| ---------- | --------------------- | ---------------------------------- |
|
|
29
|
+
| equals | Exact match. | `filter=httpMethod:equals:POST` |
|
|
30
|
+
| contains | Substring match. | `filter=route:contains:/v1/users` |
|
|
31
|
+
| in | Comma-separated list. | `filter=httpStatus:in:500,502,503` |
|
|
32
|
+
| not | Negation of equals. | `filter=country:not:US` |
|
|
33
|
+
| class | HTTP status class. | `filter=httpStatus:class:5xx` |
|
|
34
|
+
| startsWith | String prefix. | `filter=route:startsWith:/v1/` |
|
|
35
|
+
| endsWith | String suffix. | `filter=route:endsWith:.json` |
|
|
36
|
+
|
|
37
|
+
## Permalink examples
|
|
38
|
+
|
|
39
|
+
Last 7 days of 5xx errors on a specific route:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
?time=7d&filter=httpStatus:class:5xx&filter=route:startsWith:/v1/users
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Custom range with two filters:
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
?start=2026-05-01T00:00:00Z&end=2026-05-08T00:00:00Z&filter=country:equals:US&filter=httpMethod:equals:POST
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Open the demo:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
?demo=true
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Sharing
|
|
58
|
+
|
|
59
|
+
The recipient sees the same view, provided they have access to the project or
|
|
60
|
+
account.
|
|
61
|
+
|
|
62
|
+
## See also
|
|
63
|
+
|
|
64
|
+
- [Shared controls](../shared-controls.md): what each control does in the UI.
|
|
65
|
+
- [Metrics glossary](./metrics-glossary.md): definitions for the fields you can
|
|
66
|
+
filter on.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Shared Controls"
|
|
3
|
+
sidebar_label: "Shared Controls"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Every Analytics tab uses the same set of controls at the top of the page: a time
|
|
7
|
+
range picker, a filter bar, and (at project scope) an environment selector.
|
|
8
|
+
State persists to the URL so you can share or bookmark any view.
|
|
9
|
+
|
|
10
|
+
## When to use this
|
|
11
|
+
|
|
12
|
+
- Narrow a tab to a time window, environment, or set of filter values.
|
|
13
|
+
- Build a shareable link to a specific view.
|
|
14
|
+
- Understand what each banner across the top of the page means.
|
|
15
|
+
|
|
16
|
+
## Time range
|
|
17
|
+
|
|
18
|
+
The time range picker controls every chart, table, and KPI on the active tab.
|
|
19
|
+
|
|
20
|
+
**Presets.** Last 1h, 6h, 24h, 3d, 7d, 14d, 28d, 60d, 90d.
|
|
21
|
+
|
|
22
|
+
**Custom range.** Use the datetime-local inputs for **Start** and **End**. Both
|
|
23
|
+
fields are clamped to your account's retention window.
|
|
24
|
+
|
|
25
|
+
**Locked presets.** Presets longer than your retention window show an **Upgrade
|
|
26
|
+
for [preset]** tooltip. See
|
|
27
|
+
[Access and entitlements](./access-and-entitlements.md).
|
|
28
|
+
|
|
29
|
+
## Filters
|
|
30
|
+
|
|
31
|
+
Filters render as removable pills in a sticky bar at the top of the tab. Add a
|
|
32
|
+
filter from any breakdown table by clicking a value, or build one manually.
|
|
33
|
+
|
|
34
|
+
**Match modes.** Each filter uses one of:
|
|
35
|
+
|
|
36
|
+
| Mode | Meaning |
|
|
37
|
+
| ---------- | ----------------------------------- |
|
|
38
|
+
| equals | Exact match. |
|
|
39
|
+
| contains | Substring match. |
|
|
40
|
+
| in | Value is in a comma-separated list. |
|
|
41
|
+
| not | Negation of equals. |
|
|
42
|
+
| class | HTTP status class (e.g. `5xx`). |
|
|
43
|
+
| startsWith | String prefix. |
|
|
44
|
+
| endsWith | String suffix. |
|
|
45
|
+
|
|
46
|
+
**Clearing.** Remove a single pill with its **×**, or click **Clear all
|
|
47
|
+
filters** to reset.
|
|
48
|
+
|
|
49
|
+
**Disabled fields.** Some fields are grayed out on tabs where they don't apply.
|
|
50
|
+
For example, `originHost` is unavailable on Requests, Consumers, and Agents;
|
|
51
|
+
`userSub` is unavailable on Origins.
|
|
52
|
+
|
|
53
|
+
## Environment selector
|
|
54
|
+
|
|
55
|
+
The environment selector appears only at project scope. It's a dropdown grouped
|
|
56
|
+
as:
|
|
57
|
+
|
|
58
|
+
- **Working Copy**
|
|
59
|
+
- **Production**
|
|
60
|
+
- **Preview**
|
|
61
|
+
- **Other**
|
|
62
|
+
|
|
63
|
+
Each environment shows a request count next to its name. The active selection
|
|
64
|
+
appears as a blue pill in the top bar.
|
|
65
|
+
|
|
66
|
+
## Account vs project scope
|
|
67
|
+
|
|
68
|
+
See
|
|
69
|
+
[Access and entitlements](./access-and-entitlements.md#scope-account-vs-project)
|
|
70
|
+
for how scope affects available breakdowns and the environment selector.
|
|
71
|
+
|
|
72
|
+
## URL state and permalinks
|
|
73
|
+
|
|
74
|
+
Every control persists to the URL. To share a view, copy the address bar.
|
|
75
|
+
There's no separate share button.
|
|
76
|
+
|
|
77
|
+
| Parameter | Example | Effect |
|
|
78
|
+
| -------------- | ------------------------------------------------------ | ------------------------------------------------------- |
|
|
79
|
+
| `time` | `?time=7d` | Apply a preset. |
|
|
80
|
+
| `start`, `end` | `?start=2026-05-01T00:00:00Z&end=2026-05-15T00:00:00Z` | Custom range. Overrides `time`. |
|
|
81
|
+
| `filter` | `?filter=httpStatus:class:5xx` | Add a filter. Repeat the parameter for multiple values. |
|
|
82
|
+
| `demo` | `?demo=true` | Demo mode (sample data). |
|
|
83
|
+
| `preview` | `?preview=1` | Legacy preview mode. |
|
|
84
|
+
|
|
85
|
+
See [URL parameters](./reference/url-parameters.md) for the full reference.
|
|
86
|
+
|
|
87
|
+
## Refresh
|
|
88
|
+
|
|
89
|
+
A spinning loader appears in the sticky bar while data refetches, and a
|
|
90
|
+
semi-transparent **Updating…** overlay covers the content area. There's no
|
|
91
|
+
manual refresh button and no auto-refresh interval. Change a control to trigger
|
|
92
|
+
a refetch.
|
|
93
|
+
|
|
94
|
+
## Banners
|
|
95
|
+
|
|
96
|
+
Banners appear at the top of the page in this priority order:
|
|
97
|
+
|
|
98
|
+
1. **Preview banner**: when `preview=1` is set. Indicates legacy preview mode.
|
|
99
|
+
2. **Demo banner**: when `demo=true` is set. Reminds you sample data is shown
|
|
100
|
+
instead of your real analytics.
|
|
101
|
+
3. **Trial banner**: for new accounts with advanced analytics. Shows days
|
|
102
|
+
remaining and offers **View demo →** and **Contact Sales**.
|
|
103
|
+
|
|
104
|
+
## Loading and empty states
|
|
105
|
+
|
|
106
|
+
Each tab uses a shape-aware skeleton while the first request is in flight. The
|
|
107
|
+
product analytics tabs (MCP, GraphQL) suppress that skeleton briefly to avoid
|
|
108
|
+
flashing when data is already cached. Empty states on those tabs include a short
|
|
109
|
+
description and a "Read the … docs" link to the relevant product section.
|
|
110
|
+
|
|
111
|
+
## Status colors
|
|
112
|
+
|
|
113
|
+
The same color palette is used across every chart that breaks down by HTTP
|
|
114
|
+
status class:
|
|
115
|
+
|
|
116
|
+
| Class | Color |
|
|
117
|
+
| ----- | ----- |
|
|
118
|
+
| 2xx | Green |
|
|
119
|
+
| 3xx | Blue |
|
|
120
|
+
| 4xx | Amber |
|
|
121
|
+
| 5xx | Red |
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Agents"
|
|
3
|
+
sidebar_label: "Agents"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The **Agents** tab isolates AI agent traffic: requests classified as coming from
|
|
7
|
+
ChatGPT, Claude.ai, Cursor, GPTBot, and similar clients. It's a focused view;
|
|
8
|
+
browsers, webhooks, and generic SDK callers are excluded.
|
|
9
|
+
|
|
10
|
+
## When to use this
|
|
11
|
+
|
|
12
|
+
- See which AI agents are calling your API and how much volume they generate.
|
|
13
|
+
- Catch agent-specific error patterns. For example, one agent that fails CORS or
|
|
14
|
+
returns 4xx more often than the others.
|
|
15
|
+
- Compare latency experience across agents.
|
|
16
|
+
|
|
17
|
+
## Summary KPIs
|
|
18
|
+
|
|
19
|
+
| Name | What it measures |
|
|
20
|
+
| ----------------- | ---------------------------------------------------------------------------- |
|
|
21
|
+
| **Requests** | Total agent-classified requests. Excludes browsers, webhooks, generic SDKs. |
|
|
22
|
+
| **Client Errors** | Request-weighted 4xx rate across agents. |
|
|
23
|
+
| **Server Errors** | Request-weighted 5xx rate. Secondary: count of agents with at least one 5xx. |
|
|
24
|
+
| **Agents** | Distinct classified agents seen in the window. |
|
|
25
|
+
| **Total Errors** | Combined 4xx + 5xx count. Secondary: agents affected. |
|
|
26
|
+
|
|
27
|
+
## Charts
|
|
28
|
+
|
|
29
|
+
**Request Volume.** Stacked bars by status class. Granularity is always hourly
|
|
30
|
+
on this tab.
|
|
31
|
+
|
|
32
|
+
**Agent Error Rates.** 4xx and 5xx over time. _What to look for:_ divergence
|
|
33
|
+
between agents is the headline signal. If Cursor shows a 12% 4xx rate while
|
|
34
|
+
ChatGPT sits at 2%, the issue is almost certainly specific to how Cursor calls
|
|
35
|
+
your endpoint.
|
|
36
|
+
|
|
37
|
+
**Agent Latency Over Time.** P50, P95, P99 lines.
|
|
38
|
+
|
|
39
|
+
## Agent table
|
|
40
|
+
|
|
41
|
+
| Column | Notes |
|
|
42
|
+
| --------------- | -------------------------------- |
|
|
43
|
+
| Agent | Classified agent name. |
|
|
44
|
+
| Requests | Count with an inline volume bar. |
|
|
45
|
+
| Client Errors % | 4xx percentage. |
|
|
46
|
+
| Server Errors % | 5xx percentage. |
|
|
47
|
+
| Avg / P95 / P99 | Latency percentiles. |
|
|
48
|
+
| 4xx sparkline | Inline trend over the window. |
|
|
49
|
+
| 5xx sparkline | Inline trend over the window. |
|
|
50
|
+
|
|
51
|
+
Searchable and sortable on any column. Click a row to filter the tab to that
|
|
52
|
+
agent. **Show more** loads the next 50.
|
|
53
|
+
|
|
54
|
+
## Classified agents
|
|
55
|
+
|
|
56
|
+
The classifier currently recognizes: ChatGPT, Claude.ai, Cursor, Claude Code,
|
|
57
|
+
GPTBot, Perplexity, Cline, Continue, OpenAI SDK, Anthropic SDK, Google AI,
|
|
58
|
+
Common Crawl. The list expands over time.
|
|
59
|
+
|
|
60
|
+
Unclassified traffic is excluded from the Agents tab.
|
|
61
|
+
|
|
62
|
+
:::warning
|
|
63
|
+
|
|
64
|
+
Agent charts use a dedicated hourly rollup. Filtering other tabs by agent isn't
|
|
65
|
+
supported. Use the Agents tab to drill into an individual agent.
|
|
66
|
+
|
|
67
|
+
:::
|
|
68
|
+
|
|
69
|
+
## Filters
|
|
70
|
+
|
|
71
|
+
The filter bar applies. `originHost` is not applicable here. See
|
|
72
|
+
[Shared controls](../shared-controls.md#filters).
|
|
73
|
+
|
|
74
|
+
## Troubleshooting
|
|
75
|
+
|
|
76
|
+
**The Agents tab is empty.** Either no classified agents called your gateway in
|
|
77
|
+
the window, or your retention window doesn't yet include any agent traffic. Try
|
|
78
|
+
the demo with **View demo →** in the trial banner to see what a populated tab
|
|
79
|
+
looks like. See [Access and entitlements](../access-and-entitlements.md).
|
|
80
|
+
|
|
81
|
+
**I see a known agent in my logs but not here.** The classifier is conservative;
|
|
82
|
+
it labels traffic that clearly matches a known agent fingerprint. Generic SDK
|
|
83
|
+
traffic that doesn't identify itself is excluded. If you believe an agent should
|
|
84
|
+
be classified, send the User-Agent string to your Zuplo contact.
|
|
85
|
+
|
|
86
|
+
**An agent shows zero requests but appears in the table.** Filters on the rest
|
|
87
|
+
of the tab may be excluding its traffic for the current window. Clear filters to
|
|
88
|
+
verify.
|