The AWS X-Ray .NET Agent is a drop-in solution that enables the propagation of X-Ray traces within your web applications. This includes automatic tracing for AWS X-Ray SDK supported frameworks and libraries. The agent enables you to use the X-Ray SDK out of box, and requires no code changes to enable the basic propagation of traces. See the compatibility chart below for the current feature parity between the AWS X-Ray .NET SDK and the AWS X-Ray .NET Agent.

See the Sample App for a demonstration on how to use the agent.

If you're running an Asp.Net Core application, you need to install the latest version of Visual C++ Redistributable

AWS X-Ray .Net Agent will register the configuration items as AWS X-Ray .NET SDK.

Besides, AWS X-Ray .Net Agent will register the following configuration items.

{
    "ServiceName" : "DefaultService",
    "DaemonAddress" : "127.0.0.1:2000",
    "TraceHttpRequests" : "true",
    "TraceAWSRequests" : "true",
    "TraceSqlRequests" : "true",
    "TraceEFRequests" : "true"
}

You can customize the service name of your application, the daemon address and specify which request to trace through appsettings.json file (Asp.Net Core) or web.config file (Asp.Net).

If you don't provide these configuration items, the default values shown above will be applied by AWS X-Ray .NET Agent.

Note:

• .Net Agent doesn't provide configuration item to disable tracing incoming Http request. If you want to disable tracing incoming request, you may set DisableXRayTracing as true.

• AWS request will trigger Http outgoing handler, so if you want to disable tracing AWS request, you have to disable both AWS handler and Http outgoing handler.

• Similiar situation happens to Entity Framework request, which triggers both Entity Framework handler and Sql handler, therefore, if you want to disable tracing Entity Framework request, remember to disable Sql handler as well.

For building AWSXRayRecorder.AutoInstrumentation package, you need to install Visual Studio 2019.

For building profiler, you need to have workloads .NET desktop development and Desktop development with C++ installed within Visual Studio 2019.

Currently, the AWSXRayRecorder.AutoInstrumentation Nuget hasn’t been released yet (please stay tuned!), so in case that you need to add it to you application, you can git clone this repo, reference AWSXRayRecorder.AutoInstrumentation package to your application and rebuild.

Note:

DotNet Coreclr Lib is required to build the profiler project in this repo. You can find it at this repo. Put coreclr folder under aws-xray-dotnet-agent\src\profiler, then you are good to go.

1. Import AWSXRayRecorder.AutoInstrumentation package into your project and rebuild.
2. Download and run AWS X-Ray .NET Agent Installer (x64 and x86).
3. Restart IIS and launch your application.

iisreset

1. Import AWSXRayRecorder.AutoInstrumentation package into your project and rebuild.
2. Follow development instructions and build profiler. The output file of profiler should be ClrProfiler.dll.
3. Launch your application as follows.

SET CORECLR_PROFILER={AE47A175-390A-4F13-84CB-7169CEBF064A}
SET CORECLR_ENABLE_PROFILING=1
SET CORECLR_PROFILER_PATH=\Path\to\ClrProfiler.dll\ // The path to ClrProfiler.dll that you built

dotnet YourApplication.dll

Note:

• Do not set environment variables globally into the system variables as profiler will try to instrument all .NET processes running on the instance with AWS X-Ray tracing SDK.

1. Import AWSXRayRecorder.AutoInstrumentation package into your project and rebuild.
2. Add the following snippet into the web.config file.

<system.webServer>
 <modules>
  <add name="AWSXRayTracingModule" type="Amazon.XRay.Recorder.AutoInstrumentation.AspNetAutoInstrumentationModule,AWSXRayRecorder.AutoInstrumentation,Version=2.9.0.0,Culture=neutral,PublicKeyToken=d427001f96b0d0b6" />
 </modules>
</system.webServer>

3. Launch your application

Instead of using profiler, you may choose to manually instrument AWS X-Ray SDK into your Asp.Net Core application.

1. Import AWSXRayRecorder.AutoInstrumentation package into your project.

2. Add the following method into any method in startup.cs or program.cs file

Amazon.XRay.Recorder.AutoInstrumentation.Initialize.AddXRay();

Please use these community resources for getting help.

• If you think you may have found a bug or need assistance, please open an issue.
• Open a support ticket with AWS Support.
• Ask a question in the AWS X-Ray Forum.
• For contributing guidelines refer to CONTRIBUTING.md.

The developer guide provides guidance on using the AWS X-Ray DotNet Agent. Please refer to the Sample App for an example.

The AWS X-Ray SDK DotNet Agent is licensed under the Apache 2.0 License. See LICENSE for more information.