The AWS X-Ray SDK for .NET and .NET Core (.netstandard 2.0 and above) is in the form of Nuget packages. You can install the packages from Nuget gallery or from Visual Studio editor. Search AWSXRayRecorder* to see various middlewares available.
Use the following community resources for getting help with the SDK. We use the GitHub issues for tracking bugs and feature requests.
- Ask a question in the AWS X-Ray Forum.
- Open a support ticket with AWS Support.
- If you think you may have found a bug, open an issue.
If you encounter a bug with the AWS X-Ray SDK for .NET/.NET Core, we want to hear about it. Before opening a new issue, search the existing issues to see if others are also experiencing the issue. Include platform (.NET/ .NET Core). In addition, include the repro case when appropriate.
The GitHub issues are intended for bug reports and feature requests. For help and questions about using the AWS X-Ray SDK for .NET and .NET Core, use the resources listed in the Getting Help section. Keeping the list of open issues lean helps us respond in a timely manner.
The developer guide provides in-depth guidance about using the AWS X-Ray service. Following API reference documentation provides guidance for using the SDK and module-level documentation.
- The API Reference for .NET
- The API Reference for .NET Core
- AWS X-Ray SDK Documentation for .NET SDK
- Sample Apps
- Configuration
- ASP.NET Core Framework
- ASP.NET Framework
- Trace AWS SDK request
- Trace out-going HTTP requests
- Trace Query to SQL Server
- Multithreaded Execution
- Trace custom methods
- Creating custom Segment/Subsegment
- Adding metadata/annotations
- AWS Lambda support (.NET Core)
- ASP.NET Core on AWS Lambda
- Logging
- Enabling X-Ray on Elastic Beanstalk
- Enabling X-Ray on AWS Lambda
You can configure X-Ray in the appsettings of your App.config or Web.config file.
<configuration>
<appSettings>
<add key="DisableXRayTracing" value="false"/>
<add key="AWSXRayPlugins" value="EC2Plugin, ECSPlugin, ElasticBeanstalkPlugin"/>
<add key="SamplingRuleManifest" value="JSONs\DefaultSamplingRules.json"/>
<add key="AwsServiceHandlerManifest" value="JSONs\AWSRequestInfo.json"/>
<add key="UseRuntimeErrors" value="true"/>
</appSettings>
</configuration>Following are the steps to configure your .NET Core project with X-Ray.
a) In appsettings.json file, configure items under XRay key
{
"XRay": {
"DisableXRayTracing": "false",
"SamplingRuleManifest": "SamplingRules.json",
"AWSXRayPlugins": "EC2Plugin, ECSPlugin, ElasticBeanstalkPlugin",
"AwsServiceHandlerManifest": "JSONs\AWSRequestInfo.json",
"UseRuntimeErrors":"true"
}
}
b) Register IConfiguration instance with X-Ray:
using Amazon.XRay.Recorder.Core;
AWSXRayRecorder.InitializeInstance(configuration); // pass IConfiguration object that reads appsettings.json fileNote:
- You should configure this before initialization of
AWSXRayRecorderinstance and using any AWS X-Ray methods. - If you manually need to configure
IConfigurationobject refer: Link - For more information on configuration, please refer : Link
ASP.NET Core Framework (.NET Core) : Nuget
You can instrument X-Ray for your ASP.NET Core App in the Configure() method of Startup.cs file of your project.
Note :
- Use
app.UseXRay()middleware afterapp.UseExceptionHandler("/Error")in order to catch exceptions. - You need to install
Amazon.XRay.Recorder.Handlers.AspNetCorenuget package. This package adds extension methods to theIApplicationBuilderto make it easy to register AWS X-Ray to the ASP.NET Core HTTP pipeline.
A) With default configuration:
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseExceptionHandler("/Error");
app.UseXRay("SampleApp"); // name of the app
app.UseStaticFiles(); // rest of the middlewares
app.UseMVC();
}B) With custom X-Ray configuration
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseExceptionHandler("/Error");
app.UseXRay("SampleApp",configuration); // IConfiguration object is not required if you have used "AWSXRayRecorder.InitializeInstance(configuration)" method
app.UseStaticFiles(); // rest of the middlewares
app.UseMVC();
}Instead of name you can also pass SegmentNamingStrategy in the above two ways. Please refer: Link
ASP.NET Framework (.NET) : Nuget
HTTP Message handler for ASP.NET framework
Register your application with X-Ray in the Init() method of global.asax file
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
}
}At the start of each Http request, a segment is created and stored in the context (Key : AWSXRayASPNET.XRayEntity) of HttpApplication instance. If users write their custom error handler for ASP.NET framework, they can access segment for the current request by following way :
<%@ Import Namespace="Amazon.XRay.Recorder.Handlers.AspNet" %>
<%@ Import Namespace="Amazon.XRay.Recorder.Core.Internal.Entities" %>
<script runat="server">
protected void Page_Load(object sender, EventArgs e)
{
var context = System.Web.HttpContext.Current.ApplicationInstance.Context;
var segment = (Segment) context.Items[AWSXRayASPNET.XRayEntity]; // get segment from the context
segment.AddMetadata("Error","404");
}
</script>Trace AWS SDK request (.NET and .NET Core) : Nuget
using Amazon.XRay.Recorder.Handlers.AwsSdk;
AWSSDKHandler.RegisterXRayForAllServices(); //place this before any instantiation of AmazonServiceClient
AmazonDynamoDBClient client = new AmazonDynamoDBClient(RegionEndpoint.USWest2); // AmazonDynamoDBClient is automatically registered with X-RayMethods of AWSSDKHandler class:
AWSSDKHandler.RegisterXRayForAllServices(); // all instances of AmazonServiceClient created after this line are registered
AWSSDKHandler.RegisterXRay<IAmazonDynamoDB>(); // Registers specific type of AmazonServiceClient : All instances of IAmazonDynamoDB created after this line are registered
AWSSDKHandler.RegisterXRayManifest(String path); // To configure custom AWS Service Manifest file. This is optional, if you have followed "Configuration" sectionTrace out-going HTTP requests (.NET and .NET Core) : Nuget
An extension method GetResponseTraced() is provided to trace GetResponse() in System.Net.HttpWebRequest class. If you want to trace the out-going HTTP request, call the GetResponseTraced() instead of GetResponse(). The extension method will generate a trace subsegment, inject the trace header to the out-going HTTP request header and collect trace information.
using AWSXRayRecorder.Handlers.System.Net;
HttpWebRequest request = (HttpWebRequest) WebRequest.Create(URL); // enter desired url
// Any other configuration to the request
request.GetResponseTraced();An extension method GetAsyncResponseTraced() is provided to trace GetResponseAsync() in System.Net.HttpWebRequest class. If you want to trace the out-going HTTP request, call the GetAsyncResponseTraced() instead of GetResponseAsync(). The extension method will generate a trace subsegment, inject the trace header to the out-going HTTP request header and collect trace information.
using AWSXRayRecorder.Handlers.System.Net;
HttpWebRequest request = (HttpWebRequest) WebRequest.Create(URL); // enter desired url
// Any other configuration to the request
request.GetAsyncResponseTraced();A handler derived from DelegatingHandler is provided to trace the HttpMessageHandler.SendAsync method
using AWSXRayRecorder.Handlers.System.Net;
var httpClient = new HttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler()));
// Any other configuration to the client
httpClient.GetAsync(URL);Trace Query to SQL Server (.NET and .NET Core) : Nuget
The SDK provides a wrapper class for System.Data.SqlClient.SqlCommand. The wrapper class can be used interchangable with SqlCommand class. By replacing instance of SqlCommand to TraceableSqlCommand, synchronized/asynchronized method will automatically generate subsegment for the SQL query.
using AWSXRayRecorder.Handlers.SqlServer;
using (var connection = new SqlConnection("fake connection string"))
using (var command = new TraceableSqlCommand("SELECT * FROM products", connection))
{
command.ExecuteNonQuery();
}using AWSXRayRecorder.Handlers.SqlServer;
using (var connection = new SqlConnection(ConnectionString))
{
var command = new TraceableSqlCommand("SELECT * FROM Products FOR XML AUTO, ELEMENTS", connection);
command.Connection.Open();
await command.ExecuteXmlReaderAsync();
}Multithreaded Execution (.NET and .NET Core) : Nuget
In multithreaded execution, X-Ray context from current to its child thread is automatically set.
using AWSXRayRecorder.Core;
private static void TestMultiThreaded()
{
int numThreads = 3;
AWSXRayRecorder.Instance.BeginSegment("MainThread");
Thread[] t= new Thread[numThreads];
for(int i = 0; i < numThreads; i++)
{
t[i] = new Thread(()=>MakeHttpRequest(i));
t[i].Start();
}
for (int i = 0; i < numThreads; i++)
{
t[i].Join();
}
AWSXRayRecorder.Instance.EndSegment();
}
private static void MakeHttpRequest(int i)
{
AWSXRayRecorder.Instance.TraceMethodAsync("Thread "+i, CreateRequestAsync<HttpResponseMessage>).Wait();
}
private static async Task<HttpResponseMessage> CreateRequestAsync <TResult>()
{
var request = new HttpClient();
var result = await request.GetAsync(URL); // Enter desired url
return result;
}Note:
- Context used to save traces in .NET : CallContext
- Context used to save traces in .NET Core : AsyncLocal
It may be useful to further decorate portions of an application for which performance is critical. Generating subsegments around these hot spots will help in understanding their impact on application performance.
using AWSXRayRecorder.Core;
AWSXRayRecorder.Instance.TraceMethod("custom method", () => DoSomething(arg1, arg2, arg3));using AWSXRayRecorder.Core;
var response = await AWSXRayRecorder.Instance.TraceMethodAsync("AddProduct", () => AddProduct<Document>(product));
private async Task<Document> AddProduct <TResult>(Product product)
{
var document = new Document();
document["Id"] = product.Id;
document["Name"] = product.Name;
document["Price"] = product.Price;
return await LazyTable.Value.PutItemAsync(document);
}using AWSXRayRecorder.Core;
AWSXRayRecorder.Instance.BeginSegment("segment name"); // generates `TraceId` for you
try
{
DoSometing();
// can create custom subsegments
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSegment();
}If you want to pass custom TraceId:
using AWSXRayRecorder.Core;
String traceId = TraceId.NewId(); // This function is present in : Amazon.XRay.Recorder.Core.Internal.Entities
AWSXRayRecorder.Instance.BeginSegment("segment name",traceId); // custom traceId used while creating segment
try
{
DoSometing();
// can create custom subsegments
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSegment();
}Note: This should only be used after BeginSegment() method.
using AWSXRayRecorder.Core;
AWSXRayRecorder.Instance.BeginSubsegment("subsegment name");
try
{
DoSometing();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}using Amazon.XRay.Recorder.Core;
AWSXRayRecorder.Instance.AddAnnotation("mykey", "my value");
AWSXRayRecorder.Instance.AddMetadata("my key", "my value");You can create Subsegment inside lambda function.
Note: The AWS Lambda execution environment creates a Segment before the Lambda function is invoked, so a Segment cannot be created inside the Lambda function.
public string FunctionHandler(string input, ILambdaContext context)
{
AWSXRayRecorder recorder = new AWSXRayRecorder();
recorder.BeginSubsegment("UpperCase");
recorder.BeginSubsegment("Inner 1");
String result = input?.ToUpper();
recorder.EndSubsegment();
recorder.BeginSubsegment("Inner 2");
recorder.EndSubsegment();
recorder.EndSubsegment();
return result;
}We support instrumenting ASP.NET Core web app on Lambda. Please follow the steps of ASP.NET Core instrumentation.
The AWS X-Ray .NET SDK share the same logging mechanism as AWS .NET SDK. If the application had already configured logging for AWS .NET SDK, it should just work for AWS X-Ray .NET SDK.
The recommended way to configure an application is to use the element in the project’s App.config or Web.config file.
<configuration>
<configSections>
<section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/>
</configSections>
<aws>
<logging logTo="Log4Net"/>
</aws>
</configuration>Other ways to configure logging is to edit the element in the App.config or Web.config file, and set property values in the AWSConfig class. Refer to the following page for more details and example : Link
Currently we support log4net logging and options provided in LoggingOptions. You should configure logging before initialization of AWSXRayRecorder instance or using any X-Ray methods.
Following is the way to configure logging with X-Ray SDK:
using Amazon;
using Amazon.XRay.Recorder.Core;
class Program
{
static Program()
{
AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net); // Log4Net instance should already be configured before this point
}
}log4net.config example:
<?xml version="1.0" encoding="utf-8" ?>
<log4net>
<appender name="FileAppender" type="log4net.Appender.FileAppender,log4net">
<file value="c:\logs\sdk-log.txt" />
<layout type="log4net.Layout.PatternLayout">
<conversionPattern value="%date [%thread] %level %logger - %message%newline" />
</layout>
</appender>
<logger name="Amazon">
<level value="DEBUG" />
<appender-ref ref="FileAppender" />
</logger>
</log4net>Note: For log4net configuration, refer : Link
The AWS X-Ray SDK for .NET and .NET Core is licensed under the Apache 2.0 License. See LICENSE and NOTICE.txt for more information.