AWS X-Ray Tracing Implementation Guide

Overview

This document provides a technical guide for implementing AWS X-Ray tracing in http://ASP.NET Core APIs using the XRayTracingMiddleware and ITraceHandler interface. The implementation enables distributed tracing across microservices for monitoring and debugging purposes.

Key Components

1. XRayTracingMiddleware

A custom middleware that automatically captures HTTP requests and creates X-Ray segments for tracing. The middleware is already available in the ETI.Infrastructure.REST package and handles automatic tracing of all HTTP requests.

2. ITraceHandler Interface

Provides methods for manual X-Ray tracing operations, primarily for exception handling within controllers and services:

public interface ITraceHandler
{
    void AddException(Exception exception);
    void BeginSubSegment(string traceName);
    void EndSubSegment();
    string GetTraceHeader();
    ITraceMessageHandler AddTracing(string traceName, string traceHeader = "");
}

Implementation Steps

Step 1: Update Startup.cs - ConfigureServices

Add X-Ray registration in the ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    var awsConfig = Configuration.GetAWSLoggingConfigSection("Serilog");
    var awsEnv = Configuration.GetValue<string>("AWSEnvironment");
    
    // Register AWS X-Ray - this handles all configuration automatically
    services.RegisterAWSXRay(awsEnv ?? "Prod", awsConfig.Config.LogGroup);
    
    // ... other service registrations
}

Step 2: Update Startup.cs - Configure

Add middleware to the HTTP request pipeline in the Configure method:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Add X-Ray tracing middleware early in the pipeline
    app.UseTraceMiddleware("Your_API_Name");
    
    // Add custom X-Ray tracing middleware after routing
    app.UseRouting();
    app.UseMiddleware<XRayTracingMiddleware>();
    
    app.UseAuthentication();
    app.UseAuthorization();
    
    // ... other middleware
}

Important middleware ordering:

UseTraceMiddleware should be called early in the pipeline
XRayTracingMiddleware should be placed after UseRouting() but before UseAuthentication()

Step 3: Controller Implementation

Constructor Injection

Inject the ITraceHandler into your controllers:

public class YourController : ControllerBase
{
    private readonly ITraceHandler _traceHandler;
    
    public YourController(ITraceHandler traceHandler)
    {
        _traceHandler = traceHandler;
    }
}

Exception Handling in Actions

The middleware automatically handles request tracing, but you need to manually add exception tracking in catch blocks:

[HttpGet]
[Route("your-endpoint")]
public IActionResult YourAction()
{
    try
    {
        // Your business logic here
        var result = SomeBusinessOperation();
        
        return Ok(result);
    }
    catch (Exception ex)
    {
        // Add exception to X-Ray trace
        _traceHandler.AddException(ex);
        return StatusCode(500, new { error = ex.Message });
    }
}

Health Check Implementation

For monitoring X-Ray functionality, implement a health check endpoint:

[ApiController]
[Route("health")]
public class HealthController : ControllerBase
{
    private readonly ITraceHandler _traceHandler;

    public HealthController(ITraceHandler traceHandler)
    {
        _traceHandler = traceHandler;
    }

    [HttpGet]
    [Route("xray-test")]
    public IActionResult TestXRay()
    {
        try
        {
            // Simple processing delay
            System.Threading.Thread.Sleep(100);

            return Ok(new
            {
                status = "X-Ray tracing is working",
                timestamp = DateTime.UtcNow,
                service = "Your_API_Name"
            });
        }
        catch (Exception ex)
        {
            _traceHandler.AddException(ex);
            return StatusCode(500, new { error = ex.Message });
        }
    }
}

Best Practices

1. Automatic Request Tracing

The XRayTracingMiddleware automatically handles:

Creating segments for each HTTP request
Capturing request/response data
Adding timing information
No manual intervention required for basic request tracing

2. Exception Handling

Always call AddException when catching exceptions to ensure they appear in X-Ray traces:

catch (Exception ex)
{
    _traceHandler.AddException(ex);
    // Handle exception appropriately
}

3. Performance Considerations

The middleware adds minimal overhead and automatically excludes static resources
Exception tracking is lightweight and non-blocking
No need for manual subsegment creation in typical scenarios

Testing

The implementation can be tested using unit tests that mock the ITraceHandler interface:

[Test]
public void TestAction_WithException_CallsAddException()
{
    // Arrange
    var traceHandlerMock = new Mock<ITraceHandler>();
    var controller = new YourController(traceHandlerMock.Object);

    // Act & Assert would depend on your specific test scenario
    // The key is verifying that AddException is called when exceptions occur
}

Troubleshooting

Common Issues

Missing X-Ray registration: Ensure services.RegisterAWSXRay() is called in ConfigureServices
Incorrect middleware order: Place XRayTracingMiddleware after routing but before authentication
AWS credentials: Verify the application has proper AWS credentials and permissions
Missing exception tracking: Ensure AddException is called in all catch blocks

Verification

Check AWS X-Ray console for trace data
Use the health check endpoint to verify X-Ray functionality
Monitor CloudWatch logs for X-Ray errors
Exceptions should appear in X-Ray traces when AddException is properly called

Key Differences from Manual Tracing

Unlike manual tracing implementations:

No manual subsegment creation required: The middleware handles request-level tracing automatically
Focus on exception handling: Manual intervention is only needed for exception tracking
Simplified implementation: Reduces boilerplate code and potential for errors
Consistent tracing: Ensures all requests are traced uniformly across the application

This implementation provides comprehensive distributed tracing capabilities with minimal manual intervention, focusing developer effort on proper exception handling rather than request-level tracing mechanics.