Class SlowLogCollector

java.lang.Object
cloud.opencode.base.observability.SlowLogCollector
public final class SlowLogCollector extends Object
Bounded slow-operation log collector, inspired by Redis SLOWLOG. 有界慢操作日志收集器，灵感来自 Redis SLOWLOG。

Records operations whose execution time exceeds a configurable threshold. Maintains a bounded, thread-safe log for diagnostics and performance tuning. When the buffer is full, the oldest entry is evicted automatically.

记录执行时间超过可配置阈值的操作。维护有界、线程安全的日志，用于诊断和性能调优。 当缓冲区满时，自动驱逐最旧的条目。

Features | 主要功能:

  • Configurable slow operation threshold - 可配置的慢操作阈值
  • Bounded log buffer with configurable max entries - 可配置最大条目数的有界日志缓冲区
  • Thread-safe concurrent collection - 线程安全的并发收集
  • Statistical aggregation of slow operations - 慢操作的统计聚合

Usage Examples | 使用示例:

// Default: 10ms threshold, 1024 max entries
SlowLogCollector collector = SlowLogCollector.create();

// Custom threshold
SlowLogCollector collector = SlowLogCollector.create(Duration.ofMillis(50));

// Record a slow operation
collector.record("GET", "user:123", Duration.ofMillis(75));

// Query
List<SlowLogCollector.Entry> recent = collector.getEntries(10);
SlowLogCollector.Stats stats = collector.stats();

Performance | 性能特性:

  • Lock-free ConcurrentLinkedDeque for log storage - 无锁 ConcurrentLinkedDeque
  • AtomicLong counters for thread-safe statistics - AtomicLong 线程安全统计
  • Bounded buffer prevents unbounded memory growth - 有界缓冲区防止内存无限增长

Security | 安全性:

  • Thread-safe: Yes (ConcurrentLinkedDeque + AtomicLong) - 线程安全: 是
  • Null-safe: Yes (rejects null parameters) - 空值安全: 是
Since:
JDK 25, opencode-base-observability V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static SlowLogCollector create()
      Creates a collector with the default 10ms threshold and 1024 max entries. 使用默认 10ms 阈值和 1024 最大条目数创建收集器。
      Returns:
      a new collector | 新的收集器

    • create

      public static SlowLogCollector create(Duration threshold)
      Creates a collector with the given threshold and the default 1024 max entries. 使用给定阈值和默认 1024 最大条目数创建收集器。
      Parameters:
      threshold - the slow operation threshold | 慢操作阈值
      Returns:
      a new collector | 新的收集器

    • create

      public static SlowLogCollector create(Duration threshold, int maxEntries)
      Creates a collector with the given threshold and max entries. 使用给定阈值和最大条目数创建收集器。
      Parameters:
      threshold - the slow operation threshold | 慢操作阈值
      maxEntries - the maximum number of entries to retain | 保留的最大条目数
      Returns:
      a new collector | 新的收集器

    • record

      public void record(String operation, String key, Duration elapsed)
      Records an operation if its elapsed time exceeds the configured threshold. 如果操作耗时超过配置的阈值，则记录该操作。

      Captures the current thread name and timestamp automatically. If the buffer is full, the oldest entry is evicted to make room.

      自动捕获当前线程名称和时间戳。如果缓冲区已满，将驱逐最旧的条目。

      Parameters:
      operation - the operation name | 操作名称
      key - the key or resource | 键或资源
      elapsed - the elapsed duration | 耗时时长

    • getEntries

      public List<SlowLogCollector.Entry> getEntries()
      Returns all buffered slow log entries ordered from newest to oldest. 返回所有缓冲的慢日志条目，按从新到旧排序。
      Returns:
      an immutable list of entries | 条目的不可变列表

    • getEntries

      public List<SlowLogCollector.Entry> getEntries(int limit)
      Returns up to limit of the latest slow log entries. 返回最新的最多 limit 条慢日志条目。
      Parameters:
      limit - the maximum number of entries to return | 返回的最大条目数
      Returns:
      an immutable list of the latest entries | 最新条目的不可变列表
      Throws:
      ObservabilityException - if limit is negative | 如果 limit 为负数

    • clear

      public void clear()
      Clears all buffered slow log entries and resets the current-size counter. 清除所有缓冲的慢日志条目并重置当前大小计数器。

      Note: count() (cumulative total) is NOT reset by this method.

      注意：count()（累积总数）不会被此方法重置。

    • count

      public long count()
      Returns the total number of slow operations ever recorded (cumulative, never reset by clear). 返回曾经记录的慢操作总数（累积值，不会被 clear 重置）。
      Returns:
      the cumulative slow operation count | 累积慢操作计数

    • stats

      public SlowLogCollector.Stats stats()
      Computes aggregated statistics for all currently buffered entries. 计算当前缓冲的所有条目的聚合统计信息。
      Returns:
      the statistics, or SlowLogCollector.Stats.EMPTY if no entries are buffered | 统计信息；如果没有缓冲条目则返回 SlowLogCollector.Stats.EMPTY

    • threshold

      public Duration threshold()
      Returns the configured slow operation threshold. 返回配置的慢操作阈值。
      Returns:
      the threshold | 阈值

    • maxEntries

      public int maxEntries()
      Returns the configured maximum number of buffered entries. 返回配置的最大缓冲条目数。
      Returns:
      the max entries limit | 最大条目数限制