Class SampledLog

java.lang.Object
cloud.opencode.base.log.enhance.SampledLog
public final class SampledLog extends Object
Sampled Log - Rate-limited and Sampled Logging 采样日志 - 限流和采样的日志

SampledLog provides mechanisms to control high-frequency logging through probability sampling, time-based sampling, or count-based sampling.

SampledLog 提供通过概率采样、基于时间的采样或基于计数的采样来控制高频日志的机制。

Example | 示例:

// 1% probability sampling
SampledLogger sampledLog = SampledLog.sample(0.01);
sampledLog.info("High frequency event: {}", eventId);

// Time-based: at most once per 5 seconds
SampledLogger rateLimited = SampledLog.sampleByTime(Duration.ofSeconds(5));
rateLimited.warn("Rate limited warning");

// Count-based: every 100th log
SampledLogger countBased = SampledLog.sampleByCount(100);
countBased.debug("Processing item {}", itemId);

Features | 主要功能:

  • Probability-based sampling (0.0 to 1.0) - 基于概率的采样（0.0 到 1.0）
  • Time-based sampling (minimum interval) - 基于时间的采样（最小间隔）
  • Count-based sampling (every Nth message) - 基于计数的采样（每 N 条消息）

Security | 安全性:

  • Thread-safe: Yes (AtomicLong + ThreadLocalRandom) - 线程安全: 是（AtomicLong + ThreadLocalRandom）
  • Null-safe: No (format must not be null) - 空值安全: 否（格式不能为 null）
Since:
JDK 25, opencode-base-log V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • sample

      public static SampledLog.SampledLogger sample(double sampleRate)
      Creates a probability-based sampled logger. 创建基于概率的采样日志记录器。
      Parameters:
      sampleRate - the sample rate (0.0 to 1.0) - 采样率
      Returns:
      the sampled logger - 采样日志记录器

    • sampleByTime

      public static SampledLog.SampledLogger sampleByTime(Duration interval)
      Creates a time-based sampled logger. 创建基于时间的采样日志记录器。
      Parameters:
      interval - the minimum interval between logs - 日志之间的最小间隔
      Returns:
      the sampled logger - 采样日志记录器

    • sampleByCount

      public static SampledLog.SampledLogger sampleByCount(int every)
      Creates a count-based sampled logger. 创建基于计数的采样日志记录器。
      Parameters:
      every - log every Nth message - 每 N 条消息记录一次
      Returns:
      the sampled logger - 采样日志记录器