diff --git a/.github/dependabot.yml b/.github/dependabot.yml index aab722ad..3bf742f1 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -14,7 +14,47 @@ updates: prefix: chore include: scope - package-ecosystem: "nuget" # See documentation for possible values - directory: "/examples/" # Location of package manifests + directory: "/examples/Idempotency/" # Location of package manifests + schedule: + interval: "weekly" + target-branch: "develop" + commit-message: + prefix: chore + include: scope + - package-ecosystem: "nuget" # See documentation for possible values + directory: "/examples/Logging/" # Location of package manifests + schedule: + interval: "weekly" + target-branch: "develop" + commit-message: + prefix: chore + include: scope + - package-ecosystem: "nuget" # See documentation for possible values + directory: "/examples/Metrics/" # Location of package manifests + schedule: + interval: "weekly" + target-branch: "develop" + commit-message: + prefix: chore + include: scope + - package-ecosystem: "nuget" # See documentation for possible values + directory: "/examples/Parameters/" # Location of package manifests + schedule: + interval: "weekly" + target-branch: "develop" + commit-message: + prefix: chore + include: scope + - package-ecosystem: "nuget" # See documentation for possible values + directory: "/examples/ServerlessApi/" # Location of package manifests + schedule: + interval: "weekly" + target-branch: "develop" + commit-message: + prefix: chore + include: scope + - package-ecosystem: "nuget" # See documentation for possible values + directory: "/examples/Tracing/" # Location of package manifests schedule: interval: "weekly" target-branch: "develop" diff --git a/docs/core/tracing.md b/docs/core/tracing.md index 70b13f52..30a709cd 100644 --- a/docs/core/tracing.md +++ b/docs/core/tracing.md @@ -244,5 +244,36 @@ under a subsegment, or you are doing multithreaded programming. Refer examples b ## Instrumenting SDK clients and HTTP calls -User should make sure to instrument the SDK clients explicitly based on the function dependency. Refer details on -[how to instrument SDK client with Xray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-sdkclients.html) and [outgoing http calls](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-httpclients.html). +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. + +=== "Function.cs" + + ```c# hl_lines="14" + using Amazon.DynamoDBv2; + using Amazon.DynamoDBv2.Model; + using AWS.Lambda.Powertools.Tracing; + + public class Function + { + private static IAmazonDynamoDB _dynamoDb; + + /// + /// Function constructor + /// + public Function() + { + Tracing.RegisterForAllServices(); + + _dynamoDb = new AmazonDynamoDBClient(); + } + } + ``` + +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. + +```c# +Tracing.Register() +``` + +This functionality is a thin wrapper for AWS X-Ray .NET SDK. Refer details on [how to instrument SDK client with Xray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-sdkclients.html) and [outgoing http calls](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-httpclients.html). + diff --git a/docs/utilities/idempotency.md b/docs/utilities/idempotency.md index c1a675e0..d148abc5 100644 --- a/docs/utilities/idempotency.md +++ b/docs/utilities/idempotency.md @@ -140,7 +140,7 @@ You can quickly start by configuring `Idempotency` and using it with the `Idempo !!! warning "Important" Initialization and configuration of the `Idempotency` must be performed outside the handler, preferably in the constructor. - ```csharp hl_lines="4 7" + ```csharp hl_lines="5 8" public class Function { public Function() @@ -167,7 +167,7 @@ When using `Idempotent` attribute on another method, you must tell which paramet !!! info "The parameter must be serializable in JSON. We use `System.Text.Json` internally to (de)serialize objects" - ```csharp hl_lines="4 13-14" + ```csharp hl_lines="5 14-15" public class Function { public Function() @@ -211,7 +211,7 @@ If we were to treat the entire request as our idempotency key, a simple HTTP hea === "Payment function" - ```csharp hl_lines="3" + ```csharp hl_lines="4" Idempotency.Configure(builder => builder .WithOptions(optionsBuilder => @@ -221,7 +221,7 @@ If we were to treat the entire request as our idempotency key, a simple HTTP hea === "Sample event" - ```json hl_lines="27" + ```json hl_lines="28" { "version": "2.0", "routeKey": "ANY /createpayment", @@ -257,25 +257,25 @@ If we were to treat the entire request as our idempotency key, a simple HTTP hea ### Lambda timeouts ???+ note -This is automatically done when you decorate your Lambda handler with [Idempotent attribute](#idempotent-attribute). - -To prevent against extended failed retries when a [Lambda function times out](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-verify-invocation-timeouts/){target="_blank"}, -Powertools for AWS Lambda (.NET) calculates and includes the remaining invocation available time as part of the idempotency record. + This is automatically done when you decorate your Lambda handler with [Idempotent attribute](#idempotent-attribute). + + To prevent against extended failed retries when a [Lambda function times out](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-verify-invocation-timeouts/){target="_blank"}, + Powertools for AWS Lambda (.NET) calculates and includes the remaining invocation available time as part of the idempotency record. ???+ example -If a second invocation happens **after** this timestamp, and the record is marked as `INPROGRESS`, we will execute the invocation again as if it was in the `EXPIRED` state (e.g, `Expired` field elapsed). + If a second invocation happens **after** this timestamp, and the record is marked as `INPROGRESS`, we will execute the invocation again as if it was in the `EXPIRED` state (e.g, `Expired` field elapsed). This means that if an invocation expired during execution, it will be quickly executed again on the next retry. ???+ important -If you are only using the [Idempotent attribute](#Idempotent-attribute-on-another-method) to guard isolated parts of your code, -you must use `RegisterLambdaContext` available in the `Idempotency` static class to benefit from this protection. + If you are only using the [Idempotent attribute](#Idempotent-attribute-on-another-method) to guard isolated parts of your code, + you must use `RegisterLambdaContext` available in the `Idempotency` static class to benefit from this protection. Here is an example on how you register the Lambda context in your handler: === "Registering the Lambda context" - ```csharp hl_lines="9" title="Registering the Lambda context" + ```csharp hl_lines="10" title="Registering the Lambda context" public class Function { public Function() @@ -331,7 +331,7 @@ If an Exception is raised _outside_ the scope of the decorated method and after === "Handling exceptions" - ```csharp hl_lines="2-4 8-10" title="Exception not affecting idempotency record sample" + ```csharp hl_lines="10-12 16-18 21" title="Exception not affecting idempotency record sample" public class Function { public Function() @@ -675,7 +675,7 @@ With **`PayloadValidationJMESPath`**, you can provide an additional JMESPath exp === "Function.cs" - ```csharp + ```csharp hl_lines="6" Idempotency.Configure(builder => builder .WithOptions(optionsBuilder => @@ -730,7 +730,7 @@ This means that we will throw **`IdempotencyKeyException`** if the evaluation of === "Function.cs" - ```csharp + ```csharp hl_lines="9" public App() { Idempotency.Configure(builder => @@ -752,7 +752,7 @@ This means that we will throw **`IdempotencyKeyException`** if the evaluation of === "Success Event" - ```json + ```json hl_lines="6" { "user": { "uid": "BB0D045C-8878-40C8-889E-38B3CB0A61B1", @@ -782,7 +782,7 @@ When creating the `DynamoDBPersistenceStore`, you can set a custom [`AmazonDynam === "Custom AmazonDynamoDBClient" - ```csharp + ```csharp hl_lines="3 9" public Function() { AmazonDynamoDBClient customClient = new AmazonDynamoDBClient(RegionEndpoint.APSouth1); @@ -804,14 +804,16 @@ With this setting, we will save the idempotency key in the sort key instead of t You can optionally set a static value for the partition key using the `StaticPkValue` parameter. -```csharp title="Reusing a DynamoDB table that uses a composite primary key" -Idempotency.Configure(builder => - builder.UseDynamoDb(storeBuilder => - storeBuilder. - WithTableName("TABLE_NAME") - .WithSortKeyAttr("sort_key") - )); -``` +=== "Reusing a DynamoDB table that uses a composite primary key" + + ```csharp hl_lines="5" + Idempotency.Configure(builder => + builder.UseDynamoDb(storeBuilder => + storeBuilder. + WithTableName("TABLE_NAME") + .WithSortKeyAttr("sort_key") + )); + ``` Data would then be stored in DynamoDB like this: diff --git a/libraries/src/AWS.Lambda.Powertools.Tracing/AWS.Lambda.Powertools.Tracing.csproj b/libraries/src/AWS.Lambda.Powertools.Tracing/AWS.Lambda.Powertools.Tracing.csproj index 381a7f44..1fecd038 100644 --- a/libraries/src/AWS.Lambda.Powertools.Tracing/AWS.Lambda.Powertools.Tracing.csproj +++ b/libraries/src/AWS.Lambda.Powertools.Tracing/AWS.Lambda.Powertools.Tracing.csproj @@ -30,8 +30,9 @@ - + + diff --git a/libraries/src/AWS.Lambda.Powertools.Tracing/Internal/TracingAspectHandler.cs b/libraries/src/AWS.Lambda.Powertools.Tracing/Internal/TracingAspectHandler.cs index d1539dc2..e445ce8f 100644 --- a/libraries/src/AWS.Lambda.Powertools.Tracing/Internal/TracingAspectHandler.cs +++ b/libraries/src/AWS.Lambda.Powertools.Tracing/Internal/TracingAspectHandler.cs @@ -117,14 +117,15 @@ public void OnEntry(AspectEventArgs eventArgs) if (_captureAnnotations) { _xRayRecorder.AddAnnotation("ColdStart", _isColdStart); - - _isColdStart = false; + _captureAnnotations = false; _isAnnotationsCaptured = true; if (_powertoolsConfigurations.IsServiceDefined) _xRayRecorder.AddAnnotation("Service", _powertoolsConfigurations.Service); } + + _isColdStart = false; } /// diff --git a/libraries/src/AWS.Lambda.Powertools.Tracing/Tracing.cs b/libraries/src/AWS.Lambda.Powertools.Tracing/Tracing.cs index 357987b0..29e5b88a 100644 --- a/libraries/src/AWS.Lambda.Powertools.Tracing/Tracing.cs +++ b/libraries/src/AWS.Lambda.Powertools.Tracing/Tracing.cs @@ -15,6 +15,7 @@ using System; using Amazon.XRay.Recorder.Core.Internal.Entities; +using Amazon.XRay.Recorder.Handlers.AwsSdk; using AWS.Lambda.Powertools.Common; using AWS.Lambda.Powertools.Tracing.Internal; @@ -239,4 +240,20 @@ private static string GetNamespaceOrDefault(string nameSpace) return PowertoolsConfigurations.Instance.Service; } + + /// + /// Registers X-Ray for all instances of . + /// + public static void RegisterForAllServices() + { + AWSSDKHandler.RegisterXRayForAllServices(); + } + + /// + /// Registers X-Ray for the given type of . + /// + public static void Register() + { + AWSSDKHandler.RegisterXRay(); + } } \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 3d8fd5b4..9eac0182 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,13 +26,13 @@ theme: palette: - scheme: default primary: blue - accent: deep orange + accent: deep blue toggle: icon: material/toggle-switch-off-outline name: Switch to dark mode - scheme: slate primary: blue - accent: orange + accent: deep blue toggle: icon: material/toggle-switch name: Switch to light mode @@ -69,9 +69,15 @@ markdown_extensions: permalink: true toc_depth: 4 - attr_list - - pymdownx.emoji + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.inlinehilite - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format copyright: Copyright © 2023 Amazon Web Services @@ -88,3 +94,9 @@ extra_javascript: extra: version: provider: mike + social: + - icon: fontawesome/brands/github + link: https://github.com/aws-powertools/powertools-lambda-dotnet + - icon: fontawesome/brands/discord + link: https://discord.gg/B8zZKbbyET + name: Join our Discord Server! diff --git a/version.json b/version.json index 8e32d931..23c348a5 100644 --- a/version.json +++ b/version.json @@ -3,10 +3,10 @@ "Common": "1.1.2", "Logging": "1.2.0", "Metrics": "1.3.3", - "Tracing": "1.1.2" + "Tracing": "1.2.0" }, "Utilities": { - "Parameters": "0.0.3-preview", + "Parameters": "1.0.0", "Idempotency": "0.1.0-preview" } }