Interface IEventMetrics

public interface IEventMetrics
事件总线性能指标接口

提供事件总线的性能监控和统计功能，包括事件发布/处理统计、处理器性能分析、 错误追踪、热点分析等。所有指标数据可用于性能优化、问题诊断和监控告警。

Since:
1.0.0
Version:
1.0.0
Author:
Berry_so
See Also:

  • Method Details

    • recordEventPublished

      void recordEventPublished(Class<?> eventType)
      记录事件发布

      当事件通过 EventBus.publish() 发布时调用，用于统计：

      • 特定事件类型的发布次数
      • 总体事件发布频率（TPS）
      • 事件类型分布
      Parameters:
      eventType - 发布的事件类型

    • recordEventProcessed

      void recordEventProcessed(Class<?> eventType, long executionTimeMs)
      记录事件处理完成

      当某个事件被处理器完整处理后调用，用于统计：

      • 事件处理成功次数
      • 处理耗时（平均值、最大值、最小值）
      • 处理器吞吐量
      Parameters:
      eventType - 处理的事件类型
      executionTimeMs - 处理耗时（毫秒）

    • recordEventFailed

      void recordEventFailed(Class<?> eventType, Exception error)
      记录事件处理失败

      当事件处理过程中抛出异常时调用，用于统计：

      • 失败次数和失败率
      • 异常类型分布
      • 错误堆栈信息（用于诊断）

      错误信息会被记录到 ErrorStats 中，可通过 getErrorStats() 查询。

      Parameters:
      eventType - 处理失败的事件类型
      error - 发生的异常

    • recordHandlerInvocation

      void recordHandlerInvocation(HandlerRegistration handler, long executionTimeMs, boolean success)
      记录处理器调用

      每次调用事件处理器时记录，用于统计：

      • 处理器调用次数
      • 处理器执行时间统计
      • 处理器成功率
      • 识别慢处理器和热点处理器
      Parameters:
      handler - 被调用的处理器注册信息
      executionTimeMs - 执行耗时（毫秒）
      success - 是否执行成功（true 表示成功，false 表示抛出异常）

    • recordError

      void recordError(String context, Exception error)
      记录错误

      记录事件总线框架层面的错误（非业务处理器错误），如：

      • 处理器注册失败
      • 线程池异常
      • 配置错误
      • 系统资源不足
      Parameters:
      context - 错误发生的上下文信息（如 "handler-registration"、"thread-pool"）
      error - 发生的异常

    • getOverallMetrics

      OverallMetrics getOverallMetrics()
      获取总体性能指标

      返回事件总线的全局统计信息，包括：

      • 总事件发布数和处理数
      • 平均处理时间和吞吐量
      • 总体成功率和失败率
      • 当前活跃处理器数量
      • 系统运行时长
      Returns:
      总体性能指标对象

    • getEventTypeMetrics

      Map<Class<?>,EventTypeMetrics> getEventTypeMetrics()
      获取按事件类型分组的性能指标

      返回每个事件类型的详细统计信息，包括：

      • 发布次数和处理次数
      • 平均处理时间、最大/最小处理时间
      • 成功率和失败次数
      • 处理器数量

      用于：

      • 识别高频事件类型
      • 找出性能瓶颈事件
      • 分析事件处理分布
      Returns:
      事件类型到其性能指标的映射，Key 为事件类型，Value 为该类型的统计信息

    • getHandlerMetrics

      Map<String,HandlerMetrics> getHandlerMetrics()
      获取按处理器分组的性能指标

      返回每个处理器的详细统计信息，包括：

      • 调用次数和成功次数
      • 平均执行时间、最大/最小执行时间
      • 失败次数和失败率
      • 最后执行时间

      用于：

      • 识别慢处理器
      • 找出频繁失败的处理器
      • 优化处理器性能
      Returns:
      处理器标识到其性能指标的映射，Key 为处理器唯一标识（通常是类名+方法名）， Value 为该处理器的统计信息

    • getTimeWindowStats

      TimeWindowStats getTimeWindowStats()
      获取时间窗口统计

      返回不同时间窗口（如最近 1 分钟、5 分钟、15 分钟）内的性能统计，包括：

      • 每个时间窗口的事件处理数量
      • 平均响应时间趋势
      • 吞吐量变化
      • 错误率趋势

      用于：

      • 监控系统负载变化
      • 识别性能退化
      • 生成性能趋势图表
      Returns:
      时间窗口统计对象

    • getErrorStats

      ErrorStats getErrorStats()
      获取错误统计

      返回详细的错误统计信息，包括：

      • 总错误数和错误率
      • 按错误类型分组的统计
      • 最近的错误记录（含堆栈信息）
      • 错误发生的时间分布

      用于：

      • 问题诊断和定位
      • 监控系统稳定性
      • 触发告警
      Returns:
      错误统计对象

    • getHotspotEvents

      List<HotspotEvent> getHotspotEvents(int limit)
      获取热点事件列表

      返回发布频率最高的事件类型列表，按发布次数降序排列。

      用于：

      • 识别系统中最常用的事件
      • 优化高频事件的处理性能
      • 评估事件使用合理性
      Parameters:
      limit - 返回的最大数量，必须大于 0
      Returns:
      热点事件列表，按发布频率从高到低排序
      Throws:
      IllegalArgumentException - 如果 limit 小于等于 0

    • getSlowHandlers

      List<SlowHandler> getSlowHandlers(int limit)
      获取慢处理器列表

      返回平均执行时间最长的处理器列表，按平均执行时间降序排列。

      用于：

      • 识别性能瓶颈处理器
      • 指导性能优化方向
      • 评估是否需要异步处理
      Parameters:
      limit - 返回的最大数量，必须大于 0
      Returns:
      慢处理器列表，按平均执行时间从长到短排序
      Throws:
      IllegalArgumentException - 如果 limit 小于等于 0

    • reset

      void reset()
      重置所有统计指标

      清除所有已收集的性能指标数据，将计数器归零。 通常在以下情况使用：

      • 系统维护后重新开始统计
      • 定期归档历史数据后重置
      • 测试前清理环境

      注意：此操作不可逆，会丢失所有历史统计数据。 建议在重置前先导出或归档重要数据。