Performance data over a period
Note: This class is a Rakudo-specific feature and not standard Raku.
# basic usageuse Telemetry;my = Telemetry.new;# execute some codemy = Telemetry.new;my = - ; # creates Telemetry::Period objectsay "Code took $period<wallclock> microseconds to execute";
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).
Telemetry::Period does role Associative, which provides the following routines:
Associative, as the definition above shows, 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 the key to
Str and uses a very generic
Mu for value.
my ;say .of; # OUTPUT: «(Mu)␤»
The value is the first parameter you use when instantiating
Associative with particular classes:
is Hash does Associative[Cool,DateTime] ;my := DateHash.new;say .of; # OUTPUT: «(Cool)␤»
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 ;.keyof; # OUTPUT: «(Str(Any))␤»
Should return the value / container at the given key.
;say What.new; # OUTPUT: «42␤»
Should return a
Bool indicating whether the given key actually has a value.
method STORE(\values, :)
This method should only be supplied if you want to support the:
my is Foo = a => 42, b => 666;
syntax for binding your implementation of the
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.
Telemetry::Period inherits from class Telemetry, which provides the following routines:
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 (KiB CPU) so far";
multi sub snap(--> Nil)multi sub snap( --> Nil)
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 ;for ^5
If no array is specified, it will use an internal array for convenience.
sub snapper( = 0.1, :, : --> Nil)
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
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.
multi sub periods( --> Seq)multi sub periods( --> Seq)
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();# 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 ^5say .<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
multi sub report(:, :, :, :, :)
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
Below are the additional named parameters of
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
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.
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