raulnq
Enhance AWS Lambda Functions using Powertools for .NET

Enhance AWS Lambda Functions using Powertools for .NET

Raul Naupari's photo
Raul Naupari
·

5 min read

Table of contents

The increasing complexity of serverless applications demands an efficient way to manage and maintain their components. AWS Lambda Powertools offers a suite of utilities designed to simplify the development process, enhance observability, and implement best practices for building serverless applications. By leveraging these tools, developers can focus on their application's core functionality while enjoying the benefits of a streamlined and optimized infrastructure. AWS Lambda Powertools provides three main features:

  • Logging: Offers structured logs.

  • Tracing: Supplies a straightforward way for sending traces to AWS X-Ray.

  • Metrics: Provides an easy way to collect custom metrics.

Pre-requisites

  • Ensure you have an IAM User with programmatic access.

  • Install the Amazon Lambda Templates with this command: dotnet new -i Amazon.Lambda.Templates

  • Install the Amazon Lambda Tools with this command: dotnet tool install -g Amazon.Lambda.Tools

  • Install the AWS SAM CLI.

The Lambda Function

Run the following commands to create a Lambda function:

dotnet new lambda.EmptyFunction -n HelloWorldApi -o .
dotnet add src/HelloWorldApi package Amazon.Lambda.APIGatewayEvents
dotnet new sln -n AwsPowertools
dotnet sln add --in-root src/HelloWorldApi

Open the solution, navigate to the HelloWorldApi project, and update the Function.cs file as follows:

using Amazon.Lambda.APIGatewayEvents;
using Amazon.Lambda.Core;

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace HelloWorldApi
{
    public class Function
    {
        public async Task<APIGatewayHttpApiV2ProxyResponse> FunctionHandler(APIGatewayHttpApiV2ProxyRequest input, ILambdaContext context)
        {
            var key = await KeyGenerator();
            return new APIGatewayHttpApiV2ProxyResponse
            {
                Body = $@"{{""Message"":""This is your key {key}""}}",
                StatusCode = 200,
                Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
            };
        }

        private async Task<string> KeyGenerator()
        {
            await Task.Delay(Random.Shared.Next(2000));
            return Guid.NewGuid().ToString();
        }
    }
}

Create a template.yml file (AWS SAM) with the following content:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  AWS PowerTools

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Timeout: 60
      MemorySize: 512
      Tracing: Active
      Runtime: dotnet6
      Architectures:
        - x86_64    
      Handler: HelloWorldApi::HelloWorldApi.Function::FunctionHandler
      CodeUri: ./src/HelloWorldApi/
      Events:
        ListPosts:
          Type: Api
          Properties:
            Path: /
            Method: get

Run sam build and sam deploy --guided and follow the instructions to deploy the Lambda function.

Logging

To add the Powertools logging library to your project, execute the following command:

dotnet add src/HelloWorldApi package AWS.Lambda.Powertools.Logging

Add the following section in the template.yml file:

Globals:
  Function:
    Environment:
      Variables:
        POWERTOOLS_SERVICE_NAME: myfunction
        POWERTOOLS_LOG_LEVEL: Debug

The complete list of environment variables (each of which can be set at the code level using the Logging attribute) is as follows:

  • POWERTOOLS_SERVICE_NAME: Sets service name used for tracing namespace, metrics dimension, and structured logging.

  • POWERTOOLS_LOG_LEVEL: Sets logging level(Trace, Debug, Information, Warning, Error, Critical, None).

  • POWERTOOLS_LOGGER_CASE: Override the default casing(CamelCase, PascalCase, SnakeCase) for log keys.

  • POWERTOOLS_LOGGER_LOG_EVENT: Logs incoming event.

  • POWERTOOLS_LOGGER_SAMPLE_RATE: Debug log sampling.

Modify the FunctionHandler implementation as follows:

[Logging(LogEvent = true)]
public async Task<APIGatewayHttpApiV2ProxyResponse> FunctionHandler(APIGatewayHttpApiV2ProxyRequest input, ILambdaContext context)
{
    Logger.LogInformation("Generating a new key");
    var key = await KeyGenerator();
    Logger.LogInformation(new Dictionary<string, object>() { { "Key", key } },"New key generated");
    return new APIGatewayHttpApiV2ProxyResponse
    {
        Body = $@"{{""Message"":""This is your key {key}""}}",
        StatusCode = 200,
        Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
    };
}

  • The Logging attribute instructs the function to log the incoming event (when the LogEvent property is true).

  • Logger.LogInformation("Generating a new key") logs a simple message.

  • Logger.LogInformation(new Dictionary<string, object>() { { "Key", key } },"New key generated") logs a message with properties.

Deploy the function to view outputs such as:

{
    "cold_start": false,
    "xray_trace_id": "1-648fbb32-7935059f75c9ef6705c24cb0",
    "function_name": "awspowertools-MyFunction-3wYZWUsiQxv5",
    "function_version": "$LATEST",
    "function_memory_size": 512,
    "function_arn": "arn:aws:lambda:us-east-2:020000000000:function:awspowertools-MyFunction-3wYZWUsiQxv5",
    "function_request_id": "d833025d-8aa3-4766-9738-e5be283c233a",
    "key": "0eb5d295-d646-4ba9-be06-22db05504836",
    "timestamp": "2023-06-19T02:19:30.8281371Z",
    "level": "Information",
    "service": "myfunction",
    "name": "AWS.Lambda.Powertools.Logging.Logger",
    "message": "New key generated"
}

With structured logs, we can perform searches on this structured data using CloudWatch Logs Insights:

For more information, please refer to the official documentation here.

Tracing

To add the Powertools tracing library (wrapper for AWS X-Ray SDK for .NET) to your project, run the following command:

dotnet nuget add AWS.Lambda.Powertools.Tracing

Ensure that the Tracing property is activated for your AWS::Serverless::Function resource. Like the logging library, there are a set of environment variables (each of which can be set at the code level using the Tracing attribute) that we can use:

  • POWERTOOLS_SERVICE_NAME: Sets service name used for tracing namespace, metrics dimension, and structured logging.

  • POWERTOOLS_TRACE_DISABLED: Disables tracing.

  • POWERTOOLS_TRACER_CAPTURE_RESPONSE: Captures Lambda or method return as metadata.

  • POWERTOOLS_TRACER_CAPTURE_ERROR: Captures Lambda or method exception as metadata.

Update the template.yml file as follows:

Globals:
  Function:
    Environment:
      Variables:
        POWERTOOLS_SERVICE_NAME: myfunction
        POWERTOOLS_LOG_LEVEL: Debug
        POWERTOOLS_TRACER_CAPTURE_RESPONSE: true
        POWERTOOLS_TRACER_CAPTURE_ERROR: true

To enable PowerTools tracing for our function, add the Tracing attribute to our FunctionHandler method or to any other method:

[Logging(LogEvent = true)]
[Tracing]
public async Task<APIGatewayHttpApiV2ProxyResponse> FunctionHandler(APIGatewayHttpApiV2ProxyRequest input, ILambdaContext context)
{
    Logger.LogInformation("Generating a new key");
    var key = await KeyGenerator();
    Logger.LogInformation(new Dictionary<string, object>() { { "Key", key } }, "New key generated");
    return new APIGatewayHttpApiV2ProxyResponse
    {
        Body = $@"{{""Message"":""This is your key {key}""}}",
        StatusCode = 200,
        Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
    };
}

[Tracing(SegmentName = "Key generator service")]
private async Task<string> KeyGenerator()
{
    await Task.Delay(Random.Shared.Next(2000));
    return Guid.NewGuid().ToString();
}

Deploy the function, then navigate to AWS X-Ray traces to view the results:

We can instrument all our AWS SDK for .NET clients by calling AWSSDKHandler.RegisterXRayForAllServices() at the constructor level.

For more information, please refer to the official documentation here.

Metrics

To add the Powertools metrics library to your project, execute the following command:

dotnet nuget add AWS.Lambda.Powertools.Metrics

The metrics utility generates custom metrics asynchronously by logging metrics to standard output using the Amazon CloudWatch Embedded Metric Format (EMF). The set of environment variables (each of which can be set at the code level using the Metrics attribute) we can use are:

  • POWERTOOLS_SERVICE_NAME: Sets service name used for tracing namespace, metrics dimension, and structured logging.

  • POWERTOOLS_METRICS_NAMESPACE: Sets namespace used for metrics.

Update the template.yml file as follows:

Globals:
  Function:
    Environment:
      Variables:
        POWERTOOLS_SERVICE_NAME: myfunction
        POWERTOOLS_LOG_LEVEL: Debug
        POWERTOOLS_TRACER_CAPTURE_RESPONSE: true
        POWERTOOLS_TRACER_CAPTURE_ERROR: true
        POWERTOOLS_METRICS_NAMESPACE: mymetrics

Modify the FunctionHandler implementation as follows:

[Logging(LogEvent = true)]
[Metrics]
[Tracing]
public async Task<APIGatewayHttpApiV2ProxyResponse> FunctionHandler(APIGatewayHttpApiV2ProxyRequest input, ILambdaContext context)
{
    Logger.LogInformation("Generating a new key");
    var key = await KeyGenerator();
    Logger.LogInformation(new Dictionary<string, object>() { { "Key", key } }, "New key generated");
    Metrics.AddMetric("SuccessfulKeyGeneration", 1, MetricUnit.Count);
    return new APIGatewayHttpApiV2ProxyResponse
    {
        Body = $@"{{""Message"":""This is your key {key}""}}",
        StatusCode = 200,
        Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
    };
}

Deploy the function, then navigate to CloudWatch metrics to view the results:

For more information, please refer to the official documentation here.

Conclusion

AWS Lambda Powertools for .NET is a collection of utilities that simplifies serverless application development. By using its logging, tracing, and metrics features, developers can concentrate on their application's core functionality. All the code is available here. Thanks, and happy coding.

.NETAWSaws lambdaAWS Powertools