feat: Add bring your own log formatter to logger

[amirkaws]

Issue number: #366

Summary

This PR allows users to being their own log formatter

Changes

No changes to exiting functionalities only adding a new feature.

User experience

    /**
     * Handler for requests to Lambda function.
     */
    public class Function
    {
        /// <summary>
        /// Function constructor
        /// </summary>
        public Function()
        {
            Logger.UseFormatter(new CustomLogFormatter());
        }

        [Logging(CorrelationIdPath = "/headers/my_request_id_header", SamplingRate = 0.7)]
        public async Task<APIGatewayProxyResponse> FunctionHandler
            (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
        {
            ...
        }
    }

CustomLogFormatter implementation

    public class CustomLogFormatter : ILogFormatter
    {
        public object FormatLogEntry(LogEntry logEntry)
        {
            return new
            {
                Message = logEntry.Message,
                Service = logEntry.Service,
                CorrelationIds = new 
                {
                    AwsRequestId = logEntry.LambdaContext?.AwsRequestId,
                    XRayTraceId = logEntry.XRayTraceId,
                    CorrelationId = logEntry.CorrelationId
                },
                LambdaFunction = new
                {
                    Name = logEntry.LambdaContext?.FunctionName,
                    Arn = logEntry.LambdaContext?.InvokedFunctionArn,
                    MemoryLimitInMB = logEntry.LambdaContext?.MemoryLimitInMB,
                    Version = logEntry.LambdaContext?.FunctionVersion,
                    ColdStart = logEntry.ColdStart,
                },
                Level = logEntry.Level.ToString(),
                Timestamp = logEntry.Timestamp.ToString("o"),
                Logger = new
                {
                    Name = logEntry.Name,
                    SampleRate = logEntry.SamplingRate
                },
            };
        }
    }

Example CloudWatch Logs excerpt

    {
        "Message": "Test Message",
        "Service": "lambda-example",
        "CorrelationIds": {
            "AwsRequestId": "52fdfc07-2182-154f-163f-5f0f9a621d72",
            "XRayTraceId": "1-61b7add4-66532bb81441e1b060389429",
            "CorrelationId": "correlation_id_value"
        },
        "LambdaFunction": {
            "Name": "test",
            "Arn": "arn:aws:lambda:eu-west-1:12345678910:function:test",
            "MemorySize": 128,
            "Version": "$LATEST",
            "ColdStart": true
        },
        "Level": "Information",
        "Timestamp": "2021-12-13T20:32:22.5774262Z",
        "Logger": {
            "Name": "AWS.Lambda.Powertools.Logging.Logger",
            "SampleRate": 0.7
        }
    }

Checklist

Please leave checklist items unchecked if they do not apply to your change.

• Meets tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[hjgraca]

In what scenarios can logObject be null?

[amirkaws]

if custom formatter implemented by user for any reason returns null as output.

[hjgraca]

don't think is possible at runtime to have an empty or null key for dictionary, this could be simplified with logEntry.ExtraKeys = new Dictionary<string, string>(extraKeys);

[amirkaws]

It cannot, I can remove the null check but is's an append to the existing dictionary, so cannot be replaced.

[amirkaws]

I have replaced it with a new throw new LogFormatException (custom exception)

[hjgraca]

In here we are changing the premise that what is logged should be exactly what is returned from the formatter.

[amirkaws]

We don't change the object returning from formatter and we log it as is. This is not for the object returned from the formatter, it's for creating an LogEntry to pass it to the formatter.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
12 Code Smells

No Coverage information
0.0% Duplication

[hjgraca]

GTM. Great work Amir. I think there is room for improving the code in the future, specifically in PowertoolsLogger line 300 to line 330, those loops and checks could be improved.