Interface IEventProfiler

public interface IEventProfiler
事件总线性能分析器接口

提供深度性能分析和追踪功能,包括事件执行链路追踪、处理器性能剖析、 调用链分析、热点识别等。用于诊断复杂的性能问题和优化系统性能。

与 IEventMetrics 的区别：

  • Metrics：轻量级,持续运行,提供聚合统计数据
  • Profiler：重量级,按需启用,提供详细的执行追踪和调用链
Since:
1.0.0
Version:
1.0.0
Author:
Berry_so
See Also:

  • Method Details

    • enableProfiling

      void enableProfiling(ProfileLevel level)
      启用性能分析

      根据指定的分析级别启动性能追踪。不同级别的开销和详细程度：

      • BASIC：仅记录事件发布和总体执行时间,开销约 1-3%
      • DETAILED：记录每个处理器的执行时间和状态,开销约 5-10%
      • FULL：记录完整调用链、参数和堆栈信息,开销约 15-30%

      注意：性能分析会显著影响系统性能,建议仅在以下情况启用：

      • 开发和测试环境
      • 生产环境的短期问题诊断（启用后应及时关闭）
      • 性能压测和基准测试
      Parameters:
      level - 分析级别
      See Also:

    • disableProfiling

      void disableProfiling()
      禁用性能分析

      停止性能追踪,释放相关资源。已收集的数据会保留, 可通过 generateReport() 等方法查询。

      建议在性能分析完成后立即调用此方法,以恢复系统性能。

    • isProfilingEnabled

      boolean isProfilingEnabled()
      检查性能分析是否已启用
      Returns:
      如果性能分析已启用则返回 true,否则返回 false

    • getProfileLevel

      ProfileLevel getProfileLevel()
      获取当前的性能分析级别
      Returns:
      当前分析级别,如果未启用则返回 null

    • startEventTrace

      EventTrace startEventTrace(Object event, String eventId)
      开始事件追踪

      为一个事件创建追踪记录,记录事件的生命周期：发布→分发→处理→完成。

      仅在启用了性能分析时有效。追踪记录包括：

      • 事件唯一标识
      • 事件类型和内容
      • 开始时间戳
      • 调用线程信息

      必须与 endEventTrace(java.lang.String, boolean, java.util.List<java.lang.Exception>) 配对使用。

      Parameters:
      event - 被追踪的事件对象
      eventId - 事件唯一标识符
      Returns:
      事件追踪对象

    • endEventTrace

      void endEventTrace(String eventId, boolean success, List<Exception> exceptions)
      结束事件追踪

      标记事件处理完成,记录结束时间和执行结果。

      Parameters:
      eventId - 事件唯一标识符,与 startEventTrace(java.lang.Object, java.lang.String) 中的 eventId 对应
      success - 事件是否处理成功
      exceptions - 处理过程中发生的异常列表,如果没有异常则为空列表

    • recordHandlerExecution

      void recordHandlerExecution(HandlerRegistration handler, long executionTimeMs, boolean success, Exception exception)
      记录处理器执行信息

      在事件追踪上下文中记录单个处理器的执行详情,包括：

      • 处理器标识和优先级
      • 执行时间
      • 成功/失败状态
      • 异常信息（如果有）
      • 执行线程（同步/异步）
      Parameters:
      handler - 执行的处理器注册信息
      executionTimeMs - 执行耗时（毫秒）
      success - 是否执行成功
      exception - 如果执行失败,传入异常对象；成功则传 null

    • generateReport

      PerformanceReport generateReport()
      生成性能分析报告

      基于收集的追踪数据生成综合性能报告,包括：

      • 总体性能指标（吞吐量、平均响应时间、成功率）
      • 按事件类型的性能统计
      • 慢处理器排行
      • 热点事件和热点处理器
      • 异常统计和错误率
      • 性能趋势分析
      • 优化建议

      报告生成可能耗时较长（取决于追踪数据量）,建议异步调用。

      Returns:
      性能分析报告对象

    • createSnapshot

      PerformanceSnapshot createSnapshot()
      创建性能快照

      捕获当前时刻的系统性能状态,用于：

      • 对比不同时间点的性能变化
      • 记录优化前后的性能差异
      • 导出性能数据用于离线分析

      快照包含当前所有追踪数据的副本,不会随后续操作改变。

      Returns:
      性能快照对象

    • getTracesInTimeRange

      List<EventTrace> getTracesInTimeRange(LocalDateTime start, LocalDateTime end)
      获取指定时间范围内的事件追踪记录

      查询在给定时间段内发布的所有事件的追踪记录。

      用于：

      • 分析特定时间段的系统行为
      • 定位问题发生的时间窗口
      • 生成时间序列性能图表
      Parameters:
      start - 开始时间（包含）
      end - 结束时间（包含）
      Returns:
      时间范围内的事件追踪记录列表,按时间升序排列

    • getSlowEventTraces

      List<EventTrace> getSlowEventTraces(long thresholdMs)
      获取慢事件追踪记录

      返回执行时间超过指定阈值的事件追踪列表,按执行时间降序排列。

      用于：

      • 识别性能瓶颈事件
      • 找出需要优化的处理逻辑
      • 评估是否需要异步化处理
      Parameters:
      thresholdMs - 时间阈值（毫秒）,执行时间超过此值的事件会被返回
      Returns:
      慢事件追踪记录列表,按执行时间从长到短排序

    • getFailedEventTraces

      List<EventTrace> getFailedEventTraces()
      获取失败的事件追踪记录

      返回处理过程中发生异常的事件追踪列表,按时间倒序排列。

      用于：

      • 诊断错误原因
      • 分析失败模式
      • 评估系统稳定性
      Returns:
      失败事件的追踪记录列表,包含详细的异常信息

    • getCallChainRecords

      Map<String,CallChainRecord> getCallChainRecords()
      获取调用链记录

      返回所有事件的完整调用链信息,包括：

      • 事件触发链（A事件触发B事件触发C事件）
      • 处理器调用顺序
      • 同步/异步执行关系
      • 父子事件关系

      用于：

      • 理解复杂的事件交互流程
      • 发现循环依赖
      • 优化事件处理顺序

      注意：调用链分析需要启用

      invalid reference 
      ProfileLevel#FULL
      级别。
      Returns:
      事件标识到其调用链记录的映射

    • getHotspotHandlers

      List<HotspotInfo> getHotspotHandlers(int limit)
      获取热点处理器列表

      返回调用频率最高或执行时间占比最大的处理器列表,按热度降序排列。

      热度计算公式：调用次数 × 平均执行时间

      用于：

      • 识别需要优先优化的处理器
      • 评估系统负载分布
      • 指导性能优化方向
      Parameters:
      limit - 返回的最大数量,必须大于 0
      Returns:
      热点处理器信息列表,按热度从高到低排序
      Throws:
      IllegalArgumentException - 如果 limit 小于等于 0

    • cleanup

      void cleanup()
      清理追踪数据

      删除所有已收集的追踪记录,释放内存。通常在以下情况使用：

      • 长时间运行后防止内存溢出
      • 生成报告后清理历史数据
      • 重新开始性能分析前清空旧数据

      注意：

      • 此操作不可逆,会丢失所有追踪数据
      • 不会关闭性能分析,新事件仍会被追踪
      • 建议在清理前先调用 generateReport() 保存报告