本指南基于 Pulse 1.11.0 的源代码。示例中的
ReportGenerated 事件是用于说明的假想类。在实际的扩展包中,请替换为你自己的事件。处理流程
记录器接收到事件后,会把记录累积到 Pulse 的缓冲区中。缓冲区会在采集(ingest)时统一保存。创建记录器
记录器在listen 属性中声明要订阅的事件,并在 record() 方法中实现处理。下面的示例记录扩展包分发的 ReportGenerated 事件。假设该事件拥有 $type 和 $durationMs 属性。
Ignores 和 Sampling trait 会读取下文介绍的 ignore 和 sample_rate 配置。
在应用中注册记录器
在应用的config/pulse.php 的 recorders 数组中注册记录器。以记录器的类名作为键,并以启用标志和配置作为值。
pulse.enabled 开启时,PulseServiceProvider 会读取 pulse.recorders 并注册记录器。enabled 为 false 的记录器不会被注册。与其由扩展包自动改写此配置,不如在安装说明中展示配置示例更安全。
汇总的种类
Pulse::record() 返回一个 Entry。链式调用 count()、min()、max()、sum() 或 avg() 后,对应的汇总会保存到 pulse_aggregates 中。
min()、max()、sum() 和 avg() 会使用 value 进行计算。仅使用 count() 时不需要 value。
当事件触发非常频繁时,onlyBuckets() 可以减少 pulse_entries 的行数。
保存字符串值
如果要保存最新状态之类的字符串而不是汇总数值,请使用Pulse::set()。该值会保存到 pulse_values 表中。
value 必须以 string 形式传入。
延迟耗时处理
传给Pulse::lazy() 的闭包不会立即执行,而是在 Pulse 采集数据时执行。当记录比较耗时、希望在发送响应之后再执行时使用。
记录已认证用户
需要已认证用户的标识符时,请使用Pulse::resolveAuthenticatedUserId()。没有已认证用户时返回 null。
排除、采样与过滤
可以使用以下四种方式减少记录量:ignore配置:当传给shouldIgnore()的值与任一正则表达式匹配时跳过记录。在上面的示例中,$event->type与/^debug_/匹配的事件会被跳过。sample_rate配置:由shouldSample()检查。1记录所有事件,0.1大约记录 10%。Pulse::ignore():在回调内禁用记录,并返回回调的结果。Pulse::filter():在保存前接收每个Entry或Value,只保存返回true的项目。
异常处理
Pulse 会用rescue() 包裹记录器的处理和采集。记录器内抛出的异常不会传到应用中。如果没有设置 handleExceptionsUsing(),异常会被静默丢弃。如需报告异常,请在应用中进行配置。
测试
测试记录器时,可以分发事件、调用Pulse::ingest(),然后检查保存的行。下面的示例由 Pulse 的源代码推导而来,尚未实际运行。请确保测试环境中 pulse.enabled 已开启。
键的设计
key 是汇总的单位。如果使用用户 ID 或 URL 这类会无限增长的值,数据量会增加,汇总结果也会难以阅读。key 请使用事件类型或进程名称这类种类有限的值。