New AWS X-Ray .NET Core Support

In our AWS re:Invent talk this year, we preannounced support for .NET Core 2.0 with AWS Lambda and support for .NET Core 2.0 with AWS X-Ray. Last month we released the AWS Lambda support for .NET Core 2.0. This week we released the AWS X-Ray support for .NET Core 2.0, with new 2.0 beta versions of the AWS X-Ray SDK for .NET NuGet packages.

AWS X-Ray is a service that collects data about requests that your application serves. X-Ray provides tools you can use to view, filter, and gain insights into that data to identify issues and opportunities for optimization. For any traced request to your application, you can see detailed information in the AWS X-Ray console. This includes information not only about the request and response, but also about calls that your application makes to downstream AWS resources, microservices, databases, and HTTP web APIs.

In our .NET re:Invent talk, we showed a demo using X-Ray with Lambda, ASP.NET Core, and a couple AWS services to detect a performance problem. To better understand how you can use X-Ray to detect and diagnose performance problems with your application, check out the AWS X-Ray developer guide.

The biggest feature with the 2.0 beta release is support for .NET Core 2.0, which means you can use X-Ray with all of your AWS .NET Core applications. The 2.0 beta release also has new features such as improved integration with the AWS SDK for .NET, asynchronous support, and improved ASP.NET tracing support.

The 2.0 beta release is a major release for the AWS X-Ray SDK for .NET, so our initial release is a beta release. We encourage you to try it out now and give us feedback. You can do that through the new GitHub repository for the AWS X-Ray SDK for .NET. To add the 2.0 beta release to your project in Visual Studio, be sure to check the Include prerelease check box.

Adding X-Ray to your application

For X-Ray to provide the details of how your application is performing, your application must be instrumented to send tracing data to X-Ray. The AWS X-Ray SDK for .NET provides NuGet packages to make it easy to instrument your application for common scenarios.

AWS SDK for .NET

If your application is using the AWS SDK for .NET to access other AWS services, use the AWSXRayRecorder.Handlers.AwsSdk NuGet package to enable the collection of tracing data for your AWS requests.

For the 2.0 beta release we simplified how to integrate X-Ray with the AWS SDK for .NET. In the previous version of the X-Ray SDK, you had to register every instance of an AWS service client that you created with X-Ray. This caused you to add X-Ray to all parts of your application that were using AWS. That can be challenging if the service clients were created outside of your application code, for example, in a third-party library or a dependency injection framework like the one provided in ASP.NET Core applications.

With the new release, you just add a little bit of code at the start of your application and any AWS service clients created in your applications, including those created by third-party libraries or dependency injection frameworks, are enabled for X-Ray.

To register all AWS service clients, add the following line at the start of your application.


Amazon.XRay.Recorder.Handlers.AwsSdk.AWSSDKHandler.RegisterXRayForAllServices();

To register only certain AWS service clients with X-Ray, use the following command.


Amazon.XRay.Recorder.Handlers.AwsSdk.AWSSDKHandler.RegisterXRay<Amazon.S3.IAmazonS3>();

After these lines of code run, all AWS service clients created after this point are enabled to collect tracing data for X-Ray.

ASP.NET Applications

We’ve also improved support for collecting tracing data in ASP.NET applications. In the previous release, tracing data was collected only for web API controllers. For the 2.0 beta release, we’ve deprecated the AWSXRayRecorder.Handlers.AspNet.WebApi NuGet package in favor of the new AWSXRayRecorder.Handlers.AspNet package. AWSXRayRecorder.Handlers.AspNet works for both web API controllers and MVC controllers. To use this new support, you must remove the deprecated AWSXRayRecorder.Handlers.AspNet.WebApi package.

To enable AWS X-Ray tracing in your ASP.NET application, override the init method in your Global.asax.cs file, and then call the RegisterXRay method.


public override void Init()
{
	base.Init();

	AWSXRayASPNET.RegisterXRay(this, "XRayAspNetSample"); // default name of the web app
}

ASP.NET Core Applications

.NET Core 2.0 support is the major feature of the 2.0 beta release, so of course we wanted to ensure getting tracing data from the ASP.NET Core HTTP request was also simple. You do this using the AWSXRayRecorder.Handlers.AspNetCore NuGet package. After you add the package, just add the “app.UseXRay(“XRayAspNetCoreSample”);” line of code in the Configure method for the Startup class. Here is a full example.


public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseBrowserLink();
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
    }

    app.UseXRay("XRayAspNetCoreSample");

    app.UseStaticFiles();
    app.UseMvc();
}

The order in which features are registered to the IApplicationBuilder controls the order in which the features, like X-Ray, are called. Because we want X-Ray to capture as much request data as possible, we highly recommended that you add the UseXRay call earlier in the Configure method, but after the UseExceptionHandler. The exception handler will take away some of the exception data for the tracing if it’s registered after X-Ray.

Deploying Applications Enabled for X-Ray

To send tracing data collected by the AWS X-Ray SDK for .NET to the X-Ray service, the X-Ray daemon must be running in the same environment as the application. For AWS Elastic Beanstalk and AWS Lambda, this is taken care of for you when you enable X-Ray during the deployment. With the latest release of the AWS Toolkit for Visual Studio, the Elastic Beanstalk and Lambda deployment wizards are updated to enable X-Ray.

In the Elastic Beanstalk deployment wizard, enable X-Ray on the Application Options page.

In the Lambda deployment wizard, enable X-Ray on the Advanced Function Details page.

If you’re deploying Lambda functions as a serverless application, you can enable X-Ray in the serverless.template file by setting the Tracing property of your AWS::Serverless::Function resource to Active.


{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Transform" : "AWS::Serverless-2016-10-31",
  "Resources" : {
    "Get" : {
      "Type" : "AWS::Serverless::Function",
      "Properties": {
        "Handler": "XRayServerlessSample::XRayServerlessSample.Functions::Get",
        "Runtime": "dotnetcore2.0",
        "CodeUri": "",
        "MemorySize": 256,
        "Timeout": 30,
        "Policies": [ "AWSLambdaBasicExecutionRole" ],

        "Tracing" : "Active",

        "Events": {
          "PutResource": {
            "Type": "Api",
            "Properties": {
              "Path": "/",
              "Method": "GET"
            }
          }
        }
      }
    }
  },
  "Outputs" : {

  }

}

In addition, the Amazon.Lambda.Tools and Amazon.ElasticBeanstalk.Tools extensions to the dotnet CLI were updated to support enabling X-Ray tracing in the target deployment environments.

Conclusion

I think .NET developers will be very excited to see the type of data AWS X-Ray can show about their applications, so we hope you check out this new update. Also, you’ll find a lot more information on the advanced configuration you can do with X-Ray on the AWS X-Ray SDK for .NET GitHub repository. If you have any issues with the 2.0 beta release, let us know by opening an issue in our GitHub repository.

AWS Developer Tools Blog