class Telemetry::Period is Telemetry { }

Note: This class is a Rakudo-specific feature and not standard Raku.

# basic usage 
use Telemetry;
my $t0 = Telemetry.new;
# execute some code 
my $t1 = Telemetry.new;
my $period = $t1 - $t0;  # creates Telemetry::Period object 
say "Code took $period<wallclock> microseconds to execute";

A Telemetry::Period object contains the difference between two Telemetry objects. It is generally not created by calling .new, but it can be if needed. For all practical purposes, it is the same as the Telemetry object, but the meaning of the values is different (and the values are generally much smaller, as they usually are the difference of two big values of the Telemetry objects from which it was created).

Type Graph

Expand above chart

Routines supplied by role Associative

Telemetry::Period does role Associative, which provides the following routines:

(Associative) method of

Defined as:

method of()

Associative is actually a parameterized role which can use different classes for keys and values. As seen at the top of the document, by default it coerces to Str for the key and uses a very generic Mu for value.

my %any-hash;
say %any-hash.of;#  OUTPUT: «(Mu)␤»

The value is the first parameter you use when instantiating Associative with particular classes:

class DateHash is Hash does Associative[Cool,DateTime] {};
my %date-hash := DateHash.new;
say %date-hash.of; # OUTPUT: «(Cool)␤»

(Associative) method keyof

Defined as:

method keyof()

Returns the parameterized key used for the Associative role, which is Any coerced to Str by default. This is the class used as second parameter when you use the parameterized version of Associative.

my %any-hash;
%any-hash.keyof; #OUTPUT: «(Str(Any))␤»

(Associative) method AT-KEY

method AT-KEY(\key)

Should return the value / container at the given key.

(Associative) method EXISTS-KEY

method EXISTS-KEY(\key)

Should return a Bool indicating whether the given key actually has a value.

(Associative) method STORE

method STORE(\values, :$initialize)

This method should only be supplied if you want to support the:

my %h is Foo = a => 42, b => 666;

syntax for binding your implementation of the Associative role.

Should accept the values to (re-)initialize the object with, which either could consist of Pairs, or separate key/value pairs. The optional named parameter will contain a True value when the method is called on the object for the first time. Should return the invocant.

Routines supplied by class Telemetry

Telemetry::Period inherits from class Telemetry, which provides the following routines:

(Telemetry) 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:

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

(Telemetry) routine snap

multi sub snap(--> Nil)
multi sub snap(@s --> Nil)

The snap subroutine is shorthand for creating a new Telemetry object and pushing it to an array for later processing. It is exported by default.

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

If no array is specified, it will use an internal array for convenience.

(Telemetry) routine snapper

sub snapper($sleep = 0.1, :$stop, :$reset --> 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 parameter, will then start a snapper for you.

(Telemetry) routine periods

multi sub periods( --> Seq)
multi sub periods(@s --> 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.

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

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).

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

If only one snap was done, another snap will be done to create at least one Telemetry::Period object.

(Telemetry) routine report

multi sub 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.

:columns

Specify the names of the columns to be included in the report. Names can be specified with the column name (e.g. gw). If not specified, defaults to what is specified in the RAKUDO_REPORT_COLUMNS environment variable. If that is not set either, defaults to:

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

:header-repeat

Specifies after how many lines the header should be repeated in the report. If not specified, defaults to what is specified in the RAKUDO_REPORT_HEADER_REPEAT environment variable. If that is not set either, defaults to 32.

:legend

Specifies whether a legend should be added to the report. If not specified, defaults to what is specified in the RAKUDO_REPORT_LEGEND environment variable. If that is not set either, defaults to True.

If there are snaps available in the internal array at the end of the program, then report will be automatically generated and printed on STDERR.