Traffic Splitting / A/B Testing

Route a percentage of traffic to different upstream targets for canary deployments, blue-green releases, and A/B testing — with optional sticky sessions to ensure users always hit the same variant.

Use Cases

  • Canary deployment — Send 5% of traffic to a new version while 95% hits stable
  • Blue-green release — Instantly switch 100% of traffic between two environments
  • A/B testing — Split traffic 50/50 between two API variants and compare metrics
  • Gradual rollout — Incrementally increase traffic to a new version over time

Configuration

Configure traffic splitting per-route. Variant weights must sum to exactly 100.

{
  "trafficSplit": {
    "sticky": true,
    "stickyKey": "api_key",
    "testName": "v2-canary",
    "variants": [
      {
        "id": "stable",
        "targetUrl": "https://api.example.com/v1",
        "weight": 90
      },
      {
        "id": "canary",
        "targetUrl": "https://api.example.com/v2",
        "weight": 10,
        "headers": {
          "X-Canary": "true"
        }
      }
    ]
  }
}

Sticky Sessions

When sticky: true, the same user always hits the same variant. This prevents users from seeing inconsistent behavior across requests.

api_key

Sticky by API key — recommended for server-to-server traffic

ip

Sticky by client IP address

header:x-user-id

Sticky by a custom request header value

Sticky assignments are stored in a two-level cache: L1 in-memory LRU (instant) and L2 Redis (24-hour TTL, shared across gateway nodes).

Routing Algorithm

Variant selection uses FNV-1a consistent hashing over the sticky key. This ensures deterministic, uniform distribution without a database lookup on every request. Binary search over pre-computed cumulative weights gives O(1) selection.

Limits

  • Maximum 10 variants per route
  • Weights must be integers summing to 100
  • Sticky session TTL: 24 hours

Plan Requirements

Traffic Splitting is available on Pro plans and above.

GraphQL ProtectionCustom Domains