Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add documentations to Tracing, Logging, and Metrics attributes #116

Merged
merged 7 commits into from
Jul 4, 2022
Merged

feat: add documentations to Tracing, Logging, and Metrics attributes #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0ebb61f
Add LoggingBuilder extensions to support dependency injection for logger
amirkaws Mar 16, 2022
c464047
Remove LoggingBuilder extensions to support dependency injection for …
amirkaws Mar 28, 2022
cc89699
Remove extra dependency
amirkaws Mar 28, 2022
24e6911
Remove extra dependency
amirkaws Mar 28, 2022
c3aa2f8
add logging attribute class documentation
amirkaws Mar 28, 2022
1e4eac9
add logging attribute class documentation
amirkaws Mar 28, 2022
20309e1
add attribute class documentations
amirkaws Mar 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions libraries/src/AWS.Lambda.Powertools.Logging/Internal/LoggerProvider.cs
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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