Description
Lambda Structured Logging Support
Status (September 5th, 2024)
Version 1.11.0 of Amazon.Lambda.RuntimeSupport and 2.3.0 of Amazon.Lambda.Core have been released with structured logging support. Lambda functions as .NET class libraries requiring the managed runtime to be updated with the new version of Amazon.Lambda.RuntimeSupport which is pending a deployment. Executable Lambda functions can get started with structured logging support but need to add <EnablePreviewFeatures>true</EnablePreviewFeatures> to the csproj file to access the new parameterized logging API in Amazon.Lambda.Core. Once the .NET managed runtime has been update a new version of Amazon.Lambda.Core will be release removing the preview flag for the logging APIs.
The new logging APIs
As part of the effort to support JSON logging, new parameterized logging methods have been added to Amazon.Lambda.Core. These new APIs are the ones marked as preview, requiring the EnablePreviewFeatures property to be set. This will be required until the new version of Amazon.Lambda.RuntimeSupport has been deployed to the managed runtime for class-library-based Lambda functions. These new logging APIs will also function for the existing Text logging mode providing the string replacement.
The following code shows the handler in the project using the parameterized logging to log the input property.
var handler = (string input, ILambdaContext context) =>
{
context.Logger.LogInformation("The input provided is: {input}", input);
return input.ToUpper();
};The parameterized logging statement will produce the following JSON, adding the parameters to the log statement as properties of the JSON logging.
{
"timestamp": "2024-04-26T00:40:04.236Z",
"level": "Information",
"requestId": "6ebb975f-b9fb-41e9-81f5-ab96586fb42e",
"traceId": "Root=1-662af7e3-7076fd596550114013d8cd03;Parent=69ab02fe14dc7380;Sampled=0;Lineage=09ad9508:0",
"message": "The input provided is: hello",
"input": "hello"
}Following the pattern of other logging libraries, exceptions can also be passed in for logging. For example, the following code will throw an exception if the input is equal to “fail”.
var handler = (string input, ILambdaContext context) =>
{
context.Logger.LogInformation("The input provided is: {input}", input);
if (input == "fail")
{
try
{
throw new ApplicationException("You forced a failure");
}
catch(Exception ex)
{
context.Logger.LogError(ex, "An error has happened with input {input}", input);
}
}
return input.ToUpper();
};
This produces the following JSON.
{
"timestamp": "2024-04-26T00:58:51.554Z",
"level": "Error",
"requestId": "1f8da9f0-7914-47c7-a129-e3974bba879e",
"traceId": "Root=1-662afc4b-2b74361610fca0584cd2a46e;Parent=40bb090170fa2442;Sampled=0;Lineage=09ad9508:0",
"message": "An error has happened with input fail",
"input": "fail",
"errorType": "System.ApplicationException",
"errorMessage": "You forced a failure",
"stackTrace": [
"System.ApplicationException: You forced a failure",
"at Program.<>c.<<Main>$>b__0_0(String input, ILambdaContext context) in C:\\Temp\\DotNetJsonLoggingPreview\\src\\DotNetJsonLoggingPreview\\Function.cs:line 14"
]
}Serialization options
Formatting scalers: When using scalars like integers and doubles as logging parameters, the format can be customized by providing a format string using a suffix on the parameter name. For example,
var handler = (string input, ILambdaContext context) =>
{
...
double cost = 8.12345;
context.Logger.LogInformation("The cost is {cost:0.00}", cost);
...
}
The string after the colon in {cost:0.00} is the same as the formatString used in .NET’s composite formatting. The code above produces the following JSON logging statement.
{
"timestamp": "2024-05-07T21:30:47.157Z",
"level": "Information",
"requestId": "4ce09890-4c13-41eb-8d62-9a6c90e10e5b",
"traceId": "Root=1-663a9d86-530f9b9c5db0148471607964;Parent=480ce27c09876e32;Sampled=0;Lineage=cd25c10f:0",
"message": "The cost is 8.12",
"cost": "8.12"
}Custom types: When using instances of custom types as parameters to logging, the ToString method is used as the value for the property. If the @ prefix is used, the object will be serialized into the JSON logging statement. For example, the code below:
var handler = (string input, ILambdaContext context) =>
{
...
var user = new User {FirstName = "Norm", LastName = "Johanson"};
context.Logger.LogInformation("User {@user} logged in", user);
...
}
...
public class User
{
public string FirstName { get; set; }
public string LastName { get; set; }
}Produce the following JSON document:
{
"timestamp": "2023-09-07T01:30:06.977Z",
"level": "Information",
"requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
"traceId": "1-6408af34-50f56f5b5677a7d763973804",
"message": "User {@user} logged in",
"user":
{
"FirstName": "Norm",
"LastName": "Johanson"
}
}Collections: When using lists and dictionaries as parameters, the items in the collections are written to the JSON log using the ToString method. The @ prefix can be used to indicate that the items should be serialized into the JSON log message.
Example JSON using ToString:
{
"timestamp": "2023-09-07T01:30:06.977Z",
"level": "Information",
"requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
"traceId": "1-6408af34-50f56f5b5677a7d763973804",
"message": "Request {metrics}",
"metrics":
{
"Requests" : "50rpm",
"Latency" : "145.1ms"
}
}Example JSON using serialization:
{
"timestamp": "2023-09-07T01:30:06.977Z",
"level": "Information",
"requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
"traceId": "1-6408af34-50f56f5b5677a7d763973804",
"message": "Request {@metrics}",
"metrics":
{
"Requests" :
{
"Value": 50,
"Unit": "rpm"
}
"Latency" :
{
"Value": 145.1,
"Unit": "ms"
}
}
}