Skip to content

Commit

Permalink
Merge pull request #116 from awslabs/amirkaws/add-di-support-for-logging
Browse files Browse the repository at this point in the history 
feat: add documentations to Tracing, Logging, and Metrics attributes
  • Loading branch information
@sliedig
sliedig authored Jul 4, 2022
2 parents 9dca27a + 20309e1 commit 79d04c1
Show file tree
Hide file tree
Showing 5 changed files with 298 additions and 53 deletions.
4 changes: 2 additions & 2 deletions libraries/src/AWS.Lambda.Powertools.Logging/Internal/LoggerProvider.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ namespace AWS.Lambda.Powertools.Logging.Internal;
/// Implements the <see cref="Microsoft.Extensions.Logging.ILoggerProvider" />
/// </summary>
/// <seealso cref="Microsoft.Extensions.Logging.ILoggerProvider" />
internal sealed class LoggerProvider : ILoggerProvider
public sealed class LoggerProvider : ILoggerProvider
{
/// <summary>
/// The loggers
Expand All @@ -42,7 +42,7 @@ internal sealed class LoggerProvider : ILoggerProvider
/// Initializes a new instance of the <see cref="LoggerProvider" /> class.
/// </summary>
/// <param name="config">The configuration.</param>
internal LoggerProvider(IOptions<LoggerConfiguration> config)
public LoggerProvider(IOptions<LoggerConfiguration> config)
{
_currentConfig = config?.Value;
}
Expand Down
96 changes: 93 additions & 3 deletions libraries/src/AWS.Lambda.Powertools.Logging/LoggingAttribute.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,100 @@
namespace AWS.Lambda.Powertools.Logging;

/// <summary>
/// Class LoggingAttribute.
/// Implements the <see cref="MethodAspectAttribute" />
/// Provides a Lambda optimized logger with output structured as JSON. <br/>
/// <br/>
/// Key features <br/>
/// --------------------- <br/>
/// <list type="bullet">
/// <item>
/// <description>Capture key fields from Lambda context and cold start</description>
/// </item>
/// <item>
/// <description>Log Lambda event when instructed (disabled by default)</description>
/// </item>
/// <item>
/// <description>Log sampling enables DEBUG log level for a percentage of requests (disabled by default)</description>
/// </item>
/// <item>
/// <description>Append additional keys to structured log at any point in time</description>
/// </item>
/// </list>
/// <br/>
/// Environment variables <br/>
/// --------------------- <br/>
/// <list type="table">
/// <listheader>
/// <term>Variable name</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>POWERTOOLS_SERVICE_NAME</term>
/// <description>string, service name</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_LOG_LEVEL</term>
/// <description>string, logging level (e.g. Information, Debug, and Trace)</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_LOGGER_CASE</term>
/// <description>string, logger output case (e.g. CamelCase, PascalCase, and SnakeCase)</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_LOGGER_SAMPLE_RATE</term>
/// <description>double, sampling rate ranging from 0 to 1, 1 being 100% sampling</description>
/// </item>
/// </list>
/// <br/>
/// Parameters <br/>
/// ----------- <br/>
/// <list type="table">
/// <listheader>
/// <term>Parameter name</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>Service</term>
/// <description>string, service name to be appended in logs, by default "service_undefined"</description>
/// </item>
/// <item>
/// <term>LogLevel</term>
/// <description>enum, logging level (e.g. Information, Debug, and Trace), by default Information</description>
/// </item>
/// <item>
/// <term>LoggerOutputCase</term>
/// <description>enum, logger output case (e.g. CamelCase, PascalCase, and SnakeCase)</description>
/// </item>
/// <item>
/// <term>SamplingRate</term>
/// <description>double, sample rate for debug calls within execution context defaults to 0.0</description>
/// </item>
/// <item>
/// <term>CorrelationIdPath</term>
/// <description>string, pointer path to extract correlation id from input parameter</description>
/// </item>
/// <item>
/// <term>ClearState</term>
/// <description>bool, clear all custom keys on each request, by default false</description>
/// </item>
/// </list>
/// </summary>
/// <seealso cref="MethodAspectAttribute" />
/// <example>
/// <code>
/// [Logging(
/// Service = "Example",
/// LogEvent = true,
/// ClearState = true,
/// LogLevel = LogLevel.Debug,
/// LoggerOutputCase = LoggerOutputCase.SnakeCase,
/// CorrelationIdPath = "/headers/my_request_id_header")
/// ]
/// public async Task&lt;APIGatewayProxyResponse&gt; FunctionHandler
/// (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
/// {
/// ...
/// }
/// </code>
/// </example>
[AttributeUsage(AttributeTargets.Method)]
public class LoggingAttribute : MethodAspectAttribute
{
Expand Down
79 changes: 76 additions & 3 deletions libraries/src/AWS.Lambda.Powertools.Metrics/MetricsAttribute.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,83 @@
namespace AWS.Lambda.Powertools.Metrics;

/// <summary>
/// Class MetricsAttribute.
/// Implements the <see cref="MethodAspectAttribute" />
/// Creates custom metrics asynchronously by logging metrics to
/// standard output following Amazon CloudWatch Embedded Metric Format (EMF). <br/>
/// <br/>
/// Key features <br/>
/// --------------------- <br/>
/// <list type="bullet">
/// <item>
/// <description>Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)</description>
/// </item>
/// <item>
/// <description>Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)</description>
/// </item>
/// <item>
/// <description>Metrics are created asynchronously by CloudWatch service, no custom stacks needed</description>
/// </item>
/// <item>
/// <description>Context manager to create a one off metric with a different dimension</description>
/// </item>
/// </list>
/// <br/>
/// Environment variables <br/>
/// --------------------- <br/>
/// <list type="table">
/// <listheader>
/// <term>Variable name</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>POWERTOOLS_SERVICE_NAME</term>
/// <description>string, service name</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_METRICS_NAMESPACE</term>
/// <description>string, metric namespace</description>
/// </item>
/// </list>
/// <br/>
/// Parameters <br/>
/// ----------- <br/>
/// <list type="table">
/// <listheader>
/// <term>Parameter name</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>Service</term>
/// <description>string, service name is used for metric dimension across all metrics, by default service_undefined</description>
/// </item>
/// <item>
/// <term>Namespace</term>
/// <description>string, logical container where all metrics will be placed</description>
/// </item>
/// <item>
/// <term>CaptureColdStart</term>
/// <description>bool, captures cold start during Lambda execution, by default false</description>
/// </item>
/// <item>
/// <term>RaiseOnEmptyMetrics</term>
/// <description>bool, instructs metrics validation to throw exception if no metrics are provided, by default false</description>
/// </item>
/// </list>
/// </summary>
/// <seealso cref="MethodAspectAttribute" />
/// <example>
/// <code>
/// [Metrics(
/// Service = "Example",
/// Namespace = "ExampleNamespace",
/// CaptureColdStart = true,
/// RaiseOnEmptyMetrics = true)
/// ]
/// public async Task&lt;APIGatewayProxyResponse&gt; FunctionHandler
/// (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
/// {
/// ...
/// }
/// </code>
/// </example>
[AttributeUsage(AttributeTargets.Method)]
public class MetricsAttribute : MethodAspectAttribute
{
Expand Down
90 changes: 86 additions & 4 deletions libraries/src/AWS.Lambda.Powertools.Tracing/TracingAttribute.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,92 @@
namespace AWS.Lambda.Powertools.Tracing;

/// <summary>
/// Class TracingAttribute.
/// Implements the <see cref="MethodAspectAttribute" />
/// Creates an opinionated thin wrapper for AWS X-Ray .NET SDK which provides functionality to reduce the overhead of performing common tracing tasks. <br/>
/// <br/>
/// Key features <br/>
/// --------------------- <br/>
/// <list type="bullet">
/// <item>
/// <description>Helper methods to improve the developer experience for creating custom AWS X-Ray subsegments</description>
/// </item>
/// <item>
/// <description>Capture cold start as annotation</description>
/// </item>
/// <item>
/// <description>Capture function responses and full exceptions as metadata</description>
/// </item>
/// <item>
/// <description>Better experience when developing with multiple threads</description>
/// </item>
/// <item>
/// <description>Auto-patch supported modules by AWS X-Ray</description>
/// </item>
/// </list>
/// <br/>
/// Environment variables <br/>
/// --------------------- <br/>
/// <list type="table">
/// <listheader>
/// <term>Variable name</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>POWERTOOLS_SERVICE_NAME</term>
/// <description>string, service name</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_TRACER_CAPTURE_RESPONSE</term>
/// <description>bool, disable auto-capture response as metadata (e.g. true, false)</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_TRACER_CAPTURE_ERROR</term>
/// <description>bool, disable auto-capture error as metadata (e.g. true, false)</description>
/// </item>
/// <item>
/// <term>POWERTOOLS_TRACE_DISABLED</term>
/// <description>bool, disable auto-capture error or response as metadata (e.g. true, false)</description>
/// </item>
/// </list>
/// <br/>
/// Parameters <br/>
/// ----------- <br/>
/// <list type="table">
/// <listheader>
/// <term>Parameter name</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>Service</term>
/// <description>string, service name that will be appended in all tracing metadata</description>
/// </item>
/// <item>
/// <term>SegmentName</term>
/// <description>string, custom segment name for the operation, by default '## {MethodName}'</description>
/// </item>
/// <item>
/// <term>Namespace</term>
/// <description>string, namespace to current subsegment</description>
/// </item>
/// <item>
/// <term>CaptureMode</term>
/// <description>enum, capture mode to record method responses and errors (e.g. EnvironmentVariable, Response, and Error), by default EnvironmentVariable</description>
/// </item>
/// </list>
/// </summary>
/// <seealso cref="MethodAspectAttribute" />
/// <example>
/// <code>
/// [Tracing(
/// SegmentName = "ExampleSegment",
/// Namespace = "ExampleNamespace",
/// CaptureMode = TracingCaptureMode.ResponseAndError)
/// ]
/// public async Task&lt;APIGatewayProxyResponse&gt; FunctionHandler
/// (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
/// {
/// ...
/// }
/// </code>
/// </example>
public class TracingAttribute : MethodAspectAttribute
{
/// <summary>
Expand All @@ -40,7 +122,7 @@ public class TracingAttribute : MethodAspectAttribute
public string Namespace { get; set; } = "";

/// <summary>
/// Set capture mode to record method responses and exceptions.
/// Set capture mode to record method responses and errors.
/// The defaults are the environment variables <c>POWERTOOLS_TRACER_CAPTURE_RESPONSE</c> and
/// <c>POWERTOOLS_TRACER_CAPTURE_ERROR</c>.
/// </summary>
Expand Down
Loading

0 comments on commit 79d04c1

Please sign in to comment.