X-Ray Tracing (Sampling Rule)

📦 Overview

This Terraform module provisions an AWS X-Ray sampling rule to enable distributed tracing across microservices, APIs, and backend services.

---

✅ Key Features

• Creates configurable X-Ray sampling rules
• Supports filtering by service name, host, HTTP method, and path
• Enables granular trace collection for better debugging and observability
• Automatically tags resources for environment visibility

---

💼 Use Cases

• Visualize distributed request flows across microservices
• Debug latency or performance issues in complex systems
• Collect tracing data in a controlled and cost-efficient manner
• Use with AWS X-Ray SDK or OpenTelemetry instrumentation

---

📥 Input Variables

Name	Type	Description
region	string	AWS region for the deployment
rule_name	string	Name of the X-Ray sampling rule
service_name	string	Name of the service the rule applies to
priority	number	Priority of the rule (lower number = higher priority)
fixed_rate	number	Percentage (0.0–1.0) of requests to trace
http_method	string	HTTP method pattern to match (e.g., "*" or "POST")
host	string	Host pattern to match (e.g., "*" or "example.com")
url_path	string	URL path pattern to match (e.g., "*" or "/api/*")
environment	string	Environment tag for resource visibility (e.g., dev, staging, prod)

---

📤 Outputs

Name	Description
sampling_rule_name	The name of the created X-Ray sampling rule
sampling_rule_arn	The ARN of the sampling rule

---

🚀 Deployment Readiness

• ✅ Compatible with Terraform 1.0+
• ✅ Requires AWS Provider 5.x+
• 🔐 IAM permissions required: xray:PutSamplingRule, xray:CreateSamplingRule
• 🧩 Ensure your workloads are instrumented with X-Ray SDK or OpenTelemetry

---

🛠️ Example Usage

module "xray_tracing_deployment" {
  source         = "git::ssh://git@github.com/archiphire/aws-level-1-modules.git//observability/xray-tracing?ref=v1.0.0"

  region         = "us-east-1"
  rule_name      = "trace-prod-traffic"
  service_name   = "api-service"
  priority       = 100
  fixed_rate     = 0.05
  http_method    = "*"
  host           = "*"
  url_path       = "*"
  environment    = "prod"
}

terraform init
terraform plan
terraform apply

or

tofu init
tofu plan
tofu apply

---

🧹 Cleanup Options

Terraform Destroy:

terraform destroy

or

tofu destroy

Manual Deletion (for Production):

aws xray delete-sampling-rule --rule-name trace-prod-traffic

---

🛡️ Notes

This is a Level 1 observability module.
To take full advantage of tracing, be sure to instrument services using AWS X-Ray SDK or the AWS Distro for OpenTelemetry (ADOT).

You can use multiple sampling rules to tailor tracing across environments, services, or paths.

---

🔒 Deployment Package Notice

This module is part of the Level 1 AWS License Tier.
To access the full deployment package and source code, subscribe to Archiphire.