class Telemetry { }

注意：此类是 Rakudo 特有功能，不是标准 Raku。

创建时，Telemetry 对象包含虚拟机当前状态的各个方面的快照。这本身很有用，但通常需要两个快照来表示差异（这是一个 Telemetry::Period 对象）。

Telemetry 对象实际上是不同“仪器”拍摄的一系列快照的集合。默认情况下，Telemetry::Instrument::Usage 和 Telemetry::Instrument::ThreadPool 仪器处于激活状态。

Telemetry（和 Telemetry::Period）对象也是 Associative。这意味着你可以将 Telemetry 对象视为只读 Hash，其中仪器的所有数据值都是键。

你可以通过设置 $*SAMPLER 动态变量（这是一个 Telemetry::Sampler 对象）来确定 Telemetry 应使用哪些仪器。

目前，Rakudo 核心支持以下仪器

• Telemetry::Instrument::Usage

按字母顺序提供：cpu、cpu-sys、cpu-user、cpus、id-rss、inb、invcsw、is-rss、ix-rss、majf、max-rss、minf、mrcv、msnd、nsig、nswp、volcsw、outb、util% 和 wallclock。有关这些数据值的含义的完整文档，请参阅 Telemetry::Instrument::Usage。

• Telemetry::Instrument::Thread

按字母顺序提供：tad、tcd、thid、tjd、tsd 和 tys。有关这些数据值的含义的完整文档，请参阅 Telemetry::Instrument::Thread。

• Telemetry::Instrument::ThreadPool

按字母顺序提供：atc、atq、aw、gtc、gtq、gw、s、ttc、ttq 和 tw。有关这些数据值的含义的完整文档，请参阅 Telemetry::Instrument::ThreadPool。

• Telemetry::Instrument::AdHoc

本身不提供任何数据：必须指明要监视哪些变量，然后这些变量将作为仪器上具有相同名称的方法提供。

例程 T§

sub T()

Telemetry.new 的快捷方式。它默认导出。由于 Telemetry 类还提供 Associative 接口，因此可以轻松地在单个语句中内插多个值

use Telemetry;
say "Used {T<max-rss cpu>} (KiB CPU) so far";

例程 snap§

multi snap(--> Nil)
multi snap(Str:D $message --> Nil)
multi snap(Str $message = "taking heap snapshot...", :$heap!)
multi snap(@s --> Nil)

snap 子例程是创建新的 Telemetry 对象并将其推送到数组以供以后处理的简写。它默认导出。从 2021.12 版本开始，如果为其提供了 :$heap 关联参数，它将返回存储快照的文件名。

use Telemetry;
my @t;
for ^5 {
    snap(@t);
    # do some stuff 
    LAST snap(@t);
}

如果没有指定数组，它将出于方便考虑使用内部数组。

例程 snapper§

sub snapper($sleep = 0.1, :$stop, :$reset --> Nil)

snapper 例程启动一个单独的线程，该线程将重复调用 snap 直到程序结束。它默认导出。

默认情况下，它将每 0.1 秒调用一次 snap。唯一的定位参数被视为 snap 之间的延迟。

请参阅 snapper 模块，了解如何在不更改代码的情况下从外部启动 snapper。只需将 -Msnapper 作为命令行参数添加，即可为您启动 snapper。

例程 periods§

multi periods( --> Seq)
multi periods(@s --> Seq)

periods 子例程处理一个 Telemetry 对象数组，并从中生成一个 Seq 的 Telemetry::Period 对象。它默认导出。

.<cpu wallclock>.say for periods(@t);
 
# OUTPUT: 
# ==================== 
# (164 / 160) 
# (23 / 21) 
# (17 / 17) 
# (15 / 16) 
# (29 / 28) 

如果没有指定数组，它将使用 snap 的内部数组，不带参数 并且 在完成时将重置该数组（以便可以再次添加新的 snap）。

use Telemetry;
for ^5 {
    snap;
    LAST snap;
}
say .<cpu wallclock>.join(" / ") for periods;
 
# OUTPUT: 
# ==================== 
# 172 / 168 
# 24 / 21 
# 17 / 18 
# 17 / 16 
# 27 / 27 

如果只执行了一个 snap，则将执行另一个 snap 以至少创建一个 Telemetry::Period 对象。

例程 report§

multi report(:@columns, :$legend, :$header-repeat, :$csv, :@format)

report 子例程生成有关 Telemetry 对象数组的报告。它默认导出。这些可以通过定期调用 snap 创建，或者通过运行 snapper 创建。如果没有使用定位参数，它将假定无参数 snap 推送到的内部数组。

以下是 report 的其他命名参数。

• :columns

指定要包含在报告中的列的名称。名称可以使用列名称指定（例如 gw）。如果未指定，则默认为 RAKUDO_REPORT_COLUMNS 环境变量中指定的内容。如果也没有设置，则默认为

wallclock util% max-rss gw gtc tw ttc aw atc

• :header-repeat

指定在报告中重复标题的次数。如果未指定，则默认为 RAKUDO_REPORT_HEADER_REPEAT 环境变量中指定的内容。如果也没有设置，则默认为 32。

• :legend

指定是否应将图例添加到报告中。如果未指定，则默认为 RAKUDO_REPORT_LEGEND 环境变量中指定的内容。如果也没有设置，则默认为 True。

如果在程序结束时内部数组中有可用的 snap，则将自动生成 report 并打印在 STDERR 上。

模块 snapper§

启动一个线程，获取重复的系统状态快照。

此模块不包含子例程或方法或任何内容。它旨在作为启动 Telemetry 模块的 snapper 子例程的快捷方式，允许在无需更改程序的情况下获取程序执行的快照。只需使用 -Msnapper 加载模块即可完成启动 snapper 所需的所有操作，并在程序完成后在 STDERR 上打印报告。

RAKUDO_SNAPPER 环境变量可以设置为指示快照之间的时间。如果未指定，它将默认为 0.1 秒。

snapper 模块假定进程有序关闭。终止进程（例如通过按 Control-c）不会生成报告。

模块 safe-snapper§

自 Rakudo 编译器 2021.09 版本起可用。

此模块提供了一个对 snapper 模块的安全的替代：通过按 Control-c 终止进程将生成报告。它能够通过安装 信号处理程序 来实现此目的，这可能会干扰交互式程序的正常运行。

以任何其他方式终止进程不会生成报告。

类型图§