docs

lib/Harbinger/Client.pm

@@ -1,5 +1,9 @@
 package Harbinger::Client;
 
+# ABSTRACT: Impend all the doom you could ever want ⚔
+
+use v5.16.1;
+use utf8;
 use Moo;
 use warnings NONFATAL => 'all';
 use Try::Tiny;
@@ -73,3 +77,282 @@ sub send {
 }
 
 1;
+
+__END__
+
+=pod
+
+=encoding utf8
+
+=head1 SYNOPSIS
+
+ my $client = Harbinger::Client->new(
+   harbinger_ip => '10.6.1.6',
+   harbinger_port => 8090,
+   default_args => [
+     server => 'foo.lan.bar.com',
+     port   => 1890,
+   ],
+ );
+
+ my $doom = $client->start(
+    ident => 'process-images',
+ );
+
+ for (@images) {
+    ...
+    $doom->bode_ill;
+ }
+
+ $client->send($doom->finish);
+
+=head1 LIGHTHOUSE ⛯
+
+Beware the siren song (👄) of the B<Harbinger>!  The API is not stable yet, I already
+have major changes planned for a plugin (🔌) system.  I'm not even going to attempt
+to keep things working.  You've been warned (⚠).
+
+=head1 DESCRIPTION
+
+After reading
+L<The Mature Optimization Handbook|http://carlos.bueno.org/optimization/mature-optimization.pdf>,
+in a fever dream of hubris, I wrote C<Harbinger::Client> and
+L<Harbinger::Server|https://github.com/frioux/Harbinger>.  They have both
+served me surprisingly well with how minimal they are.  The goal is to be as
+lightweight as possible such that the measuring of performance does not degrade
+performance nor impact reliability.  If the client B<ever> throws an exception
+I have failed in my goals.
+
+As should be clear in the L</SYNOPSIS> the grim measurement that the
+C<Harbinger> records is called L</DOOM 💀>.  L</DOOM 💀> currently measures a handful
+of data points, but the important bits are:
+
+=over 2
+
+=item * time
+
+=item * space
+
+=item * queries
+
+=back
+
+See more in L</DOOM 💀>.
+
+=head3 METHODS
+
+=head3 C<new>
+
+Instantiate client with this method.  Note example in L</SYNOPSIS>.
+
+Takes a hash of C<harbinger_ip> (default of C<127.0.0.1>), C<harbinger_port>
+(default of C<8001>), and C<default_args> (default of C<[]>).
+
+C<harbinger_ip> and C<harbinger_port> are how to connect to the remote
+C<HarBinger::Server>.
+
+C<default_args> get used in L</start> and L</instant> when forging new L</DOOM 💀>.
+
+=head3 C<start>
+
+The typical way to start measuring some L</DOOM 💀>.  Note example in L</SYNOPSIS>.
+
+Actual implementation at L<< /Harbinger::Client::Doom->start >>.
+
+=head3 C<instant>
+
+ $client->instant(
+    ident => 'man overboard',
+    count => 1,
+ );
+
+Instead of measuring deltas as L</DOOM 💀> typically does, this method is for measuring
+instantaneous events, maybe for counting or graphing them later.  Sends the
+event immediately.
+
+=head3 C<send>
+
+ $client->send($completed_doom);
+
+Once L</DOOM 💀> is ready to be sent to the server pass it to C<send>.
+
+=head1 DOOM 💀
+
+Measure the crushing weight, the glacial pace, the incredible demand which your
+application puts upon your database server with C<DOOM™>
+
+=head2 DOOMFUL ATTRIBUTES ☠
+
+=head3 C<server>
+
+Something unique that identifies the machine that we are measuring the L</DOOM 💀>
+for.  A good idea is the ip address or the hostname.  If this is not set L</DOOM 💀>
+will not be sent or recorded.
+
+=head3 C<ident>
+
+Something unique that identifies the task that we are measuring the L</DOOM 💀> for.
+For a web server, C<PATH_INFO> might be a good option, or for some kind of
+message queue the task type would be a good option.
+
+=head3 C<pid>
+
+The pid of the process L</DOOM 💀> is being recorded for.  Has a sensible default,
+you probably will never need to set it.
+
+=head3 C<port>
+
+The port that the service is listening on, if applicable.  Leave alone if
+unknown or not applicable.
+
+=head3 C<count>
+
+The count of things being done in this unit of L</DOOM 💀>.  If it were a web
+request that returns a list of items, this would reasonably be set as that
+number.  If the operation is not related to things that are countable, leave
+alone.
+
+=head3 C<milliseconds_elapsed>
+
+The total milliseconds elapsed during the unit of L</DOOM 💀>.  If instant or
+unknown L</DOOM 💀> leave empty.
+
+=head3 C<db_query_count>
+
+The total queries executed during the unit of L</DOOM 💀>.  If not applicable or
+unknown L</DOOM 💀> leave empty.
+
+=head3 C<memory_growth_in_kb>
+
+The total memory growth in kb during the unit of L</DOOM 💀>.  If not applicable or
+unknown L</DOOM 💀> leave empty.
+
+=head3 C<query_logger>
+
+A tool to measure query count with C<DBIx::Class>.  Please only use as
+documented, underlying implementation may change.  See L</QUERYLOG 📜>
+
+=head2 DOOMFUL METHODS 🔮
+
+=head3 C<< Harbinger::Client::Doom->start >>
+
+Normally called via L</start>.  Sets up some internal stuff to make automatic
+measuring of L</memory_growth_in_kb> and L</milliseconds_elapsed> work.  Takes a
+hash and merges hash into the object via accessors.
+
+B<NOTE>: to automatically measure memory growth you need either
+L<Win32::Process::Memory> or L<Proc::ProcessTable> installed.
+
+=head3 C<< $doom->bode_ill >>
+
+Increment the L</DOOM 💀> L</count>er.
+
+=head3 C<< $doom->finish >>
+
+ $doom->finish( count => 32 );
+
+Finalizes L</memory_growth_in_kb> and L</milliseconds_elapsed>.  As with
+L<< /Harbinger::Client::Doom->start >> takes a hash and merges it into the object
+via accessors.  Returns the object to allow chaining.
+
+=head1 C<Plack::Middleware::Harbinger>
+
+ builder {
+   enable Harbinger => {
+      harbinger_ip   => '192.168.1.1',
+      harbinger_port => 2250,
+      default_args   => [
+         server => '192.168.1.2',
+         port   => 80,
+      ],
+   };
+   $my_app
+ };
+
+Takes the same args as L</new>.  Adds C<query_log> from L</DOOM 💀> to
+C<harbinger.querylog> in C<psgi ENV>.  See L</QUERYLOG 📜>.
+
+After the query completes the L</DOOM 💀> will automatically be sent.
+
+If C<harbinger.ident> is set it will be used for the L</ident>, otherwise
+C<PATH_INFO> will be used.
+
+C<harbinger.server>, and C<harbinger.count> are passed more or less directly.
+
+C<harbinger.port> will be passed if true, otherwise C<SERVER_PORT> will be used.
+
+=head1 C<Catalyst::TraitFor::Controller::Harbinger>
+
+This page intentionally left blank.
+
+=head1 QUERYLOG 📜
+
+You are recommended to apply the query log with L<DBIx::Class::QueryLog::Tee>
+and L<DBIx::Class::QueryLog::Conditional>.
+
+First, set up your schema
+ package MyApp::Schema;
+
+ use base 'DBIx::Class::Schema';
+ use aliased 'DBIx::Class::QueryLog::Tee';
+ use aliased 'DBIx::Class::QueryLog::Conditional';
+
+ __PACKAGE__->load_namespaces(
+    default_resultset_class => 'ResultSet',
+ );
+
+ sub connection {
+    my $self = shift;
+
+    my $ret = $self->next::method(@_);
+
+    $ret->storage->debugobj(
+       Tee->new(
+          loggers => {
+             original => Conditional->new(
+                logger => $self->storage->debugobj,
+                enabled_method => sub { $ENV{DBIC_TRACE} },
+             ),
+          },
+       )
+    );
+
+    $ret->storage->debug(1);
+
+    $ret
+ }
+
+ 1;
+
+Note that the L<DBIx::Class::QueryLog::Tee> extension allows you to add more
+Query loggers as you go, so you can even log inner loops and outer loops at the
+same time.  Also note that L<DBIx::Class::QueryLog::Conditional> allows you to
+have the C<Harbinger> loggers always on, but the pretty L<DBIx::Class> console
+logger can still be set via environment variable, as usual.
+
+Now to set the logger after whipping up some L</DOOM 💀> this is all that's needed:
+
+ my $doom = $client->start(
+    ident => 'process-images',
+ );
+
+ $schema->storage->debugobj
+   ->add_logger('process-images-harbinger', $doom->query_logger);
+
+ $client->send($doom->finish);
+ $schema->storage->debugobj
+   ->remove_logger('process-images-harbinger');
+
+Finally, if you have some legacy code or are using the wrong ORM, you can still
+use the QueryLogger as follows:
+
+ $dbh->{Callbacks}{ChildCallbacks}{execute} = sub {
+   $doom->query_log->query_start('', []);
+   $doom->query_log->query_end('', []);
+   return ();
+ }
+
+If you can pull it off, doing this dynamically with C<local> is preferred, but
+that's not always possible.
+
+=cut