1.4.2

Summary

In this release we are excited to announce the release of custom log formatter support. You can customize the structure (keys and values) of your log entries by implementing a custom log formatter and override default log formatter using Logger.UseFormatter method. You can implement a custom log formatter by inheriting the ILogFormatter class and implementing the object FormatLogEntry(LogEntry logEntry) method.

We are also happy to announce the support for adding the Idempotent attribute on any method, not only the Lambda handler.

We also removed Moq library from our tests and replaced it with NSubsitute due to privacy concerns

We also made improvements to how we handle when an exception is thrown inside a method that is decorated with Powertools utilities the user should see the full stack trace for that exception.

Note
This change required us to update all utilities (Common). To avoid issues please update to the latest version all utilities you are using in your projects.
We are working to remove the dependency on Common (#339)

Custom log formatter

• Create a class that implements ILogFormatter
  

• Call method Logger.UseFormatter on Lambda function constructor
  

• Example CloudWatch Logs
  

Idempotent attribute on another method

You can use the Idempotent attribute for any .NET function, not only the Lambda handlers.
When using Idempotent attribute on another method, you must tell which parameter in the method signature has the data we should use:

• If the method only has one parameter, it will be used by default.
• If there are 2 or more parameters, you must set the IdempotencyKey attribute on the parameter to use.

Full list of changes

🌟New features and non-breaking changes

• feat: Add bring your own log formatter to logger (#375) by @amirkaws
• feat: idempotent function (#349) by @hossambarakat

📜 Documentation updates

• docs: Clarify why we currently prefer X-Ray over ADOT in Tracing (#347) by @hjgraca

🐛 Bug and hot fixes

• fix: Stack trace lost when exception is thrown the when using decorator (#357) by @hjgraca

🔧 Maintenance

• chore: Idempotency - refactor example to be simpler with a comparable idempotent output (#342) by @hjgraca
• chore: Replace Moq NuGet package with NSubstitute (#370) by @amirkaws
• chore(deps): bump AWSSDK.SecretsManager from 3.7.102.38 to 3.7.200.3 in /libraries (#359) by @dependabot
• chore(deps): bump xunit from 2.4.1 to 2.4.2 in /libraries (#328) by @dependabot
• chore(deps): bump AWSSDK.DynamoDBv2 from 3.7.103.1 to 3.7.104.1 in /libraries (#327) by @dependabot
• chore(deps): bump AWSXRayRecorder.Core from 2.13.0 to 2.14.0 in /libraries (#325) by @dependabot
• chore(deps): bump Testcontainers from 3.2.0 to 3.3.0 in /libraries (#326) by @dependabot
• chore(deps): bump Moq from 4.18.1 to 4.18.4 in /libraries (#329) by @dependabot

This release was made possible by the following contributors:

@amirkaws, @hjgraca and @hossambarakat

1.4.1

Summary

In this release we patch Metrics utility to version 1.3.2.
With this release we are releasing a fix that ensures that when a new data point is added, and the limit is reached, all the stored metrics are flushed right away.
Also release a fix for a race condition on the metrics utilities.

No changes in other utilities.

Metrics

Prior to this release the Metrics utility allowed to add a number of data points greater than the current limit of 100 data points set by the EMF specification.

If you are using Metrics in your workloads and are dealing with a large number of datapoints, we encourage to update to the latest version of the package at your earliest convenience.

📜 Documentation updates

• docs: Parameters example (#298) by @amirkaws
• chore: update urls to new format. remove latest from .net url (#315) by @hjgraca
• docs: ASP.NET Core WebAPI example(s) (#287) by @swimming-potato
• docs: Add Idempotency example (#300) by @hossambarakat

🐛 Bug and hot fixes

• fix: Prevent a single metric have more than 100 data points (#312) by @hjgraca
• fix: Metrics Race condition if using Async calls (#313) by @hjgraca

🔧 Maintenance

• chore: Update dependabot.yml (#318) by @hjgraca
• chore: Bump logging version to fix idempotency example (#320) by @hjgraca
• chore: Idempotency examples - Update AWSSDK.DynamoDBv2 version (#319) by @hjgraca
• chore: Create dependabot.yml to enable dependabot (#317) by @hjgraca
• docs: Parameters example (#298) by @amirkaws
• chore: update urls to new format. remove latest from .net url (#315) by @hjgraca
• chore: Readme updates (#314) by @hjgraca
• chore: remove GH pages (#303) by @sthulb
• chore: update changelog with latest changes (#308) by @hjgraca

This release was made possible by the following contributors:

@amirkaws, @hjgraca, @hossambarakat, @sthulb and @swimming-potato

1.4.0

Summary

In this release we are happy to announce the first developer preview for the new Idempotency utility 🚀. The Idempotency utility provides a simple solution to convert your Lambda functions into idempotent operations which are safe to retry.

⚠️ Warning
This utility is currently in developer preview and is intended strictly for feedback and testing purposes and not for production workloads. The version and all future versions tagged with the -preview suffix should be treated as not stable. Until this utility is General Availability we may introduce significant breaking changes and improvements in response to customers feedback.

🌟Key features

• Prevent Lambda handler function from executing more than once on the same event payload during a time window.
• Use DynamoDB as a persistence layer for state with bring your own persistence store provider.
• Select a subset of the event as the idempotency key using JMESPath expressions.
• Payload validation to provide an additional JMESPath expression to specify which part of the event body should be validated against previous idempotent invocations.

Implementation example

Quick links: 📜 Documentation | ⬇️ NuGet | 🐛 Bug Report

🌟New features and non-breaking changes

• feat: Add ClearAllDimensions Method (#293) by @glynn1211
• feat(docs): Start S3 Docs (#278) by @sthulb

📜 Documentation updates

• chore(docs): doc and readme updates (#301) by @sliedig
• docs: Update roadmap and maintainers (#291) by @hjgraca
• docs(parameter): adding required permission to SSM provider (#273) by @leandrodamascena

🐛 Bug and hot fixes

• fix: rename repository to powertools-lambda-dotnet (#302) by @sthulb
• chore(deps): update mkdocs configuration to support pymdown-extensions 10.0 (#276) by @hjgraca
• fix: parameters nuget icon (#271) by @amirkaws

🔧 Maintenance

• chore: Change repo URL to the new location (#285) by @sthulb
• chore: rename project to Powertools for AWS Lambda (.NET) (#282) by @sthulb
• chore: update changelog with latest changes (#277) by @hjgraca
• chore(deps): Bump pymdown-extensions from 9.9 to 10.0 (#276) by @hjgraca

This release was made possible by the following contributors:

@amirkaws, @hjgraca , @hossambarakat and @sliedig, @glynn1211 , @leandrodamascena , @sthulb and @glynn1211

1.3.0

Changes

In this release we are excited to announce the first developer preview for the new Parameters utility 🎉. This new utility provides high-level functionality to retrieve one or multiple parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB. We also provide extensibility to bring your own providers.

⚠️ Warning
This utility is currently in developer preview and is intended strictly for feedback and testing purposes and not for production workloads. The version and all future versions tagged with the -preview suffix should be treated as not stable. Until this utility is General Availability we may introduce significant breaking changes and improvements in response to customers feedback.

🌟Key features

• Retrieve one or multiple parameters from the underlying provider
• Cache parameter values for a given amount of time (defaults to 5 seconds)
• Transform parameter values from JSON or base 64 encoded strings
• Bring your own parameter store provider

--

Quick links: 📜 Documentation | ⬇️ NuGet | 🐛 Bug Report

This release was made possible by the following contributors:

@amirkaws, @hjgraca and @sliedig

1.2.0

Changes

Tracing and Logging utilities remain on 1.1.0 (no changes)

Metrics 1.2.0

Metrics produced by AWS services are standard resolution by default. When you publish a custom metric, you can define it as either standard resolution or high resolution. When you publish a high-resolution metric, CloudWatch stores it with a resolution of 1 second, and you can read and retrieve it with a period of 1 second, 5 seconds, 10 seconds, 30 seconds, or any multiple of 60 seconds.

High-resolution metrics can give you more immediate insight into your application's sub-minute activity. Keep in mind that every PutMetricData call for a custom metric is charged, so calling PutMetricData more often on a high-resolution metric can lead to higher charges. For more information about CloudWatch pricing, see Amazon CloudWatch Pricing.

If you set an alarm on a high-resolution metric, you can specify a high-resolution alarm with a period of 10 seconds or 30 seconds, or you can set a regular alarm with a period of any multiple of 60 seconds. There is a higher charge for high-resolution alarms with a period of 10 or 30 seconds.

{
   "_aws":{
      "Timestamp":1680086851067,
      "CloudWatchMetrics":[
         {
            "Namespace":"dotnet-powertools-test",
            "Metrics":[
               {
                  "Name":"Time",
                  "Unit":"Milliseconds",
                  "StorageResolution":60   <---- New property
               }
            ],
            "Dimensions":[
               [
                  "Service"
               ],
               [
                  "functionVersion"
               ]
            ]
         }
      ]
   },
   "Service":"testService",
   "functionVersion":"$LATEST",
   "Time":100.5
}
 

User experience

using AWS.Lambda.Powertools.Metrics;

public class Function {

  [Metrics(Namespace = "ExampleApplication", Service = "Booking")]
  public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
  {
    // Publish a metric with standard resolution i.e. StorageResolution = 60
    Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count, MetricResolution.Standard);

    // Publish a metric with high resolution i.e. StorageResolution = 1
    Metrics.AddMetric("FailedBooking", 1, MetricUnit.Count, MetricResolution.High);

    // The last parameter (storage resolution) is optional
    Metrics.AddMetric("SuccessfulUpgrade", 1, MetricUnit.Count);
  }
}

When method is called without MetricsResolution parameter it will default to not sending StorageResolution.

2023-04-26T15:07:43.552Z	49e1f9a4-9b00-4462-b111-478fcd8ceffa	info	{
    "_aws": {
        "Timestamp": 1682521663552,
        "CloudWatchMetrics": [
            {
                "Namespace": "ServerlessGreeting",
                "Metrics": [
                    {
                        "Name": "SuccessfulBooking",
                        "Unit": "Count",
                        "StorageResolution": 60
                    },
                    {
                        "Name": "FailedBooking",
                        "Unit": "Count",
                        "StorageResolution": 1
                    },
                    {
                        "Name": "SuccessfulUpgrade",
                        "Unit": "Count"
                    }
                ],
                "Dimensions": [
                    [
                        "Service"
                    ]
                ]
            }
        ]
    },
    "Service": "ServerlessGreeting",
    "GetGreeting_Invocations": 1,
    "High": 1
}

🌟New features and non-breaking changes

• feat: Support for High resolution metrics (#226) by @hjgraca

This release was made possible by the following contributors:

@hjgraca

1.1.0

Changes

In this release we introduced telemetry for Powertools user-agent for Lambda Execution Environment.
This will allow us to have visibility on Powertools invocations.

🌟New features and non-breaking changes

• feat: Powertools User-Agent for Lambda execution environment (#246) by @hjgraca

🔧 Maintenance

• chore(governance): add Lambda Powertools for Python in issue templates (#251) by @leandrodamascena
• chore(ci): add workflow to dispatch analytics fetching (#248) by @rubenfonseca
• update changelog with latest changes (#241) by @hjgraca
• update pipeline to create a new branch instead of push (#237) by @hjgraca
• fix: Update NuGet references for examples (#235) by @amirkaws

This release was made possible by the following contributors:

@amirkaws, @hjgraca, @leandrodamascena, @rubenfonseca and Release bot

v1.0.1

Changes

In this minor release we have addressed a bug in the Tracing utility that when an exception was thrown the Tracing utility would override the error and throw a InvalidOperationException instead of the correct exception.

We have also improved the documentation for Metrics utility, there was wrong casing in the examples. Thanks @srcsakthivel

Finally there was maintenance work done on the NuGet references for examples and changelog. Changelog still in progress and will be fixed soon.

🐛 Bug and hot fixes

• Fix Tracing when exception is thrown. Prevent Tracing from throwing InvalidOperationException (#223) by @hjgraca

🔧 Maintenance

• chore : add changelog to makefile (#227) by @hjgraca
• chore: Bump versions for release v1.0.1 (#232) by @amirkaws
• fix: update NuGet references for examples (#218) by @amirkaws
• chore(docs) - Metrics doc updates (#225) by @srcsakthivel

This release was made possible by the following contributors:

@amirkaws, @hjgraca, @sliedig and @srcsakthivel

v1.0.0

With this release, we move from release candidate to General Availability 🎉🎉🎉!

This means APIs for the core utilities Tracing, Logging, and Metrics are now stable and they are ready to be used in AWS Lambda functions written in .NET 6 running in production.

Quick links: 📜 Documentation | NuGet | Roadmap | Examples

Logging

Key features

• Capture key fields from Lambda context, cold start and structures logging output as JSON
• Log Lambda event when instructed (disabled by default)
• Log sampling enables DEBUG log level for a percentage of requests (disabled by default)
• Append additional keys to structured log at any point in time

For more information see Logging documentation.

Metrics

Key features

• Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
• Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)
• Metrics are created asynchronously by CloudWatch service, no custom stacks needed
• Context manager to create a one off metric with a different dimension

For more information see Metrics documentation.

Tracing

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

For more information see Tracing documentation.

Special thank you

We'd like to extend our gratitude to the following people who helped with contributions, feedbacks, and their opinions while we were in developer preview:
@heitorlessa, @t1agob, @sthuber90, @nCubed, @kenfdev, @msimpsonnz, and @pgrm

v0.0.2-preview

What's Changed

• fix: custom exception JSON converter (#152) by @amirkaws
• fix: updated logger casing env vars in samples (#173) by @sliedig
• chore: updated NuGet packages (#172) by @sliedig

📜 Documentation updates

• docs: fix documentation links (#147) by @amirkaws
• docs: add discord invitation link (#155) by @sthuber90
• fix: some grammar; update links to example projects. (#170) by @nCubed
• docs: typo in metrics README (#157) by @kenfdev
• docs: updated documentation (#175) by @sliedig

This release was made possible by the following contributors:

@amirkaws, @sliedig, @sthuber90, @nCubed and @kenfdev

v0.0.1-preview.1

Summary

Introducing AWS Lambda Powertools for .NET, a suite of utilities for AWS Lambda functions running on the .NET 6 runtime, to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.

⚠️ Do not use this library for production workloads. ⚠️
AWS Lambda Powertools for .NET is currently released in preview and is intended strictly for feedback purposes only.
This version is not stable, and significant breaking changes might incur as part of the upcoming production-ready release.

--

Quick links: 📜 Documentation | ⬇️ NuGet | 💬 Feature request | 🐛 Bug Report | ⚡️Examples

Logger

🤩 Key features 🤩

• Capture key fields from Lambda context, cold start and structures logging output as JSON
• Log Lambda event when instructed (disabled by default)
• Log sampling enables DEBUG log level for a percentage of requests (disabled by default)
• Append additional keys to structured log at any point in time

Metrics

🤩 Key features 🤩

• Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
• Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)
• Metrics are created asynchronously by CloudWatch service, no custom stacks needed
• Context manager to create a one off metric with a different dimension

Tracer

🤩 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

This release was made possible by the following contributors:

@sliedig , @amirkaws , @t1agob, @heitorlessa

Credits

Credits for the Lambda Powertools idea go to DAZN with their DAZN Lambda Powertools.