Skip to content

Commit

Permalink
Update basic Telemetry documentation
Browse files Browse the repository at this point in the history 
More on the separate instruments to follow
  • Loading branch information
@lizmat
lizmat committed Dec 17, 2017
1 parent 287bd03 commit 5c0d780
Showing 1 changed file with 43 additions and 178 deletions.
221 changes: 43 additions & 178 deletions doc/Type/Telemetry.pod6
View file
Expand Up @@ -9,188 +9,54 @@
B<Note: > This class is a Rakudo-specific feature and not standard Perl 6.
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
On creation, a C<Telemetry> object contains a snapshot of various aspects 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
L<Telemetry::Period|/type/Telemetry::Period> object).
The following data is available both as a method on a C<Telemetry> type object,
as well as on an instantiated C<Telemetry> object. When loading it as a
module with the C<:COLUMNS> named parameter, these are also available as
standalone subroutines.
The Telemetry object is really a collection of snapshots taken by different
"instruments". By default, the
L<Telemetry::Instrument::Usage|/type/Telemetry::Instrument::Usage>
and L<Telemetry::Instrument::ThreadPool|/type/Telemetry::Instrument::ThreadPool>
instruments are activated.
=begin code
use Telemetry; # imports default subroutines: T, snap, snapper, periods, report
use Telemetry :COLUMNS; # imports all of the possible columns of report
use Telemetry < cpu wallclock snap >; # only imports cpu, wallclock and snap
=end code
Apart from this data, other fields in the POSIX C<getrusage> struct are also
collected, but are probably not in use on most operating systems and will thus
always give 0. These are (column names in parenthesis):
id-rss, inblock (inb), invcw, is-rss, ix-rss, maj-flt (aft), min-flt (ift),
msgrcv (mrc), msgsnd (msd), nsignals (ngs), nswap (nsw), nvcsw (vcs),
outblock (oub).
Please consult the C<getrusage> manual information for the meaning of these
fields.
=head1 Methods
=head2 method affinity-tasks-completed
=for code :preamble<use Telemetry;>
multi method affinity-tasks-completed(Telemetry:U: --> Int)
multi method affinity-tasks-completed(Telemetry:D: --> Int)
Available data. Column name: C<atc>.
Returns the number of tasks completed in affinity threads in this period.
=head2 method affinity-tasks-queued
=for code :preamble<use Telemetry;>
multi method affinity-tasks-queued(Telemetry:U: --> Int)
multi method affinity-tasks-queued(Telemetry:D: --> Int)
Available data. Column name: C<atq>.
Returns the number of tasks queued for execution in affinity threads.
=head2 method affinity-workers
=for code :preamble<use Telemetry;>
multi method affinity-workers(Telemetry:U: --> Int)
multi method affinity-workers(Telemetry:D: --> Int)
Available data. Column name: C<aw>.
Returns the number of affinity threads added in this period.
=head2 method cpu
=for code :preamble<use Telemetry;>
multi method cpu(Telemetry:U: --> Int)
multi method cpu(Telemetry:D: --> Int)
Available data.
Returns the total amount of CPU time of this period (in microseconds),
essentially the sum of C<cpu-user> and C<cpu-sys>.
=head2 method cpu-user
=for code :preamble<use Telemetry;>
multi method cpu-user(Telemetry:U: --> Int)
multi method cpu-user(Telemetry:D: --> Int)
Available data.
Returns the amount of CPU time spent on executing user code of this period
(in microseconds).
=head2 method cpu-sys
=for code :preamble<use Telemetry;>
multi method cpu-sys(Telemetry:U: --> Int)
multi method cpu-sys(Telemetry:D: --> Int)
Available data.
Returns the amount of CPU time spent in system overhead of this period (in
microseconds).
=head2 method general-tasks-completed
=for code :preamble<use Telemetry;>
multi method general-tasks-completed(Telemetry:U: --> Int)
multi method general-tasks-completed(Telemetry:D: --> Int)
Available data. Column name: C<gtc>.
Returns the number of tasks completed in general worker threads in this period.
=head2 method general-tasks-queued
=for code :preamble<use Telemetry;>
multi method general-tasks-queued(Telemetry:U: --> Int)
multi method general-tasks-queued(Telemetry:D: --> Int)
Available data. Column name: C<gtq>.
Returns the number of tasks queued for execution in general worker threads
in this period.
=head2 method general-workers
=for code :preamble<use Telemetry;>
multi method general-workers(Telemetry:U: --> Int)
multi method general-workers(Telemetry:D: --> Int)
Available data. Column name: C<gw>.
Returns the number of general worker threads that were added in this period.
=head2 method max-rss
=for code :preamble<use Telemetry;>
multi method max-rss(Telemetry:U: --> Int)
multi method max-rss(Telemetry:D: --> Int)
Available data.
Returns the maximum resident set size increase for this period (in KiB).
=head2 method supervisor
=for code :preamble<use Telemetry;>
multi method supervisor(Telemetry:U: --> Int)
multi method supervisor(Telemetry:D: --> Int)
Available data. Column name: C<s>.
Returns The number of supervisor threads running, usually C<0> or C<1>.
=head2 method timer-tasks-completed
=for code :preamble<use Telemetry;>
multi method timer-tasks-completed(Telemetry:U: --> Int)
multi method timer-tasks-completed(Telemetry:D: --> Int)
Available data. Column name: C<ttc>.
Returns the number of tasks completed in timer worker threads.
=head2 method timer-tasks-queued
=for code :preamble<use Telemetry;>
multi method timer-tasks-queued(Telemetry:U: --> Int)
multi method timer-tasks-queued(Telemetry:D: --> Int)
The Telemetry (and Telemetry::Period) object also C<Associative>. This means
that you can treat a Telemetry object as a read-only C<Hash>, with all of the
data values of the instruments as keys.
Available data. Column name: C<ttq>.
You can determine which instruments C<Telemetry> should use by setting the
C<$*SAMPLER> dynamic variable, which is a
L<Telemetry::Sampler|/type/Telemetry::Sampler> object.
Returns the number of tasks queued for execution in timer worker threads.
Currently, the following instruments are supported by the Rakudo core:
=head2 method timer-workers
=item Telemetry::Instrument::Usage
=for code :preamble<use Telemetry;>
multi method timer-workers(Telemetry:U: --> Int)
multi method timer-workers(Telemetry:D: --> Int)
Provides (in alphabetical order): C<cpu>, C<cpu-sys>, C<cpu-user>, C<cpus>,
C<id-rss>, C<inb>, C<invcsw>, C<is-rss>, C<ix-rss>, C<majf>, C<max-rss>,
C<minf>, C<mrcv>, C<msnd>, C<nsig>, C<nswp>, C<volcsw>, C<outb>, C<util%>
and C<wallclock>. For complete documentation of the meaning of these data
values, see L<Telemetry::Instrument::Usage|/type/Telemetry::Instrument::Usage>.
Available data. Column name: C<tw>.
=item Telemetry::Instrument::Thread
Returns the number of timer worker threads.
Provides (in alphabetical order): C<tad>, C<tcd>, C<thid>, C<tjd>, C<tsd> and
C<tys>. For complete documentation of the meaning of these data values, see
L<Telemetry::Instrument::Thread|/type/Telemetry::Instrument::Thread>.
=head2 method wallclock
=item Telemetry::Instrument::ThreadPool
=for code :preamble<use Telemetry;>
multi method wallclock(Telemetry:U: --> Int)
multi method wallclock(Telemetry:D: --> Int)
Provides (in alphabetical order): C<atc>, C<atq>, C<aw>, C<gtc>, C<gtq>, C<gw>,
C<s>, C<ttc>, C<ttq> and C<tw>. For complete documentation of the meaning of
these data values, see
L<Telemetry::Instrument::ThreadPool|/type/Telemetry::Instrument::ThreadPool>.
Available data.
=item Telemetry::Instrument::AdHoc
Returns the time the program has been executing (in microseconds).
Does not provide any data by itself: one must indicate which variables are
to be monitored, which will then become available as methods with the same name
on the instrument. For complete documentation, see
L<Telemetry::Instrument::AdHoc|/type/Telemetry::Instrument::AdHoc>.
=head2 routine T
Expand Down Expand Up @@ -249,15 +115,15 @@ generates a L<Seq> of C<Telemetry::Period> objects out of that. It is exported
by default.
=begin code :preamble<my @t;use Telemetry;>
.say for periods(@t);
.<cpu wallclock>.say for periods(@t);
# OUTPUT:
# ====================
# 164 / 160
# 23 / 21
# 17 / 17
# 15 / 16
# 29 / 28
# (164 / 160)
# (23 / 21)
# (17 / 17)
# (15 / 16)
# (29 / 28)
=end code
If no array is specified, it will use the internal array of C<snap> without
Expand All @@ -270,7 +136,7 @@ for ^5 {
snap;
LAST snap;
}
.say for periods;
say .<cpu wallclock>.join(" / ") for periods;
# OUTPUT:
# ====================
Expand Down Expand Up @@ -299,8 +165,7 @@ Below are the additional named parameters of C<report>.
=item C<:columns>
Specify the names of the columns to be included in the report. Names can
be specified with the full method name (e.g. C<general-workers>) or with
the abbreviated column name (e.g. C<gw>). If not specified, defaults to
be specified with the column name (e.g. C<gw>). If not specified, defaults to
what is specified in the C<RAKUDO_REPORT_COLUMNS> environment variable.
If that is not set either, defaults to:
Expand Down

0 comments on commit 5c0d780

Please sign in to comment.