Rules / Types, classes & roles / basic

Telemetry Reference

Collect performance state for analysis

What it is #

Position in the hierarchy #

Inherits from—
Does—
Inherited byTelemetry::Period

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

routine T #

sub T()

Shortcut for Telemetry.new. It is exported by default. Since the Telemetry class also provides an Associative interface, one can easily interpolate multiple values in a single statement:

routine snap #

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

Returns Nil.

The snap subroutine is shorthand for creating a new Telemetry object and pushing it to an array for later processing. The subroutine is exported by default. From release 2017.11, one can give a custom array @s to push to: If no array is specified, it will use an internal array for convenience. From release 2019.07, snap accepts a positional argument $message of type Str, which will

routine snapper #

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

Returns Nil.

The snapper routine starts a separate thread that will call snap repeatedly until the end of program. It is exported by default. By default, it will call snap every 0.1 second. The only positional parameter is taken to be the delay between snaps. Please see the snapper module for externally starting a snapper without having to change the code. Simply adding -Msnapper as a command line

routine periods #

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

Returns Seq.

The periods subroutine processes an array of Telemetry objects and generates a Seq of Telemetry::Period objects out of that. It is exported by default. If no array is specified, it will use the internal array of snap without parameters and will reset that array upon completion (so that new snaps can be added again). If only one snap was done, another snap will be done to create at least

routine report #

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

The report subroutine generates a report about an array of Telemetry objects. It is exported by default. These can have been created by regularly calling snap, or by having a snapper running. If no positional parameter is used, it will assume the internal array to which the parameterless snap pushes. Below are the additional named parameters of report. Specify the names of the columns to be included in the report. Names can

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

6 no-output

class Telemetry { }

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

.<cpu wallclock>.say for periods(@t);

# OUTPUT:
# ====================
# (164 / 160)
# (23 / 21)
# (17 / 17)
# (15 / 16)
# (29 / 28)

Not executed: the documentation states no expected output for this example.

use Telemetry;
for ^5 {
snap;
LAST snap;
}
say .<cpu wallclock>.join(" / ") for periods;

# OUTPUT:
# ====================
# 172 / 168
# 24 / 21
# 17 / 18
# 17 / 16
# 27 / 27

Not executed: the documentation states no expected output for this example.

=begin code :lang<text>
wallclock util% max-rss gw gtc tw ttc aw atc
=end code

Not executed: the documentation states no expected output for this example.