How do reservoir size and fixed rate work together?

The reservoir is the number of traces per second that are guaranteed to be sampled, regardless of traffic volume. After the reservoir is exhausted, the fixed rate (a percentage between 0 and 1) determines what fraction of additional requests are sampled. For example, a reservoir of 5 with a fixed rate of 0.10 means: the first 5 requests per second are always traced, and 10% of all additional requests are traced. For low-traffic services, the reservoir alone may capture all requests. For high-traffic services, the fixed rate controls the sampling percentage.

How does X-Ray choose which sampling rule to apply?

X-Ray evaluates rules in priority order (lowest number first). Each rule specifies matching criteria: service name, service type, HTTP method, URL path, resource ARN, and host. The first rule whose criteria match the incoming request is applied. If no custom rule matches, the default rule (priority 10000) is used. Assign lower priority numbers to more specific rules (e.g., priority 1 for /api/payments, priority 100 for /api/*, priority 10000 for the default catch-all).

X-Ray Sampling Rule Builder

MonitoringAWS

Build AWS X-Ray sampling rules for controlling trace collection rates.

Last verified: May 2026

X-Ray Configuration

Build X-Ray sampling rule configs to control tracing rates per service, method, and URL path.

Required Fields

SamplingRule.RuleNameSamplingRule.PrioritySamplingRule.FixedRateSamplingRule.ReservoirSizeSamplingRule.ServiceNameSamplingRule.URLPath

{
  "SamplingRule": {
    "RuleName": "high-priority-api",
    "RuleARN": "*",
    "ResourceARN": "*",
    "Priority": 100,
    "FixedRate": 0.1,
    "ReservoirSize": 10,
    "ServiceName": "order-service",
    "ServiceType": "AWS::ECS::Container",
    "Host": "*",
    "HTTPMethod": "POST",
    "URLPath": "/api/orders/*",
    "Version": 1,
    "Attributes": {
      "environment": "production"
    }
  },
  "AdditionalRules": [
    {
      "RuleName": "health-check-suppress",
      "Priority": 50,
      "FixedRate": 0.0,
      "ReservoirSize": 0,
      "ServiceName": "*",
      "ServiceType": "*",
      "Host": "*",
      "HTTPMethod": "GET",
      "URLPath": "/health",
      "ResourceARN": "*",
      "Version": 1
    },
    {
      "RuleName": "default-low-rate",
      "Priority": 10000,
      "FixedRate": 0.01,
      "ReservoirSize": 1,
      "ServiceName": "*",
      "ServiceType": "*",
      "Host": "*",
      "HTTPMethod": "*",
      "URLPath": "*",
      "ResourceARN": "*",
      "Version": 1
    }
  ]
}

Generated Output

Output will appear here...

About This Tool

AWS X-Ray sampling rules control which requests are traced, allowing you to balance observability coverage with cost. Without custom rules, X-Ray applies a default rule that traces the first request each second and 5% of additional requests. Custom sampling rules let you set different rates for different services, URLs, HTTP methods, or other attributes. The X-Ray Sampling Rule Builder helps you define rules with proper priority ordering, reservoir sizes (guaranteed traces per second), and fixed rates (percentage of additional requests to sample).

Real-World Scenario

Your team's X-Ray bill hit $400/month (80M traces from 1.6B requests at 5% default sampling). The builder helps redesign sampling: priority 1 rule traces 100% of /api/payments/* (low volume, high value); priority 100 traces 1% of /api/* (medium volume, batch debugging); priority 1000 traces 0.1% of /healthz (high volume, rarely useful); default 5% rule for everything else. New monthly cost: $30. Visibility into payment issues actually IMPROVES because you have 100% coverage on those paths.

When to Use This Tool

•Creating high-priority sampling rules that trace 100% of requests to critical API endpoints like payment processing
•Defining low-rate sampling for high-volume health check endpoints to reduce X-Ray costs without losing visibility
•Building service-specific rules that increase sampling for new deployments while keeping steady-state sampling low

Pro Tips

TIP

X-Ray costs $5 per million traces recorded. The default 5% sampling rate looks low but adds up fast — 100M requests/month × 5% = 5M traces = $25/month. For high-volume services, custom sampling can drop costs 10x while maintaining the visibility you actually need (sample errors at 100%, success at 1%).

TIP

Always sample 100% of payment/auth/critical paths. The cost is negligible (these endpoints have low volume) and the debug value is enormous when something goes wrong. Use a high-priority rule with `URLPath: /api/payments/*` and a fixed rate of 1.0.

TIP

Reservoir size of 1 with fixed rate 0 is the 'always trace at least N per second' pattern. Useful for low-traffic endpoints where 5% sampling means most days have 0 traces — set reservoir 1 to guarantee at least one trace/second/endpoint for analysis.

How It Works Under the Hood

The builder generates X-Ray sampling rules with: rule name, priority (1-9999), reservoir size (guaranteed traces/sec), fixed rate (0.0-1.0, percentage above reservoir), and matching criteria (service name + service type + HTTP method + URL path + resource ARN + host, all supporting wildcards). Output is generated as aws xray create-sampling-rule commands and Terraform aws_xray_sampling_rule resources.

Frequently Asked Questions

How do reservoir size and fixed rate work together?: The reservoir is the number of traces per second that are guaranteed to be sampled, regardless of traffic volume. After the reservoir is exhausted, the fixed rate (a percentage between 0 and 1) determines what fraction of additional requests are sampled. For example, a reservoir of 5 with a fixed rate of 0.10 means: the first 5 requests per second are always traced, and 10% of all additional requests are traced. For low-traffic services, the reservoir alone may capture all requests. For high-traffic services, the fixed rate controls the sampling percentage.
How does X-Ray choose which sampling rule to apply?: X-Ray evaluates rules in priority order (lowest number first). Each rule specifies matching criteria: service name, service type, HTTP method, URL path, resource ARN, and host. The first rule whose criteria match the incoming request is applied. If no custom rule matches, the default rule (priority 10000) is used. Assign lower priority numbers to more specific rules (e.g., priority 1 for /api/payments, priority 100 for /api/*, priority 10000 for the default catch-all).

Related Learning Guides

CloudWatch & Observability Guide24 min read

Was this tool helpful?

Disclaimer: This tool runs entirely in your browser. No data is sent to our servers. Always verify outputs before using them in production. AWS, Azure, and GCP are trademarks of their respective owners.