zuplo 6.70.70 → 6.70.71

package/docs/analytics/tabs/graphql.md

@@ -0,0 +1,77 @@
+---
+title: "GraphQL"
+sidebar_label: "GraphQL"
+---
+
+The **GraphQL** tab breaks traffic down by GraphQL operation: the queries,
+mutations, and subscriptions clients send through routes you've marked as
+GraphQL endpoints. Use it to find your most-used operations, separate validation
+and resolver errors, and see how much of each operation's latency falls in your
+upstream resolvers. It's visible when the project proxies a GraphQL API.
+
+## When to use this
+
+- Find the highest-volume operations and the ones clients call most.
+- Separate resolver, validation, and auth errors when a GraphQL endpoint
+  misbehaves.
+- Compare total round-trip latency against resolver-only time to see whether the
+  gateway or the upstream owns a slowdown.
+
+## Summary KPIs
+
+| Name              | What it measures                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------- |
+| **Operations**    | Total GraphQL operations in the window.                                                       |
+| **Success Rate**  | Share of operations that completed without error. Secondary: ok / err split.                  |
+| **p95 Latency**   | Total P95 across operations. Secondary: resolver P95.                                         |
+| **Error Classes** | Total errored operations. Secondary: resolver / validation / auth split (`res · val · auth`). |
+
+See [Metrics glossary](../reference/metrics-glossary.md) for error-class and
+resolver-latency definitions.
+
+## Charts
+
+**GraphQL Operations Over Time.** Operation volume per interval. Populates once
+a client sends a query, mutation, or subscription.
+
+**Operation Types.** A donut splitting operations across **query**,
+**mutation**, and **subscription**.
+
+**Latency — Total vs Resolver.** Total P95 and resolver P95 over time, with P50
+total, P95 total, P99 total, and P95 resolver summary cards. _What to look for:_
+a total P95 well above the resolver P95 means the operation spends its time
+outside your resolvers — in parsing, validation, or gateway policies — rather
+than in the upstream.
+
+## Operations table
+
+| Column               | Notes                                          |
+| -------------------- | ---------------------------------------------- |
+| Operation            | The GraphQL operation name.                    |
+| Type                 | query, mutation, or subscription.              |
+| Operations           | Count with an inline volume bar.               |
+| Errors               | Errored-operation count.                       |
+| Error Rate           | Errors ÷ operations.                           |
+| Complexity (avg/max) | Average and maximum computed query complexity. |
+| p95                  | P95 latency for the operation.                 |
+
+The table is searchable and sortable on any column (default: operations
+descending).
+
+## Filters
+
+The filter bar applies. See [Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The GraphQL tab is empty.** No GraphQL operations arrived in the selected
+window. Operations appear once a client sends a query, mutation, or subscription
+through a route you've marked as a GraphQL endpoint. See
+[GraphQL on Zuplo](../../articles/graphql.mdx) for how to mark a route.
+
+**The tab isn't visible.** Visibility requires at least one route you've marked
+as a GraphQL endpoint. See [GraphQL on Zuplo](../../articles/graphql.mdx).
+
+**Total latency is high but resolver latency is low.** The operation spends its
+time outside your resolvers. Check the gateway policies on the GraphQL route —
+parsing, validation, complexity analysis, or auth — rather than the upstream.

package/docs/analytics/tabs/mcp.md

@@ -0,0 +1,80 @@
+---
+title: "MCP"
+sidebar_label: "MCP"
+---
+
+The **MCP** tab shows Model Context Protocol traffic through Zuplo: OAuth and
+auth decisions, virtual-server routing, capability and tool invocations,
+JSON-RPC method usage, and upstream MCP server health. It covers both traffic
+that flows _to_ an MCP fleet through Zuplo's gateway and activity _inside_ MCP
+servers you host on Zuplo. It's visible when the project type is **standard**
+and MCP is in use.
+
+## When to use this
+
+- See which virtual servers, capabilities, and tools clients call most, and
+  who's calling them.
+- Track auth and policy decision outcomes across OAuth flows.
+- Identify whether failures originate in the gateway, the upstream, or the
+  client.
+- Investigate the JSON-RPC error codes clients receive.
+
+## Summary KPIs
+
+| Name                    | What it measures                                                                             |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| **Events**              | Total MCP events in the window.                                                              |
+| **Success Rate**        | Share of events with outcome = success. Secondary: success / error split.                    |
+| **Client Errors (4xx)** | Count of client-side errors. Secondary: share of all errors.                                 |
+| **Server Errors (5xx)** | Count of server-side errors. Secondary: share of all errors.                                 |
+| **Failure Origins**     | Combined gateway + upstream + client failures. Secondary: per-origin split (`gw · up · cl`). |
+
+See [Metrics glossary](../reference/metrics-glossary.md) for the failure-origin
+and outcome-class definitions.
+
+## Charts
+
+**MCP Events Over Time.** Stacked area showing the top event types over the
+window.
+
+**Event Families.** A donut distributing events across families: **Requests**,
+**Capabilities**, and **Auth**.
+
+**Latency — Gateway vs Upstream.** Total, gateway, and upstream P95 over time,
+with P50 total, P95 total, P95 gateway, and P95 upstream summary cards. _What to
+look for:_ a P95 that the upstream slice dominates points to a slow MCP backend;
+a gateway-heavy P95 points to policy or auth overhead.
+
+## Breakdown tables
+
+| Table                | Columns                                                                                                                |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Capabilities         | Server, Capability, Type, Calls, Client (4xx), Server (5xx), Error Rate, P95.                                          |
+| Consumers            | Consumer, Events, Client (4xx), Server (5xx).                                                                          |
+| Virtual Servers      | Virtual Server, Events, Client (4xx), Server (5xx).                                                                    |
+| Upstream Servers     | Upstream, Events, Client (4xx), Server (5xx), P95.                                                                     |
+| MCP Methods          | Method (for example `tools/call`, `tools/list`, `resources/list`, `prompts/list`, `resources/templates/list`), Events. |
+| Clients              | Client, Kind (from the `initialize` handshake), Events.                                                                |
+| JSON-RPC Error Codes | Code, Errors — the JSON-RPC error codes clients receive.                                                               |
+| Failure Origins      | Origin (gateway / upstream / client), Errors, Client (4xx), Server (5xx).                                              |
+| Reason Codes         | Class, Code, Events, Errors, Client (4xx), Server (5xx).                                                               |
+
+Most tables sort on any column and show the top values by volume. Click **Show
+more** to load the next page.
+
+## Filters
+
+The filter bar applies. See [Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The MCP tab is empty.** No MCP events arrived in the selected window. Once a
+client connects and invokes a capability or tool, the dashboard populates.
+
+**The tab isn't visible.** Visibility requires project type **standard** with
+MCP in use — either an MCP gateway that routes to upstream servers, or an MCP
+server you host on Zuplo.
+
+**Errors show but Failure Origins is empty.** Zuplo classifies failure origins
+server-side from event metadata. Events without a clear origin classification
+land in Errors but in none of the gateway / upstream / client buckets.

package/docs/analytics/tabs/origins.md

@@ -0,0 +1,82 @@
+---
+title: "Origins"
+sidebar_label: "Origins"
+---
+
+The **Origins** tab shows backend performance: how each upstream host you proxy
+to is performing in terms of volume, error rate, and latency. It's visible when
+the project uses managed-edge origins.
+
+## When to use this
+
+- Identify which backend is slow or returning errors.
+- Compare the latency contribution of DNS, TCP, TLS, and application time.
+- Audit traffic distribution across direct origins and service tunnels.
+
+## Summary metrics
+
+The header strip shows totals derived from the time series:
+
+| Name                 | What it measures                                                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Total requests       | All requests served against any origin in the window.                                                                                       |
+| 4xx rate             | Client error rate across all origins.                                                                                                       |
+| 5xx rate             | Server error rate across all origins.                                                                                                       |
+| Weighted avg latency | Origin response time weighted by request count, so high-traffic origins dominate. See [Metrics glossary](../reference/metrics-glossary.md). |
+
+## Charts
+
+**Backend Request Time Series.** Stacked bars by status class, aggregated across
+origins by default. Apply a host filter to scope to one origin.
+
+**Backend Latency.** Average and P95 over time. _What to look for:_ a P95 climb
+while the average stays flat usually points to a few slow origins or routes
+inside an otherwise healthy fleet.
+
+**Backend Error Rate.** 4xx and 5xx rates over time.
+
+**Request Lifecycle.** Stacked time spent in each phase of an origin request:
+**DNS time**, **TCP time**, **TLS time**, and **application time**. A high TLS
+slice indicates handshake overhead; a high application slice indicates the
+origin is slow.
+
+## Tables
+
+Two tables sit side by side in a 2-column grid.
+
+### Direct Origins
+
+| Column          | Notes                            |
+| --------------- | -------------------------------- |
+| Host            | The origin hostname.             |
+| Requests        | Count with an inline volume bar. |
+| Client Errors   | 4xx percentage.                  |
+| Server Errors   | 5xx percentage.                  |
+| Avg / P95 / P99 | Latency percentiles.             |
+| 4xx sparkline   | Inline trend over the window.    |
+| 5xx sparkline   | Inline trend over the window.    |
+
+Clicking a row toggles a host filter. Click again to remove it.
+
+### Service Tunnels
+
+Same columns and behavior as Direct Origins, scoped to tunnel-routed origins.
+The table is hidden when no tunnel traffic is present.
+
+## Filters
+
+The filter bar applies, with one exception: `userSub` is not applicable on this
+tab. See [Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The Origins tab isn't visible.** It appears only when the project uses
+managed-edge origins. If your project routes traffic differently, the tab is
+hidden.
+
+**Service Tunnels table is missing.** That table only renders when at least one
+origin is reached over a service tunnel.
+
+**A 5xx spike on one origin doesn't match the Requests tab.** If you've filtered
+the Requests tab to a different route or status class, totals won't match. Clear
+filters or compare with the same filters applied on both tabs.

package/docs/analytics/tabs/requests.md

@@ -0,0 +1,96 @@
+---
+title: "Requests"
+sidebar_label: "Requests"
+---
+
+The **Requests** tab is the default Analytics overview: every request through
+your gateway in the selected time window, with charts and breakdowns for volume,
+latency, and errors.
+
+## When to use this
+
+- Spot-check overall traffic and error rate across a project or the whole
+  account.
+- Investigate a spike in 4xx or 5xx responses.
+- Drill from a route, status code, or geographic breakdown into the underlying
+  requests.
+
+## Summary KPIs
+
+| Name              | What it measures                                              | When it's useful                          |
+| ----------------- | ------------------------------------------------------------- | ----------------------------------------- |
+| **Requests**      | Total request count. Secondary value: successful (2xx) count. | Quick health check on volume and success. |
+| **Client Errors** | 4xx rate (4xx ÷ total). Secondary value: raw 4xx count.       | Spot bad-input or auth issues.            |
+| **Server Errors** | 5xx rate (5xx ÷ total). Secondary value: raw 5xx count.       | Spot gateway or upstream failures.        |
+| **Avg Latency**   | Mean response time. Secondary value: min to max.              | Detect broad latency regressions.         |
+| **Consumers**     | Distinct API consumers (authenticated + anonymous).           | Gauge active audience.                    |
+
+See [Metrics glossary](../reference/metrics-glossary.md) for how rates and
+percentiles are computed.
+
+## Charts
+
+**Request Time Series.** Stacked bars per interval, broken down by status class
+(2xx / 3xx / 4xx / 5xx). Drag to select a region to zoom; the time range picker
+updates to match.
+
+**Request Locations Map.** A world map with a heatmap of request volume by
+location. Shown only when geolocation data is present.
+
+**Latency Over Time.** P50, P95, and P99 lines. _What to look for:_ a widening
+gap between P50 and P95 typically signals a tail-latency problem affecting a
+subset of requests.
+
+**Error Rate.** 4xx and 5xx rates plotted over time.
+
+**Latency Distribution.** A histogram of P10, P50, P90, P95, and P99 buckets.
+Click a band to filter the rest of the tab to requests in that duration range.
+
+**Active Instances.** Distinct active edge instances over time. A rough
+indicator of how widely your traffic is distributed across gateway workers.
+
+## Breakdowns
+
+Each breakdown shows the top 10 values by request count. Click **Show more** to
+load the next 50.
+
+**Primary breakdowns:**
+
+- **HTTP Method**
+- **HTTP Status**
+- **Route Path**
+
+**Account scope only:**
+
+- **Project Name**: click to drill into project-scope analytics.
+- **Deployment Name**: click to drill into a specific deployment.
+
+**Secondary breakdowns:**
+
+- **Country**, **City**, **Colo**
+- **User Sub**
+- **Client IP**
+- **AS Organization**
+
+Clicking any value applies an `equals` filter for that field.
+
+## Filters
+
+The full filter bar applies. `originHost` is not applicable on this tab. See
+[Shared controls](../shared-controls.md#filters) for match modes and the filter
+pill UI.
+
+## Troubleshooting
+
+**The map is missing.** The Request Locations Map only renders when geolocation
+data is present in the time window. Short windows for low-traffic projects may
+not include any geolocated requests.
+
+**Show more doesn't load anything.** You may already be viewing every value for
+that breakdown. Top-10 plus 50 covers up to 60 distinct values; beyond that,
+narrow the time range or add a filter.
+
+**My charts look sparse.** If your account is new, the trial banner across the
+top calls this out. Click **View demo →** in the banner to see what a fully
+populated dashboard looks like. See
+[Access and entitlements](../access-and-entitlements.md).

package/docs/articles/ci-cd-github/basic-deployment.mdx

@@ -27,7 +27,9 @@ jobs:
         run: npm install
 
       - name: Deploy to Zuplo
-        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "${{
+          github.ref_name }}"
         env:
           ZUPLO_API_KEY: ${{ secrets.ZUPLO_API_KEY }}
 ```
@@ -41,6 +43,13 @@ This workflow:
 
 Since this deploys from `main`, it updates your production environment.
 
+Passing `--environment` is technically optional here — without it, the CLI
+infers the environment name from the checked-out git ref — but inference can
+pick the wrong name in CI (detached HEAD checkouts, commits that exist on more
+than one branch, or `pull_request` merge refs). Passing the branch name
+explicitly makes every workflow deploy a predictable environment. See the
+[deploy command reference](../../cli/deploy.mdx) for details.
+
 ## Next Steps
 
 - Add [testing after deployment](./deploy-and-test.mdx)

package/docs/articles/ci-cd-github/deploy-and-test.mdx

@@ -34,9 +34,14 @@ jobs:
       - name: Deploy to Zuplo
         id: deploy
         shell: bash
+        env:
+          # head_ref is the source branch on pull_request events (where the
+          # checkout is the pull/<number>/merge ref, not the branch);
+          # ref_name covers push events
+          ENVIRONMENT: ${{ github.head_ref || github.ref_name }}
         run: |
           # Capture deployment output
-          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$ENVIRONMENT" 2>&1)
           echo "$OUTPUT"
 
           # Extract the deployment URL
@@ -53,6 +58,14 @@ This workflow:
 2. Runs your test suite against the live deployment
 3. Fails the workflow if any tests fail
 
+The deploy step passes `--environment` explicitly because this workflow runs on
+both `push` and `pull_request` events. The expression
+`${{ github.head_ref || github.ref_name }}` resolves to the branch name on
+either trigger, so every run for a branch updates the same environment. Without
+it, `pull_request` runs create a second environment named after the PR merge ref
+instead of your branch — see
+[PR Preview Environments](./pr-preview-environments.mdx) for details.
+
 ## Writing Tests
 
 Place test files in the `tests` folder with the `.test.ts` extension:

package/docs/articles/ci-cd-github/local-testing.mdx

@@ -64,7 +64,9 @@ jobs:
         run: npm install
 
       - name: Deploy to Zuplo
-        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "${{
+          github.ref_name }}"
 ```
 
 This workflow:

package/docs/articles/ci-cd-github/pr-preview-environments.mdx

@@ -6,6 +6,19 @@ sidebar_label: PR Preview Environments
 Give every pull request its own Zuplo environment. Reviewers can test changes
 against a live API, and environments clean up automatically when PRs close.
 
+:::caution{title="Pass --environment on pull_request events"}
+
+Workflows triggered by `pull_request` check out the pull request **merge ref**
+(`refs/pull/<number>/merge`), not your branch. Without `--environment`, the
+Zuplo CLI derives the environment name from that ref and creates an environment
+named `pull/<number>/merge` instead of one named after your branch. If anything
+else deploys the same branch — a `push`-triggered workflow, the GitHub
+integration, or a local `zuplo deploy` — you end up with two environments and
+two different URLs for the same branch. Always pass `--environment` with the
+source branch name (`github.head_ref`).
+
+:::
+
 ```yaml title=".github/workflows/pr-workflow.yaml"
 name: PR Workflow
 
@@ -13,6 +26,12 @@ on:
   pull_request:
     types: [opened, synchronize, reopened, closed]
 
+# Runs for the same branch share one queue, so rapid pushes don't race
+# concurrent deploys into the same environment
+concurrency:
+  group: zuplo-preview-${{ github.head_ref }}
+  cancel-in-progress: true
+
 jobs:
   deploy-and-test:
     # Run on PR open/update, not on close
@@ -34,8 +53,12 @@ jobs:
       - name: Deploy to Zuplo
         id: deploy
         shell: bash
+        env:
+          # The PR's source branch — not the pull/<number>/merge ref that
+          # pull_request events check out
+          ENVIRONMENT: ${{ github.head_ref }}
         run: |
-          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$ENVIRONMENT" 2>&1)
           echo "$OUTPUT"
           DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
           echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
@@ -103,12 +126,21 @@ This workflow:
 
 ## How It Works
 
-- The environment name comes from the branch name (`feature/auth` becomes
-  `feature-auth`)
-- Each push to the PR updates the same environment
+- The deploy step passes `--environment` with the PR's source branch name
+  (`github.head_ref`), so the environment is named after the branch — the same
+  name the [GitHub integration](../source-control-setup-github.mdx) would use
+- Each push to the PR updates the same environment, so the environment URL stays
+  stable for the life of the branch
 - Closing the PR (merge or abandon) triggers cleanup
 - The PR comment lets reviewers quickly access the preview
 
+A stable environment URL matters whenever an external system references it
+exactly — an OIDC token audience, a webhook registration, or an IP/URL
+allowlist. Capture the URL from the deploy output rather than constructing it
+from the branch name: the URL hostname uses a normalized, truncated form of the
+environment name plus a unique identifier (see
+[Branch-Based Deployments](../branch-based-deployments.mdx)).
+
 ## Next Steps
 
 - Add [automatic cleanup on branch delete](./cleanup-on-branch-delete.mdx) as a

package/docs/articles/custom-ci-cd-github.mdx

@@ -47,8 +47,8 @@ The Zuplo CLI handles deployment, testing, and environment management. Your
 GitHub Actions workflow orchestrates when these happen:
 
 ```bash
-# Deploy to Zuplo (environment name from branch or --environment flag)
-npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+# Deploy to Zuplo (pass --environment with the branch name — see below)
+npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$BRANCH_NAME"
 
 # Run tests against any Zuplo environment
 npx zuplo test --endpoint https://your-env.zuplo.dev
@@ -64,6 +64,15 @@ Capture the deployment URL from the deploy command output to pass to subsequent
 test steps. The CLI outputs `Deployed to https://...` which you can parse and
 use throughout your workflow.
 
+Always pass `--environment` with the branch name when deploying from GitHub
+Actions, so that every workflow run for a branch updates the same environment.
+Without it, the CLI infers the environment name from the checked-out git ref —
+and on `pull_request` events that's the PR merge ref
+(`refs/pull/<number>/merge`), not your branch, which silently creates a second
+environment with a different URL. The expression
+`${{ github.head_ref || github.ref_name }}` resolves to the branch name on both
+`pull_request` and `push` events.
+
 ## Prerequisites
 
 1. **Disconnect the GitHub integration** — Custom CI/CD replaces automatic