First draft of Telemetry documentation

Telemetry.pod6

=begin pod

=TITLE class Telemetry

=SUBTITLE Collect performance state for analysis

    class Telemetry { }
    class Telemetry::Period { }

On creation, a C<Telemetry> object contains a snapshot of the current state
of the virtual machine.  This is in itself useful, but generally one needs
two snapshots for the difference (which is a C<Telemetry::Period> object).

=for information gathered

=item cpu-user

The amount of CPU time spent on executing user code since start of program
(in microseconds).

=item cpu-sys

The amount of CPU time spent in system overhead since start of program
(in microseconds).
  
=item wallclock

The time the program has been executing (in microseconds).

=back

=begin code
use Telemetry;
# basic usage
my $t0 = Telemetry.new;
# execute some code
my $t1 = Telemetry.new;
my $period = $t1 - $t0;
say "Code took $period (cpu / wallclock) microseconds to execute";
=end

=head1 Methods

=head2 method cpu

Returns the total amount of CPU time spent since start of program (in
microseconds).

=head2 method cpu-user

Returns the amount of CPU time spent on executing user code since start of
program (in microseconds).

=head2 method cpu-sys

Returns the amount of CPU time spent in system overhead since start of program
(in microseconds).
  
=head2 method wallclock

Returns the number of seconds the program has been executing (in microseconds).

=head2 method gist / method Str

Returns a string representation in the form "cpu / wallclock".

=head1 Subroutines

=head2 routine snap

The C<snap> subroutine is shorthand for creating a new C<Telemetry> object and
pushing it to an array for later processing.

=begin code
use Telemetry;
my @t;
for ^5 {
    snap(@t);
    LAST snap(@t);
}
=end

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

=head2 routine periods

The C<periods> subroutine processes an array of C<Telemetry> objects and
generates a L<Seq> of C<Telemetry::Period> objects out of that.

=begin code
.say for periods(@t);
====================
164 / 160
23 / 21
17 / 17
15 / 16
29 / 28
=end

If no array is specified, it will use the internal array of C<snap> without
parameters B<and> will reset that array upon completion (so that new C<snap>s
can be added again).

=begin code
use Telemetry;
for ^5 {
    snap;
    LAST snap;
}
.say for periods;
====================
172 / 168
24 / 21
17 / 18
17 / 16
27 / 27
=end

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

If there are C<snap>s available in the internal array, then C<periods> will be
automatically called, C<say>ing each of its elements.

=head1 See Also

L<Telemetry::Period>

=end pod