Tracing
Powertools for AWS Lambda (.NET) tracing is an opinionated thin wrapper for AWS X-Ray .NET SDK a provides functionality to reduce the overhead of performing common tracing tasks.
Key Features¶
- Helper methods to improve the developer experience for creating custom AWS X-Ray subsegments.
- Capture cold start as annotation.
- Capture function responses and full exceptions as metadata.
- Better experience when developing with multiple threads.
- Auto-patch supported modules by AWS X-Ray
- Auto-disable when not running in AWS Lambda environment
- Ahead-of-Time compilation to native code support AOT from version 1.5.0
Installation¶
Powertools for AWS Lambda (.NET) are available as NuGet packages. You can install the packages from NuGet Gallery or from Visual Studio editor by searching AWS.Lambda.Powertools*
to see various utilities available.
-
AWS.Lambda.Powertools.Tracing:
dotnet nuget add AWS.Lambda.Powertools.Tracing
Getting Started¶
Tracer relies on AWS X-Ray SDK over OpenTelememetry Distro (ADOT) for optimal cold start (lower latency).
Before you use this utility, your AWS Lambda function must have permissions to send traces to AWS X-Ray.
To enable active tracing on an AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function resource, use the Tracing
property. You can use the Globals section of the AWS SAM template to set this for all
Using AWS Serverless Application Model (AWS SAM)¶
1 2 3 4 5 6 7 8 9 10 11 |
|
The Powertools for AWS Lambda (.NET) service name is used as the X-Ray namespace. This can be set using the environment variable
POWERTOOLS_SERVICE_NAME
Full list of environment variables¶
Environment variable | Description | Default |
---|---|---|
POWERTOOLS_SERVICE_NAME | Sets service name used for tracing namespace, metrics dimension and structured logging | "service_undefined" |
POWERTOOLS_TRACE_DISABLED | Disables tracing | false |
POWERTOOLS_TRACER_CAPTURE_RESPONSE | Captures Lambda or method return as metadata. | true |
POWERTOOLS_TRACER_CAPTURE_ERROR | Captures Lambda or method exception as metadata. | true |
Lambda handler¶
To enable Powertools for AWS Lambda (.NET) tracing to your function add the [Tracing]
attribute to your FunctionHandler
method or on
any method will capture the method as a separate subsegment automatically. You can optionally choose to customize
segment name that appears in traces.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
|
1 2 3 4 5 6 7 8 9 |
|
By default, this attribute will automatically record method responses and exceptions. You can change the default behavior by setting
the environment variables POWERTOOLS_TRACER_CAPTURE_RESPONSE
and POWERTOOLS_TRACER_CAPTURE_ERROR
as needed. Optionally, you can override behavior by different supported CaptureMode
to record response, exception or both.
Returning sensitive information from your Lambda handler or functions, where Tracing
is used?
You can disable attribute from capturing their responses and exception as tracing metadata with captureMode=DISABLED
or globally by setting environment variables POWERTOOLS_TRACER_CAPTURE_RESPONSE
and POWERTOOLS_TRACER_CAPTURE_ERROR
to false
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Annotations & Metadata¶
Annotations are key-values associated with traces and indexed by AWS X-Ray. You can use them to filter traces and to create Trace Groups to slice and dice your transactions.
Metadata are key-values also associated with traces but not indexed by AWS X-Ray. You can use them to add additional context for an operation using any native object.
You can add annotations using AddAnnotation()
method from Tracing
1 2 3 4 5 6 7 8 9 10 11 |
|
You can add metadata using AddMetadata()
method from Tracing
1 2 3 4 5 6 7 8 9 10 11 |
|
Utilities¶
Tracing modules comes with certain utility method when you don't want to use attribute for capturing a code block under a subsegment, or you are doing multithreaded programming. Refer examples below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
Instrumenting SDK clients and HTTP calls¶
You should make sure to instrument the SDK clients explicitly based on the function dependency. You can instrument all of your AWS SDK for .NET clients by calling RegisterForAllServices before you create them.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
To instrument clients for some services and not others, call Register instead of RegisterForAllServices. Replace the highlighted text with the name of the service's client interface.
1 |
|
This functionality is a thin wrapper for AWS X-Ray .NET SDK. Refer details on how to instrument SDK client with Xray and outgoing http calls.
AOT Support¶
Native AOT trims your application code as part of the compilation to ensure that the binary is as small as possible. .NET 8 for Lambda provides improved trimming support compared to previous versions of .NET.
These improvements offer the potential to eliminate build-time trimming warnings, but .NET will never be completely trim safe. This means that parts of libraries that your function relies on may be trimmed out as part of the compilation step. You can manage this by defining TrimmerRootAssemblies as part of your .csproj
file as shown in the following example.
For the Tracing utility to work correctly and without trim warnings please add the following to your .csproj
file
1 2 3 4 5 6 |
|
Note that when you receive a trim warning, adding the class that generates the warning to TrimmerRootAssembly might not resolve the issue. A trim warning indicates that the class is trying to access some other class that can't be determined until runtime. To avoid runtime errors, add this second class to TrimmerRootAssembly.
To learn more about managing trim warnings, see Introduction to trim warnings in the Microsoft .NET documentation.