diff --git a/src/OpenTelemetry.Instrumentation.AWSLambda/README.md b/src/OpenTelemetry.Instrumentation.AWSLambda/README.md index 28adbb4bb6..a41913b46d 100644 --- a/src/OpenTelemetry.Instrumentation.AWSLambda/README.md +++ b/src/OpenTelemetry.Instrumentation.AWSLambda/README.md @@ -15,17 +15,44 @@ Add `AddAWSLambdaConfigurations()` to `TracerProvider`. ```csharp TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder() // add other instrumentations - .AddAWSLambdaConfigurations() + .AddAWSLambdaConfigurations(options => options.DisableAwsXRayContextExtraction = true) .Build(); ``` +### AWSLambdaInstrumentationOptions + +`AWSLambdaInstrumentationOptions` contains various properties to configure +AWS lambda instrumentation: + +* [`DisableAwsXRayContextExtraction`](/src/OpenTelemetry.Instrumentation.AWSLambda/AWSLambdaInstrumentationOptions.cs) +* [`SetParentFromBatch`](/src/OpenTelemetry.Instrumentation.AWSLambda/AWSLambdaInstrumentationOptions.cs) + ## Instrumentation +`AWSLambdaWrapper` contains tracing methods covering different types of +function handler method signatures. `AWSLambdaWrapper.Trace()` and +`AWSLambdaWrapper.TraceAsync()` are used for wrapping synchronous +and asynchronous function handlers respectively. The `ActivityContext parentContext` +parameter is optional and used to pass a custom parent context. If the parent +is not passed explicitly then it's either extracted from the +input parameter or uses AWS X-Ray headers if AWS X-Ray context extraction is +enabled (see configuration property `DisableAwsXRayContextExtraction`). +The sequence of the parent extraction: +`explicit parent` -> `parent from input parameter` -> `AWS X-Ray headers` -> `default` +The parent extraction is supported for the input types listed in the table below: + +| Type | Parent extraction source | +|------|--------------------------| +| `APIGatewayProxyRequest, APIGatewayHttpApiV2ProxyRequest` | HTTP headers of the request | +| `SQSEvent` | Attributes of the last `SQSMessage` (if `SetParentFromMessageBatch` is `true`) | +| `SNSEvent` | Attributes of the last `SNSRecord` | + ### Lambda Function -1. Create a wrapper function with the same signature as the original Lambda function. -Call `AWSLambdaWrapper.Trace()` API and pass `TracerProvider`, original Lambda function -and its inputs as parameters. +1. Create a wrapper function with the same signature as the original Lambda +function but an added ILambdaContext parameter if it was not already present. +Call `AWSLambdaWrapper.Trace()` or `AWSLambdaWrapper.TraceAsync()` API and pass +`TracerProvider`, original Lambda function and its parameters. 2. Set the wrapper function as the Lambda handler input. @@ -48,14 +75,14 @@ public string OriginalFunctionHandler(JObject input, ILambdaContext context) For using base classes from package [Amazon.Lambda.AspNetCoreServer](https://github.com/aws/aws-lambda-dotnet/tree/master/Libraries/src/Amazon.Lambda.AspNetCoreServer#amazonlambdaaspnetcoreserver), override the `FunctionHandlerAsync` function in `LambdaEntryPoint.cs` file. Call -`AWSLambdaWrapper.Trace()` API and pass `TracerProvider`, original Lambda function +`AWSLambdaWrapper.TraceAsync()` API and pass `TracerProvider`, original Lambda function and its inputs as parameters. Below is an example if using `APIGatewayProxyFunction` as base class. ```csharp public override async Task<APIGatewayProxyResponse> FunctionHandlerAsync( APIGatewayProxyRequest request, ILambdaContext lambdaContext) -=> await AWSLambdaWrapper.Trace(tracerProvider, base.FunctionHandlerAsync, +=> await AWSLambdaWrapper.TraceAsync(tracerProvider, base.FunctionHandlerAsync, request, lambdaContext); ``` @@ -75,7 +102,7 @@ public class Function .AddHttpClientInstrumentation() .AddAWSInstrumentation() .AddOtlpExporter() - .AddAWSLambdaConfigurations() + .AddAWSLambdaConfigurations(options => options.DisableAwsXRayContextExtraction = true) .Build(); }