fix(logging): Improve log sampling documentation and add manual RefreshSampleRateCalculation

Author: hjgraca

docs/core/logging.md

@@ -778,12 +778,16 @@ custom keys can be persisted across invocations. If you want all custom keys to
 
 ## Sampling debug logs
 
-You can dynamically set a percentage of your logs to **DEBUG** level via env var `POWERTOOLS_LOGGER_SAMPLE_RATE` or
-via `SamplingRate` parameter on attribute.
+Use sampling when you want to dynamically change your log level to **DEBUG** based on a **percentage of the Lambda function invocations**.
 
-!!! info
-    Configuration on environment variable is given precedence over sampling rate configuration on attribute, provided it's
-    in valid value range.
+You can use values ranging from `0.0` to `1` (100%) when setting `POWERTOOLS_LOGGER_SAMPLE_RATE` env var, or `SamplingRate` parameter in Logger.
+
+???+ tip "Tip: When is this useful?"
+    Log sampling allows you to capture debug information for a fraction of your requests, helping you diagnose rare or intermittent issues without increasing the overall verbosity of your logs.
+
+    Example: Imagine an e-commerce checkout process where you want to understand rare payment gateway errors. With 10% sampling, you'll log detailed information for a small subset of transactions, making troubleshooting easier without generating excessive logs.
+
+The sampling decision happens automatically with each invocation when using `Logger` decorator.  When not using the decorator, you're in charge of refreshing it via `RefreshSampleRateCalculation` method. Skipping both may lead to unexpected sampling results.
 
 === "Sampling via attribute parameter"
 
@@ -802,6 +806,30 @@ via `SamplingRate` parameter on attribute.
     }
     ```
 
+=== "Sampling Logger.Configure"
+
+    ```c# hl_lines="5-10 16"
+    public class Function
+    {
+        public Function()
+        {
+            Logger.Configure(options =>
+            {
+                options.MinimumLogLevel = LogLevel.Information;
+                options.LoggerOutputCase = LoggerOutputCase.CamelCase;
+                options.SamplingRate = 0.1; // 10% sampling
+            });
+        }
+
+        public async Task<APIGatewayProxyResponse> FunctionHandler
+            (APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
+        {
+            Logger.RefreshSampleRateCalculation();            
+            ...
+        }
+    }
+    ```
+
 === "Sampling via environment variable"
 
     ```yaml hl_lines="8"

libraries/src/AWS.Lambda.Powertools.Logging/Internal/PowertoolsLoggerProvider.cs

@@ -24,10 +24,10 @@ public PowertoolsLoggerProvider(
     {
         _powertoolsConfigurations = powertoolsConfigurations;
         _currentConfig = config;
-        
+
         // Set execution environment
         _powertoolsConfigurations.SetExecutionEnvironment(this);
-        
+
         // Apply environment configurations if available
         ConfigureFromEnvironment();
     }
@@ -60,36 +60,37 @@ public void ConfigureFromEnvironment()
 
         var minLogLevel = lambdaLogLevelEnabled ? lambdaLogLevel : logLevel;
         var effectiveLogLevel = minLogLevel != LogLevel.None ? minLogLevel : LoggingConstants.DefaultLogLevel;
-        
+
         // Only set InitialLogLevel if it hasn't been explicitly configured
         if (_currentConfig.InitialLogLevel == LogLevel.Information)
         {
             _currentConfig.InitialLogLevel = effectiveLogLevel;
         }
+
         _currentConfig.MinimumLogLevel = effectiveLogLevel;
-        
+
         _currentConfig.XRayTraceId = _powertoolsConfigurations.XRayTraceId;
         _currentConfig.LogEvent = _powertoolsConfigurations.LoggerLogEvent;
-        
+
         // Configure the log level key based on output case
         _currentConfig.LogLevelKey = _powertoolsConfigurations.LambdaLogLevelEnabled() &&
                                      _currentConfig.LoggerOutputCase == LoggerOutputCase.PascalCase
             ? "LogLevel"
             : LoggingConstants.KeyLogLevel;
-            
+
         ProcessSamplingRate(_currentConfig, _powertoolsConfigurations);
         _environmentConfigured = true;
     }
-    
+
     /// <summary>
     /// Process sampling rate configuration
     /// </summary>
     private void ProcessSamplingRate(PowertoolsLoggerConfiguration config, IPowertoolsConfigurations configurations)
     {
-        var samplingRate = config.SamplingRate > 0 
-            ? config.SamplingRate 
+        var samplingRate = config.SamplingRate > 0
+            ? config.SamplingRate
             : configurations.LoggerSampleRate;
-            
+
         samplingRate = ValidateSamplingRate(samplingRate, config);
         config.SamplingRate = samplingRate;
     }
@@ -122,20 +123,29 @@ public virtual ILogger CreateLogger(string categoryName)
     }
 
     internal PowertoolsLoggerConfiguration GetCurrentConfig() => _currentConfig;
-    
+
     public void UpdateConfiguration(PowertoolsLoggerConfiguration config)
     {
         _currentConfig = config;
-        
+
         // Apply environment configurations if available
         if (_powertoolsConfigurations != null && !_environmentConfigured)
         {
             ConfigureFromEnvironment();
         }
     }
 
+    /// <summary>
+    ///   Refresh the sampling calculation and update the minimum log level if needed
+    /// </summary>
+    /// <returns>True if debug sampling was enabled, false otherwise</returns>
+    internal bool RefreshSampleRateCalculation()
+    {
+        return _currentConfig.RefreshSampleRateCalculation();
+    }
+
     public virtual void Dispose()
     {
         _loggers.Clear();
     }
-}
+}

libraries/src/AWS.Lambda.Powertools.Logging/Logger.Sampling.cs

@@ -0,0 +1,13 @@
+namespace AWS.Lambda.Powertools.Logging;
+
+public static partial class Logger
+{
+    /// <summary>
+    ///   Refresh the sampling calculation and update the minimum log level if needed
+    /// </summary>
+    /// <returns>True if debug sampling was enabled, false otherwise</returns>
+    public static bool RefreshSampleRateCalculation()
+    {
+        return _config.RefreshSampleRateCalculation();
+    }
+}

libraries/src/AWS.Lambda.Powertools.Logging/Logger.cs

@@ -12,6 +12,7 @@ namespace AWS.Lambda.Powertools.Logging;
 /// </summary>
 public static partial class Logger
 {
+    private static PowertoolsLoggerConfiguration _config;
     private static ILogger _loggerInstance;
     private static readonly object Lock = new object();
 
@@ -58,9 +59,9 @@ public static void Configure(Action<PowertoolsLoggerConfiguration> configure)
     {
         lock (Lock)
         {
-            var config = new PowertoolsLoggerConfiguration();
-            configure(config);
-            _loggerInstance = LoggerFactoryHelper.CreateAndConfigureFactory(config).CreatePowertoolsLogger();
+            _config = new PowertoolsLoggerConfiguration();
+            configure(_config);
+            _loggerInstance = LoggerFactoryHelper.CreateAndConfigureFactory(_config).CreatePowertoolsLogger();
         }
     }
 

libraries/src/AWS.Lambda.Powertools.Logging/PowertoolsLoggerConfiguration.cs

@@ -324,22 +324,31 @@ internal virtual double GetRandom()
     {
         return GetSafeRandom();
     }
-    
+
+    /// <summary>
+    ///   Refresh the sampling calculation and update the minimum log level if needed
+    /// </summary>
+    /// <returns>True if debug sampling was enabled, false otherwise</returns>
     internal bool RefreshSampleRateCalculation()
     {
         return RefreshSampleRateCalculation(out _);
     }
 
+    /// <summary>
+    ///   Refresh the sampling calculation and update the minimum log level if needed
+    /// </summary>
+    /// <param name="samplerValue"></param>
+    /// <returns>True if debug sampling was enabled, false otherwise</returns>
     internal bool RefreshSampleRateCalculation(out double samplerValue)
     {
         samplerValue = 0.0;
-        
+
         if (SamplingRate <= 0)
             return false;
 
         // Increment counter at the beginning for proper cold start protection
         SamplingRefreshCount++;
-        
+
         // Skip first call for cold start protection
         if (SamplingRefreshCount == 1)
         {
@@ -357,10 +366,11 @@ internal bool RefreshSampleRateCalculation(out double samplerValue)
         {
             MinimumLogLevel = InitialLogLevel;
         }
-        
+
         return shouldEnableDebugSampling;
     }
 
+
     internal bool ShouldEnableDebugSampling()
     {
         return ShouldEnableDebugSampling(out _);
@@ -370,11 +380,11 @@ internal bool ShouldEnableDebugSampling(out double samplerValue)
     {
         samplerValue = 0.0;
         if (SamplingRate <= 0) return false;
-        
+
         samplerValue = GetRandom();
         return samplerValue <= SamplingRate;
     }
-    
+
     internal static double GetSafeRandom()
     {
         var randomGenerator = RandomNumberGenerator.Create();
@@ -383,4 +393,4 @@ internal static double GetSafeRandom()
         uint randomUInt = BitConverter.ToUInt32(data, 0);
         return (double)randomUInt / uint.MaxValue;
     }
-}
+}

libraries/src/AWS.Lambda.Powertools.Logging/PowertoolsLoggerExtensions.cs

@@ -257,4 +257,13 @@ public static void ClearBuffer(this ILogger logger)
         // Direct call to the buffer manager to avoid any recursion
         LogBufferManager.ClearCurrentBuffer();
     }
+    
+    /// <summary>
+    ///   Refresh the sampling calculation and update the minimum log level if needed
+    /// </summary>
+    /// <returns></returns>
+    public static bool RefreshSampleRateCalculation(this ILogger logger)
+    {
+        return Logger.RefreshSampleRateCalculation();
+    }
 }