mirrors/aws-xray-dotnet-agent

# AWS X-Ray .NET Agent

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.

Upcoming Maintenance Mode on February 25, 2026

The AWS X-Ray SDKs will enter maintenance mode on February 25, 2026. During maintenance mode, the X-Ray SDKs and Daemon will only receive critical bug fixes and security updates, and will not be updated to support new features.

We recommend that you migrate to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation to generate traces (through manual or zero-code instrumentation) from your application and send them to AWS X-Ray. OpenTelemetry is the industry-wide standard for tracing instrumentation and observability. It has a large open-source community for support and provides more instrumentations and updates. By adopting an OpenTelemetry solution, developers can leverage the latest services and innovations from AWS CloudWatch.

Compatibility Chart

Feature	X-Ray SDK(.NET)	X-Ray SDK(.NET Core)	X-Ray Agent(.NET)	X-Ray Agent(.NET Core)
AWS	✔	✔	✔	✔
Incoming Http	✔	✔	✔	✔
HttpClient	✔	✔	✔	✔
HttpWebRequest	✔	✔	✔	✔
System.Data.SqlClient	✔	✔	✔	✔
Microsoft.Data.SqlClient	❌	❌	❌	✔
EntityFramework	❌	✔ (EF Core)	✔ (EF 6)	✔ (EF Core)
Local Sampling	✔	✔	✔	✔
Dynamic Sampling	✔	✔	✔	✔
Multithreaded Execution	✔	✔	✔	✔
Plugins	✔	✔	✔	✔
Custom Subsegment	✔	✔	✔	✔

Prerequisites

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

Configuration

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.

Installation

Minimum Requirements

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.

Development

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.

Automatic Instrumentation

Internet Information Services (IIS)

Asp.Net Core & Asp.Net

Git clone this repo and import AWSXRayRecorder.AutoInstrumentation package into your project and rebuild.
Download and run AWS X-Ray .NET Agent Installer (x64 and x86).
Restart IIS and launch your application.
```
iisreset
```

Others (Not IIS)

Asp.Net Core

Git clone this repo and import AWSXRayRecorder.AutoInstrumentation package into your project and rebuild.
Download and run AWS X-Ray .NET Agent Installer (x64 and x86).
Launch your application as follows. ``` SET CORECLR_PROFILER={AE47A175-390A-4F13-84CB-7169CEBF064A} SET CORECLR_ENABLE_PROFILING=1

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.**

##### Asp.Net

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

<system.webServer> </system.webServer>

3. Launch your application

### Manual Instrumentation

#### Asp.Net Core

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();


## Getting Help

Please use these community resources for getting help.

* If you think you may have found a bug or need assistance, please open an [issue](https://github.com/aws/aws-xray-dotnet-agent/issues/new).
* Open a support ticket with [AWS Support](http://docs.aws.amazon.com/awssupport/latest/user/getting-started.html).
* Ask a question in the [AWS X-Ray Forum](https://forums.aws.amazon.com/forum.jspa?forumID=241&start=0).
* For contributing guidelines refer to [CONTRIBUTING.md](https://github.com/aws/aws-xray-dotnet-agent/blob/master/CONTRIBUTING.md).

## Documentation

The [developer guide](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html) provides guidance on using the AWS X-Ray DotNet Agent. Please refer to the [Sample App](https://github.com/aws-samples/aws-xray-dotnet-webapp) for an example.

## License

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