Update basic Telemetry documentation

More on the separate instruments to follow

Author: lizmat

doc/Type/Telemetry.pod6

@@ -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
 
@@ -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
@@ -270,7 +136,7 @@ for ^5 {
     snap;
     LAST snap;
 }
-.say for periods;
+say .<cpu wallclock>.join(" / ") for periods;
 
 # OUTPUT:
 # ====================
@@ -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: