Skip to content

Commit 9220445

Browse files
hjgracahjgraca
authored
docs(logging): extract inline code examples into snippet files (#1199)
1 parent 23b6e68 commit 9220445

17 files changed

Lines changed: 962 additions & 739 deletions

‎docs/core/logging.md‎

Lines changed: 62 additions & 739 deletions
Large diffs are not rendered by default.

‎docs/snippets/logging/AdvancedConfiguration.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:json_serializer_options]
7+
builder.Logging.AddPowertoolsLogger(options =>
8+
{
9+
options.JsonOptions = new JsonSerializerOptions
10+
{
11+
DictionaryKeyPolicy = JsonNamingPolicy.CamelCase, // Override output casing
12+
TypeInfoResolver = MyCustomJsonSerializerContext.Default // Your custom JsonSerializerContext
13+
};
14+
});
15+
// --8<-- [end:json_serializer_options]
16+
17+
// --8<-- [start:clear_providers]
18+
builder.Logging.AddPowertoolsLogger(config =>
19+
{
20+
config.Service = "TestService";
21+
config.LoggerOutputCase = LoggerOutputCase.PascalCase;
22+
}, clearExistingProviders: true);
23+
// --8<-- [end:clear_providers]

‎docs/snippets/logging/AotSupport.cs‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:json_serializer_options_aot]
7+
Logger.Configure(logger =>
8+
{
9+
logger.JsonOptions = new JsonSerializerOptions
10+
{
11+
TypeInfoResolver = YourJsonSerializerContext.Default
12+
};
13+
});
14+
// --8<-- [end:json_serializer_options_aot]
15+
16+
// --8<-- [start:before_aot]
17+
Func<APIGatewayHttpApiV2ProxyRequest, ILambdaContext, Task<APIGatewayHttpApiV2ProxyResponse>> handler = FunctionHandler;
18+
await LambdaBootstrapBuilder.Create(handler, new SourceGeneratorLambdaJsonSerializer<MyCustomJsonSerializerContext>())
19+
.Build()
20+
.RunAsync();
21+
// --8<-- [end:before_aot]
22+
23+
// --8<-- [start:after_aot]
24+
Func<APIGatewayHttpApiV2ProxyRequest, ILambdaContext, Task<APIGatewayHttpApiV2ProxyResponse>> handler = FunctionHandler;
25+
await LambdaBootstrapBuilder.Create(handler, new PowertoolsSourceGeneratorSerializer<MyCustomJsonSerializerContext>())
26+
.Build()
27+
.RunAsync();
28+
// --8<-- [end:after_aot]
29+
30+
// --8<-- [start:demo_class]
31+
public class Demo
32+
{
33+
public string Name { get; set; }
34+
public Headers Headers { get; set; }
35+
}
36+
// --8<-- [end:demo_class]
37+
38+
// --8<-- [start:json_serializer_context]
39+
[JsonSerializable(typeof(APIGatewayHttpApiV2ProxyRequest))]
40+
[JsonSerializable(typeof(APIGatewayHttpApiV2ProxyResponse))]
41+
[JsonSerializable(typeof(Demo))]
42+
public partial class MyCustomJsonSerializerContext : JsonSerializerContext
43+
{
44+
}
45+
// --8<-- [end:json_serializer_context]
46+
47+
// --8<-- [start:custom_log_formatter_aot_function]
48+
49+
Func<APIGatewayHttpApiV2ProxyRequest, ILambdaContext, Task<APIGatewayHttpApiV2ProxyResponse>> handler = FunctionHandler;
50+
await LambdaBootstrapBuilder.Create(handler,
51+
new PowertoolsSourceGeneratorSerializer<LambdaFunctionJsonSerializerContext>
52+
(
53+
new CustomLogFormatter()
54+
)
55+
)
56+
.Build()
57+
.RunAsync();
58+
59+
// --8<-- [end:custom_log_formatter_aot_function]
60+
61+
// --8<-- [start:custom_log_formatter_aot_class]
62+
public class CustomLogFormatter : ILogFormatter
63+
{
64+
public object FormatLogEntry(LogEntry logEntry)
65+
{
66+
return new
67+
{
68+
Message = logEntry.Message,
69+
Service = logEntry.Service,
70+
CorrelationIds = new
71+
{
72+
AwsRequestId = logEntry.LambdaContext?.AwsRequestId,
73+
XRayTraceId = logEntry.XRayTraceId,
74+
CorrelationId = logEntry.CorrelationId
75+
},
76+
LambdaFunction = new
77+
{
78+
Name = logEntry.LambdaContext?.FunctionName,
79+
Arn = logEntry.LambdaContext?.InvokedFunctionArn,
80+
MemoryLimitInMB = logEntry.LambdaContext?.MemoryLimitInMB,
81+
Version = logEntry.LambdaContext?.FunctionVersion,
82+
ColdStart = logEntry.ColdStart,
83+
},
84+
Level = logEntry.Level.ToString(),
85+
Timestamp = logEntry.Timestamp.ToString("o"),
86+
Logger = new
87+
{
88+
Name = logEntry.Name,
89+
SampleRate = logEntry.SamplingRate
90+
},
91+
};
92+
}
93+
}
94+
// --8<-- [end:custom_log_formatter_aot_class]

‎docs/snippets/logging/AppendingKeys.cs‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:append_keys]
7+
/**
8+
* Handler for requests to Lambda function.
9+
*/
10+
public class Function
11+
{
12+
[Logging(LogEvent = true)]
13+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigwProxyEvent,
14+
ILambdaContext context)
15+
{
16+
var requestContextRequestId = apigwProxyEvent.RequestContext.RequestId;
17+
18+
var lookupInfo = new Dictionary<string, object>()
19+
{
20+
{"LookupInfo", new Dictionary<string, object>{{ "LookupId", requestContextRequestId }}}
21+
};
22+
23+
// Appended keys are added to all subsequent log entries in the current execution.
24+
// Call this method as early as possible in the Lambda handler.
25+
// Typically this is value would be passed into the function via the event.
26+
// Set the ClearState = true to force the removal of keys across invocations,
27+
Logger.AppendKeys(lookupInfo);
28+
29+
Logger.LogInformation("Getting ip address from external service");
30+
31+
}
32+
// --8<-- [end:append_keys]
33+
34+
// --8<-- [start:remove_keys]
35+
/**
36+
* Handler for requests to Lambda function.
37+
*/
38+
public class Function
39+
{
40+
[Logging(LogEvent = true)]
41+
public async Task<APIGatewayProxyResponse> FunctionHandler
42+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
43+
{
44+
...
45+
Logger.AppendKey("test", "willBeLogged");
46+
...
47+
var customKeys = new Dictionary<string, string>
48+
{
49+
{"test1", "value1"},
50+
{"test2", "value2"}
51+
};
52+
53+
Logger.AppendKeys(customKeys);
54+
...
55+
Logger.RemoveKeys("test");
56+
Logger.RemoveKeys("test1", "test2");
57+
...
58+
}
59+
}
60+
// --8<-- [end:remove_keys]

‎docs/snippets/logging/ClearState.cs‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:clear_state]
7+
/**
8+
* Handler for requests to Lambda function.
9+
*/
10+
public class Function
11+
{
12+
[Logging(ClearState = true)]
13+
public async Task<APIGatewayProxyResponse> FunctionHandler
14+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
15+
{
16+
...
17+
if (apigProxyEvent.Headers.ContainsKey("SomeSpecialHeader"))
18+
{
19+
Logger.AppendKey("SpecialKey", "value");
20+
}
21+
22+
Logger.LogInformation("Collecting payment");
23+
...
24+
}
25+
}
26+
// --8<-- [end:clear_state]

‎docs/snippets/logging/Configuration.cs‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:configure_static_logger]
7+
public class Function
8+
{
9+
public Function()
10+
{
11+
Logger.Configure(options =>
12+
{
13+
options.MinimumLogLevel = LogLevel.Information;
14+
options.LoggerOutputCase = LoggerOutputCase.CamelCase;
15+
});
16+
}
17+
18+
public async Task<APIGatewayProxyResponse> FunctionHandler
19+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
20+
{
21+
Logger.LogInformation("Collecting payment");
22+
...
23+
}
24+
}
25+
// --8<-- [end:configure_static_logger]
26+
27+
// --8<-- [start:configure_ilogger]
28+
public class Function
29+
{
30+
public Function(ILogger logger)
31+
{
32+
_logger = logger ?? LoggerFactory.Create(builder =>
33+
{
34+
builder.AddPowertoolsLogger(config =>
35+
{
36+
config.Service = "TestService";
37+
config.LoggerOutputCase = LoggerOutputCase.PascalCase;
38+
});
39+
}).CreatePowertoolsLogger();
40+
}
41+
42+
public async Task<APIGatewayProxyResponse> FunctionHandler
43+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
44+
{
45+
Logger.LogInformation("Collecting payment");
46+
...
47+
}
48+
}
49+
// --8<-- [end:configure_ilogger]

‎docs/snippets/logging/CorrelationId.cs‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:correlation_id_custom]
7+
/**
8+
* Handler for requests to Lambda function.
9+
*/
10+
public class Function
11+
{
12+
[Logging(CorrelationIdPath = "/headers/my_request_id_header")]
13+
public async Task<APIGatewayProxyResponse> FunctionHandler
14+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
15+
{
16+
...
17+
}
18+
}
19+
// --8<-- [end:correlation_id_custom]
20+
21+
// --8<-- [start:correlation_id_builtin]
22+
/**
23+
* Handler for requests to Lambda function.
24+
*/
25+
public class Function
26+
{
27+
[Logging(CorrelationIdPath = CorrelationIdPaths.ApiGatewayRest)]
28+
public async Task<APIGatewayProxyResponse> FunctionHandler
29+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
30+
{
31+
...
32+
}
33+
}
34+
// --8<-- [end:correlation_id_builtin]

‎docs/snippets/logging/CustomLogFormatter.cs‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// This file is referenced by docs/core/logging.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Logging;
5+
6+
// --8<-- [start:custom_log_formatter_function]
7+
/**
8+
* Handler for requests to Lambda function.
9+
*/
10+
public class Function
11+
{
12+
/// <summary>
13+
/// Function constructor
14+
/// </summary>
15+
public Function()
16+
{
17+
Logger.Configure(options =>
18+
{
19+
options.LogFormatter = new CustomLogFormatter();
20+
});
21+
}
22+
23+
[Logging(CorrelationIdPath = "/headers/my_request_id_header", SamplingRate = 0.7)]
24+
public async Task<APIGatewayProxyResponse> FunctionHandler
25+
(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
26+
{
27+
...
28+
}
29+
}
30+
// --8<-- [end:custom_log_formatter_function]
31+
32+
// --8<-- [start:custom_log_formatter_class]
33+
public class CustomLogFormatter : ILogFormatter
34+
{
35+
public object FormatLogEntry(LogEntry logEntry)
36+
{
37+
return new
38+
{
39+
Message = logEntry.Message,
40+
Service = logEntry.Service,
41+
CorrelationIds = new
42+
{
43+
AwsRequestId = logEntry.LambdaContext?.AwsRequestId,
44+
XRayTraceId = logEntry.XRayTraceId,
45+
CorrelationId = logEntry.CorrelationId
46+
},
47+
LambdaFunction = new
48+
{
49+
Name = logEntry.LambdaContext?.FunctionName,
50+
Arn = logEntry.LambdaContext?.InvokedFunctionArn,
51+
MemoryLimitInMB = logEntry.LambdaContext?.MemoryLimitInMB,
52+
Version = logEntry.LambdaContext?.FunctionVersion,
53+
ColdStart = logEntry.ColdStart,
54+
},
55+
Level = logEntry.Level.ToString(),
56+
Timestamp = logEntry.Timestamp.ToString("o"),
57+
Logger = new
58+
{
59+
Name = logEntry.Name,
60+
SampleRate = logEntry.SamplingRate
61+
},
62+
};
63+
}
64+
}
65+
// --8<-- [end:custom_log_formatter_class]

0 commit comments

Comments
 (0)