AWS X-Ray support for .NET Core is GA

Last year the X-Ray team released a preview 2.0 version of the AWS X-Ray libraries for .NET Core. Today, these libraries are generally available (GA) as version 2.5.

AWS X-Ray helps developers analyze and debug distributed applications, such as those built using a microservices architecture. With X-Ray, you can understand how your application and its underlying services are performing to identify and troubleshoot the root cause of performance issues and errors. X-Ray provides a view on how requests go through your system and the other services that your requests are interacting with. To provide this fine-grained detail, developers instrument their applications using libraries that the AWS X-Ray team provides.

For a walkthrough of how to use the .NET support for X-Ray, check out our blog post for the preview release. https://aws.amazon.com/blogs/developer/new-aws-x-ray-net-core-support/

New features

The biggest feature of this new major version is support for .NET Core and ASP.NET Core. New .NET Standard 2.0 versions of the NuGet packages provide this support. This enables you to use X-Ray for your .NET Core 2.0 and later applications, including .NET Core Lambda functions.

Sampling configuration is also easier with this version, as you can now configure the sampling rules from the AWS Management Console. By configuring sampling rules, you can control the amount of data that you record, and modify sampling behavior on the fly without modifying or redeploying your code. For more information on configuring sample rules, see the AWS X-Ray Developer Guide, https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html.

Migrating from a previous version

If you’re migrating from the version 1.x of the AWS .NET X-Ray libraries, you’ll need to make a couple changes to your code before you migrate to the new version.

AWS SDK for .NET

In the 1.x version of the .NET library you needed to use the AWSSdkTracingHandler to instrument each AWS service client you created. It also didn’t support the case of a service client being created outside of your code’s control.

In version 2.5, instrumenting the AWS SDK for .NET for X-Ray is a lot more simple. You just add the following line at the start of your application.

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

Be aware the old AWSSdkTracingHandler has been removed, so when you upgrade to the new version, you must move to the new registration system.

ASP.NET

The 1.x version of the .NET libraries provided support for the ASP.NET Web API with the AWSXRayRecorder.Handlers.AspNet.WebApi NuGet package. In the new version, this package is deprecated. ASP.NET developers should use the new AWSXRayRecorder.Handlers.AspNet NuGet package.

This package contains support for any type of web request coming into your ASP.NET application. With this new package you add a registration call in the Global.asax.

using Amazon.XRay.Recorder.Handlers.AspNet;

public class MvcApplication : System.Web.HttpApplication
{
     public override void Init()
     {
        base.Init();
        AWSXRayASPNET.RegisterXRay(this, "ASPNETTest"); // default name of the web app
     }
}

For more information about the ASP.NET registration, see the AWS X-Ray SDK for .NET README.md file. https://github.com/aws/aws-xray-sdk-dotnet/tree/master#aspnet-framework-net—nuget

Conclusion

For a full list of changes with the new version, you can check out the change log, https://github.com/aws/aws-xray-sdk-dotnet/blob/master/CHANGELOG.md, on GitHub. We’d love to hear your feedback on our GitHub repository about our .NET support for X-Ray, and how we can make the experience better.