First stab at documenting Telemetry::Sampler

Author: lizmat

doc/Type/Telemetry/Sampler.pod6

@@ -0,0 +1,52 @@
+=begin pod
+
+=TITLE class Telemetry::Sampler
+
+=SUBTITLE Telemetry Instrument Pod
+
+    =begin code :preamble<class Telemetry { }>
+    class Telemetry::Sampler { }
+    =end code
+
+B<Note: > This class is a Rakudo-specific feature and not standard Perl 6.
+
+=begin code
+use Telemetry;
+$*SAMPLER.set-instruments(<Usage ThreadPool>); # default setting
+=end code
+
+One usually does not create any C<Telemetry::Sampler> objects: when the
+L<Telemetry|/type/Telemetry> module is loaded, a C<Telemetry::Sampler> object
+is automatically created in the C<$*SAMPLER> dynamic variable.
+
+An object of the C<Telemetry::Sampler> class knows about which instruments
+to use when making a snapshot.
+
+=head2 method new
+
+  method new(Telemetry::Sampler: @instruments --> Telemetry::Sampler:D)
+
+The C<new> method takes a list of instruments.  If no instruments are specified,
+then it will look at the C<RAKUDO_TELEMETRY_INSTRUMENTS> environment variable
+to find specification of instruments.  If that is not available either, then
+L<Thread::Instrument::Usage|/type/Thread::Instrument::Usage> and
+L<Thread::Instrument::ThreadPool|/type/Thread::Instrument::ThreadPool> will be
+assumed.
+
+Instruments can be specified by either the type object of the instrument class
+(e.g. C<Telemetry::Instrument::Usage>) or by a string, in which case it will
+be automatically prefixed with "Telemetry::Instrument::", so "Usage" would be
+the same as C<Telemetry::Instrument::Usage>.
+
+=head2 method set-instruments
+
+  method set-instruments(Telemetry::Sampler:D @instruments --> self)
+
+Allows one to change the instruments on an existing C<Instrument::Sampler>
+object.  Generally only used by calling it on the C<$*SAMPLER> dynamic variable.
+Takes the same parameters as L<new>, except that specifying B<no> instruments
+will actually remove all of the instruments, effectively blocking any snap taking.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6