merge

Author: hjgraca

.github/workflows/build.yml

@@ -37,10 +37,10 @@ jobs:
         run: dotnet build --configuration Release --no-restore /tl
 
       - name: Test & Code Coverage
-        run: dotnet test --no-restore --filter "Category!=E2E" --collect:"XPlat Code Coverage" --results-directory ./codecov --verbosity quiet
+        run: dotnet test --no-restore --filter "Category!=E2E" --collect:"XPlat Code Coverage" --results-directory ./codecov --verbosity normal
 
       - name: Test Examples
-        run: dotnet test ../examples/ --verbosity quiet
+        run: dotnet test ../examples/ --verbosity normal
 
       - name: Codecov
         uses: codecov/codecov-action@13ce06bfc6bbe3ecf90edbbf1bc32fe5978ca1d3 # 5.3.1

.github/workflows/label_pr_on_title.yml

@@ -6,14 +6,12 @@ on:
     types:
       - completed
 
-permissions:
-  contents: read
-
 jobs:
   get_pr_details:
     permissions:
-      id-token: write
       contents: read
+      id-token: write
+      pull-requests: read
     # Guardrails to only ever run if PR recording workflow was indeed
     # run in a PR event and ran successfully
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
@@ -27,6 +25,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
+      pull-requests: write
     needs: get_pr_details
     runs-on: ubuntu-latest
     steps:

.github/workflows/on_label_added.yml

@@ -12,6 +12,7 @@ permissions:
 jobs:
   get_pr_details:
     permissions:
+      contents: read
       id-token: write
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     uses: ./.github/workflows/reusable_export_pr_details.yml

.github/workflows/on_merged_pr.yml

@@ -25,6 +25,8 @@ jobs:
     permissions:
       contents: read
       id-token: write
+      issues: write
+      pull-requests: write
     needs: get_pr_details
     runs-on: ubuntu-latest
     if: needs.get_pr_details.outputs.prIsMerged == 'true'

.github/workflows/on_opened_pr.yml

@@ -13,6 +13,7 @@ jobs:
   get_pr_details:
     permissions:
       id-token: write
+      contents: read
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     uses: ./.github/workflows/reusable_export_pr_details.yml
     with:

.github/workflows/reusable_export_pr_details.yml

@@ -43,6 +43,7 @@ jobs:
   export_pr_details:
     permissions:
       id-token: write
+      contents: read
     # see https://github.com/aws-powertools/powertools-lambda-python/issues/1349
     if: inputs.workflow_origin == 'aws-powertools/powertools-lambda-dotnet'
     runs-on: ubuntu-latest

README.md

@@ -4,7 +4,7 @@
 [![Build](https://github.com/aws-powertools/powertools-lambda-dotnet/actions/workflows/build.yml/badge.svg?branch=develop)](https://github.com/aws-powertools/powertools-lambda-dotnet/actions/workflows/build.yml)
 [![codecov.io](https://codecov.io/github/aws-powertools/powertools-lambda-dotnet/branch/develop/graphs/badge.svg)](https://app.codecov.io/gh/aws-powertools/powertools-lambda-dotnet)
 [![dotnet support](https://img.shields.io/static/v1?label=dotnet&message=%20NET6.0|NET8.0&color=blue?style=flat-square&logo=dotnet)](https://dotnet.microsoft.com/en-us/download/dotnet/6.0)
-[![NuGet Downloads](https://img.shields.io/nuget/dt/AWS.Lambda.Powertools.Logging.svg)](https://www.nuget.org/packages?q=AWS.Lambda.Powertools)
+[![NuGet Downloads](https://img.shields.io/nuget/dt/AWS.Lambda.Powertools.Logging.svg)](https://www.nuget.org/packages?q=AWS.Lambda.Powertools) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/aws-powertools/powertools-lambda-dotnet/badge)](https://scorecard.dev/viewer/?uri=github.com/aws-powertools/powertools-lambda-dotnet)
 [![Join our Discord](https://dcbadge.vercel.app/api/server/B8zZKbbyET?style=flat-square)](https://discord.gg/B8zZKbbyET)
 
 Powertools for AWS Lambda (.NET) is a developer toolkit to implement Serverless [best practices and increase developer velocity](https://docs.powertools.aws.dev/lambda-dotnet/#features).

docs/core/metrics-v2.md

@@ -16,6 +16,12 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://aws.
 * Ahead-of-Time compilation to native code support [AOT](https://docs.aws.amazon.com/lambda/latest/dg/dotnet-native-aot.html) from version 1.7.0
 * Support for AspNetCore middleware and filters to capture metrics for HTTP requests
 
+## Breaking changes from V1
+
+* **`Dimensions`** outputs as an array of arrays instead of an array of objects. Example: `Dimensions: [["service", "Environment"]]` instead of `Dimensions: ["service", "Environment"]`
+* **`FunctionName`** is not added as default dimension and only to cold start metric.
+* **`Default Dimensions`** can now be included in Cold Start metrics, this is a potential breaking change if you were relying on the absence of default dimensions in Cold Start metrics when searching.
+
 <br />
 
 <figure>
@@ -432,7 +438,7 @@ During metrics validation, if no metrics are provided then a warning will be log
 !!! tip "Metric validation"
     If metrics are provided, and any of the following criteria are not met, **`SchemaValidationException`** will be raised:
 
-    * Maximum of 9 dimensions
+    * Maximum of 30 dimensions
     * Namespace is set
     * Metric units must be [supported by CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html)
 
@@ -610,7 +616,7 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use **`PushSing
         ...
     ```
 
-By default it will skip all previously defined dimensions including default dimensions. Use default_dimensions keyword argument if you want to reuse default dimensions or specify custom dimensions from a dictionary.
+By default it will skip all previously defined dimensions including default dimensions. Use `dimensions` argument if you want to reuse default dimensions or specify custom dimensions from a dictionary.
 
 - `Metrics.DefaultDimensions`: Reuse default dimensions when using static Metrics
 - `Options.DefaultDimensions`: Reuse default dimensions when using Builder or Configure patterns
@@ -631,7 +637,7 @@ By default it will skip all previously defined dimensions including default dime
                     unit: MetricUnit.Count,
                     nameSpace: "ExampleApplication",
                     service: "Booking",
-                    defaultDimensions: new Dictionary<string, string>
+                    dimensions: new Dictionary<string, string>
                     {
                         {"FunctionContext", "$LATEST"}
                     });
@@ -651,10 +657,10 @@ By default it will skip all previously defined dimensions including default dime
         {
             { "Default", "SingleMetric" }
         });
-        Metrics.PushSingleMetric("SingleMetric", 1, MetricUnit.Count, defaultDimensions: Metrics.DefaultDimensions );
+        Metrics.PushSingleMetric("SingleMetric", 1, MetricUnit.Count, dimensions: Metrics.DefaultDimensions );
         ...
     ```
-=== "Default Dimensions Options / Builder patterns .cs"
+=== "Default Dimensions Options / Builder patterns"
 
     ```csharp hl_lines="9-13 18"
     using AWS.Lambda.Powertools.Metrics;
@@ -674,11 +680,59 @@ By default it will skip all previously defined dimensions including default dime
 
     public void HandlerSingleMetricDimensions()
     {
-        _metrics.PushSingleMetric("SuccessfulBooking", 1, MetricUnit.Count, defaultDimensions: _metrics.Options.DefaultDimensions);
+        _metrics.PushSingleMetric("SuccessfulBooking", 1, MetricUnit.Count, dimensions: _metrics.Options.DefaultDimensions);
     }
         ...
     ```
 
+### Cold start Function Name dimension
+
+In cases where you want to customize the `FunctionName` dimension in Cold Start metrics.
+
+This is useful where you want to maintain the same name in case of auto generated handler names (cdk, top-level statement functions, etc.)
+
+Example:
+
+=== "In decorator"
+    
+    ```csharp hl_lines="5"
+    using AWS.Lambda.Powertools.Metrics;
+    
+    public class Function {
+      
+      [Metrics(FunctionName = "MyFunctionName", Namespace = "ExampleApplication", Service = "Booking")]
+      public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
+      {
+        Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
+        ...
+      }
+    ```
+=== "Configure / Builder patterns"
+
+    ```csharp hl_lines="12"
+    using AWS.Lambda.Powertools.Metrics;
+    
+    public class Function {
+      
+      public Function()
+      {
+        Metrics.Configure(options =>
+        {
+            options.Namespace = "dotnet-powertools-test";
+            options.Service = "testService";
+            options.CaptureColdStart = true;
+            options.FunctionName = "MyFunctionName";
+        });
+      }
+
+      [Metrics]
+      public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
+      {
+        Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
+        ...
+      }
+    ```
+
 ## AspNetCore
 
 ### Installation

libraries/src/AWS.Lambda.Powertools.Common/Core/ConsoleWrapper.cs

@@ -0,0 +1,31 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+using System;
+
+namespace AWS.Lambda.Powertools.Common;
+
+/// <inheritdoc />
+public class ConsoleWrapper : IConsoleWrapper
+{
+    /// <inheritdoc />
+    public void WriteLine(string message) => Console.WriteLine(message);
+    /// <inheritdoc />
+    public void Debug(string message) => System.Diagnostics.Debug.WriteLine(message);
+    /// <inheritdoc />
+    public void Error(string message) => Console.Error.WriteLine(message);
+    /// <inheritdoc />
+    public string ReadLine() => Console.ReadLine();
+}

libraries/src/AWS.Lambda.Powertools.Common/Core/IConsoleWrapper.cs

@@ -0,0 +1,46 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+namespace AWS.Lambda.Powertools.Common;
+
+/// <summary>
+/// Wrapper for console operations to facilitate testing by abstracting system console interactions.
+/// </summary>
+public interface IConsoleWrapper
+{
+    /// <summary>
+    /// Writes the specified message followed by a line terminator to the standard output stream.
+    /// </summary>
+    /// <param name="message">The message to write.</param>
+    void WriteLine(string message);
+
+    /// <summary>
+    /// Writes a debug message to the trace listeners in the Debug.Listeners collection.
+    /// </summary>
+    /// <param name="message">The debug message to write.</param>
+    void Debug(string message);
+
+    /// <summary>
+    /// Writes the specified error message followed by a line terminator to the standard error stream.
+    /// </summary>
+    /// <param name="message">The error message to write.</param>
+    void Error(string message);
+
+    /// <summary>
+    /// Reads the next line of characters from the standard input stream.
+    /// </summary>
+    /// <returns>The next line of characters from the input stream, or null if no more lines are available.</returns>
+    string ReadLine();
+}

libraries/src/AWS.Lambda.Powertools.Metrics.AspNetCore/Http/ColdStartTracker.cs

@@ -0,0 +1,76 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+using Amazon.Lambda.Core;
+using Microsoft.AspNetCore.Http;
+
+namespace AWS.Lambda.Powertools.Metrics.AspNetCore.Http;
+
+
+/// <summary>
+/// Tracks and manages cold start metrics for Lambda functions in ASP.NET Core applications.
+/// </summary>
+/// <remarks>
+/// This class is responsible for detecting and recording the first invocation (cold start) of a Lambda function.
+/// It ensures thread-safe tracking of cold starts and proper metric capture using the provided IMetrics implementation.
+/// </remarks>
+internal class ColdStartTracker : IDisposable
+{
+    private readonly IMetrics _metrics;
+    private static bool _coldStart = true;
+    private static readonly object _lock = new();
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ColdStartTracker"/> class.
+    /// </summary>
+    /// <param name="metrics">The metrics implementation to use for capturing cold start metrics.</param>
+    public ColdStartTracker(IMetrics metrics)
+    {
+        _metrics = metrics;
+    }
+
+    /// <summary>
+    /// Tracks the cold start of the Lambda function.
+    /// </summary>
+    /// <param name="context">The current HTTP context.</param>
+    internal void TrackColdStart(HttpContext context)
+    {
+        if (!_coldStart) return;
+
+        lock (_lock)
+        {
+            if (!_coldStart) return;
+            _metrics.CaptureColdStartMetric(context.Items["LambdaContext"] as ILambdaContext);
+            _coldStart = false;
+        }
+    }
+
+    /// <summary>
+    /// Resets the cold start tracking state.
+    /// </summary>
+    internal static void ResetColdStart()
+    {
+        lock (_lock)
+        {
+            _coldStart = true;
+        }
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        ResetColdStart();
+    }
+}