Menu
AWS X-Ray
Developer Guide

Instrumenting Incoming HTTP Requests with the X-Ray SDK for .NET

You can use the X-Ray SDK to trace incoming HTTP requests that your application serves on an EC2 instance in Amazon EC2, AWS Elastic Beanstalk, or Amazon ECS.

Use a TracingMessageHandler to instrument incoming HTTP requests. When you add the X-Ray message handler to your application, the X-Ray SDK for .NET creates a segment for each sampled request. Any segments created by additional instrumentation become subsegments of the request-level segment that provides information about the HTTP request and response, including timing, method, and disposition of the request.

Each segment has a name that identifies your application in the service map. The segment can be named statically, or you can configure the SDK to name it dynamically based on the host header in the incoming request. Dynamic naming lets you group traces based on the domain name in the request, and apply a default name if the name doesn't match an expected pattern (for example, if the host header is forged).

Forwarded Requests

If a request is forwarded to your application by a load balancer or other intermediary, The client IP in the segment is taken from the X-Forwarded-For header in the request instead of the source IP in the IP packet. The client IP recorded for a forwarded request can be forged so should not be trusted.

The message handler creates a segment for each incoming request with an http block that contains the following information:

  • HTTP method – GET, POST, PUT, DELETE, etc.

  • Client address – The IP address of the client that sent the request.

  • Response code – The HTTP response code for the completed request.

  • Timing – The start time (when the request was received) and end time (when the response was sent).

Adding a Tracing Message Handler to your Application's HTTP Configuration

To instrument requests served by your application, add a TracingMessageHandler to the HttpConfiguration.MessageHandlers collection in your web configuration.

Example WebApiConfig - Message handler

using System.Web.Http;
using Amazon.XRay.Recorder.Handler.Http;
using SampleEBWebApplication.Controllers;

namespace SampleEBWebApplication
{
  public static class WebApiConfig
  {
    public static void Register(HttpConfiguration config)
    {
      // Add the message handler to HttpConfiguration
      config.MessageHandlers.Add(new TracingMessageHandler("MyApp"));
      // Web API routes
      config.MapHttpAttributeRoutes();
      config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
      );
    }
  }
}

Adding a Tracing Message Handler to your Application Global Configuration

Alternatively, you can also add the tracing handler to a global.asax file.

Example global.asax - Message handler

using System.Web.Http;

namespace SampleEBWebApplication
{
  public class WebApiApplication : System.Web.HttpApplication
  {
    protected void Application_Start()
    {
      GlobalConfiguration.Configure(WebApiConfig.Register);
      GlobalConfiguration.Configuration.MessageHandlers.Add(new TracingMessageHandler("MyApp"));
    }
  }
}

Configuring a Segment Naming Strategy

The X-Ray SDK can name segments after the host name in the HTTP request header, but this header can be forged, which could result in unexpected nodes in your service map. To prevent the SDK from naming segments incorrectly due to requests with forged host headers, you must specify a name to use for all segments, or configure a dynamic naming strategy. A dynamic naming strategy allows the SDK to use the host name for names that match an expected pattern, and apply a default name to names that don't.

To use the same name for all request segments, specify the name of your application when you initialize the servlet filter, as shown in the previous section. This has the same effect as creating a FixedSegmentNamingStrategy and passing it to the TracingMessageHandler constructor.

config.MessageHandlers.Add(new TracingMessageHandler(new FixedSegmentNamingStrategy("MyApp"));

Note

You can override the service name that you define in code with the AWS_XRAY_TRACING_NAME environment variable.

A dynamic naming strategy defines a pattern that host names should match, and a default name to use if the host name in the HTTP request does not match the pattern. To name segments dynamically, create a DynamicSegmentNamingStrategy and pass it to the TracingMessageHandler constructor.

config.MessageHandlers.Add(new TracingMessageHandler(new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));