Releases: aws-powertools/powertools-lambda-dotnet
1.6.0
Summary
With this release, we move Parameters utility from Developer Preview to General Availability 🎉🎉🎉!, we also released Tracing automatic register for services.
Parameters
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. Here is an example for SSM Parameter Store.
using AWS.Lambda.Powertools.Parameters;
using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement;
public class Function
{
public async Task<APIGatewayProxyResponse> FunctionHandler
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
// Get SSM Provider instance
ISsmProvider ssmProvider = ParametersManager.SsmProvider;
// Retrieve a single parameter
string? value = await ssmProvider
.GetAsync("/my/parameter")
.ConfigureAwait(false);
// Retrieve multiple parameters from a path prefix
// This returns a Dictionary with the parameter name as key
IDictionary<string, string?> values = await ssmProvider
.GetMultipleAsync("/my/path/prefix")
.ConfigureAwait(false);
}
}Instrumenting SDK clients and HTTP calls
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using AWS.Lambda.Powertools.Tracing;
public class Function
{
private static IAmazonDynamoDB _dynamoDb;
/// <summary>
/// Function constructor
/// </summary>
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.
public class Function
{
private static IAmazonDynamoDB _dynamoDb;
/// <summary>
/// Function constructor
/// </summary>
public Function()
{
Tracing.Register<IAmazonDynamoDB>()
_dynamoDb = new AmazonDynamoDBClient();
}
}Changes
🌟New features and non-breaking changes
📜 Documentation updates
- feat: Automatic Register XRay for all services (#428) by @amirkaws
- chore: include mermaid in mkdocs config. Fix identation and line numbers idempotency (#400) by @hjgraca
🔧 Maintenance
- chore: Update version release 1.6.0 (#430) by @amirkaws
- chore: include mermaid in mkdocs config. Fix identation and line numbers idempotency (#400) by @hjgraca
- chore: Update dependabot.yml (#391) by @hjgraca
This release was made possible by the following contributors:
Contributors
Assets 2
1.5.0
Summary
In this release we are happy to add support for Idempotency InProgressExpiration timestamp.
This field is required to prevent against extended failed retries when a Lambda function times out, Powertools for AWS Lambda (.NET) calculates and includes the remaining invocation available time as part of the idempotency record.
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, expire_seconds field elapsed).
This means that if an invocation expired during execution, it will be quickly executed again on the next retry.
When decorating the handler with Idempotent attribute we will do it automatically by getting the RemainingTime value from the ILambdaContext that is passed to the handler.
RemainingTime is the remaining execution time till the function will be terminated. At the time you create the Lambda function you set maximum time limit, at which time AWS Lambda will terminate the function execution.
Information about the remaining time of function execution can be used to specify function behavior when nearing the timeout.
When using 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:
Lambda request timeout diagram
Changes
🌟New features and non-breaking changes
- feat: Idempotency calculate remaining invocation available time as part of the idempotency record (#363) by @hjgraca
📜 Documentation updates
- feat: Idempotency calculate remaining invocation available time as part of the idempotency record (#363) by @hjgraca
This release was made possible by the following contributors:
Contributors
Assets 2
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.UseFormatteron 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
🐛 Bug and hot fixes
🔧 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:
Contributors
Assets 2
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
Contributors
Assets 2
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.
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
Contributors
Assets 2
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.
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:
Contributors
Assets 2
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
This release was made possible by the following contributors:
Contributors
Assets 2
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
🔧 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
Contributors
Assets 2
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:
Contributors
Assets 2
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
