=begin pod :kind("Type") :subkind("class") :category("basic")

=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 Raku.

=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

=for code :preamble<use Telemetry>
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<C<Telemetry::Instrument::Usage>|/type/Telemetry::Instrument::Usage> and
C<Telemetry::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

=for code :preamble<use Telemetry>
method set-instruments(Telemetry::Sampler:D @instruments --> Nil)

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|/routine/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
