ThrottledLogging 1.0.6

ThrottledLogging

A time-interval-based log throttler for Microsoft.Extensions.Logging that suppresses repeated log entries per key and reports the suppressed count when logging resumes.

Projects

Installation

dotnet add package ThrottledLogging

Usage

Call the throttled extension methods on any ILogger. Each call requires a key (identifies the log message for throttling purposes) and an interval (minimum time between emissions).

// Only logs once per minute for the key "disk-full".
// On the next emission after suppression, appends "(N messages suppressed)".
logger.LogWarningThrottled("disk-full", TimeSpan.FromMinutes(1), "Disk usage is above {Percent}%", usage);

Available methods mirror the standard ILogger API:

• LogTraceThrottled
• LogDebugThrottled
• LogInformationThrottled
• LogWarningThrottled
• LogErrorThrottled
• LogCriticalThrottled

Each method signature is (string key, TimeSpan interval, string? messageTemplate, params object?[] args). On .NET 9+, the args parameter uses params ReadOnlySpan<object?> for improved performance.

Suppressed count

When a throttled message is allowed through after one or more suppressions, the suppressed count is automatically appended to the message:

Disk usage is above 95% (3 messages suppressed)

Multiple independent keys

Each key has its own throttle budget — different keys do not share a counter:

logger.LogErrorThrottled("service-a-down", TimeSpan.FromSeconds(5), "Service A is unreachable");
logger.LogErrorThrottled("service-b-down", TimeSpan.FromSeconds(5), "Service B is unreachable");

Configuration

Global expiry and cleanup settings can be adjusted at startup:

// Expire idle entries after 30 minutes; run cleanup every 15 minutes.
ThrottledLogger.Configure(expiry: TimeSpan.FromMinutes(30), cleanupPeriod: TimeSpan.FromMinutes(15));

Requirements

• .NET Standard 2.0, .NET 8, .NET 9, or .NET 10

Note: On .NET Standard 2.0 targets, the background cleanup timer that removes idle entries is disabled. Entries are still released when the associated ILogger is garbage-collected.

Build

dotnet build
dotnet test
dotnet pack

ThrottledLogging（中文）

基于时间间隔的 Microsoft.Extensions.Logging 日志限流器，可按 key 抑制重复日志，并在恢复输出时报告被抑制的条数。

项目结构

安装

dotnet add package ThrottledLogging

用法

在任意 ILogger 上调用限流扩展方法。每次调用需传入一个 key（用于标识被限流的日志消息）和一个 interval（两次输出之间的最短间隔）。

// "disk-full" 这个 key 每分钟最多输出一次。
// 抑制后下次恢复输出时，会自动追加"(N messages suppressed)"。
logger.LogWarningThrottled("disk-full", TimeSpan.FromMinutes(1), "Disk usage is above {Percent}%", usage);

可用方法与标准 ILogger API 一一对应：

• LogTraceThrottled
• LogDebugThrottled
• LogInformationThrottled
• LogWarningThrottled
• LogErrorThrottled
• LogCriticalThrottled

每个方法的签名为 (string key, TimeSpan interval, string? messageTemplate, params object?[] args)。 在 .NET 9+ 上，args 参数使用 params ReadOnlySpan<object?> 以获得更好的性能。

抑制计数

当某条被限流的消息在经历一次或多次抑制后重新允许输出时，抑制次数会自动追加到消息末尾：

Disk usage is above 95% (3 messages suppressed)

多个独立 key

每个 key 拥有独立的限流计数器，互不干扰：

logger.LogErrorThrottled("service-a-down", TimeSpan.FromSeconds(5), "Service A is unreachable");
logger.LogErrorThrottled("service-b-down", TimeSpan.FromSeconds(5), "Service B is unreachable");

全局配置

可在应用启动时调整全局的过期时间和清理周期：

// 空闲条目 30 分钟后过期；每 15 分钟执行一次清理。
ThrottledLogger.Configure(expiry: TimeSpan.FromMinutes(30), cleanupPeriod: TimeSpan.FromMinutes(15));

环境要求

• .NET Standard 2.0、.NET 8、.NET 9 或 .NET 10

注意： 在 .NET Standard 2.0 目标上，用于移除空闲条目的后台清理定时器已被禁用。当关联的 ILogger 被垃圾回收时，相关条目仍会被释放。

构建

dotnet build
dotnet test
dotnet pack