The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Harbinger-Client-0.001002
River stage zero No dependents
++
/ Harbinger::Client

NAME

Harbinger::Client - Impend all the doom you could ever want âš”

VERSION

version 0.001002

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);

DESCRIPTION

After reading The Mature Optimization Handbook, in a fever dream of hubris, I wrote Harbinger::Client and Harbinger::Server. 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 ever throws an exception I have failed in my goals.

As should be clear in the "SYNOPSIS" the grim measurement that the Harbinger records is called "DOOM 💀". "DOOM 💀" currently measures a handful of data points, but the important bits are:

  • time

  • space

  • queries

See more in "DOOM 💀".

METHODS

new

Instantiate client with this method. Note example in "SYNOPSIS".

Takes a hash of harbinger_ip (default of 127.0.0.1), harbinger_port (default of 8001), and default_args (default of []).

harbinger_ip and harbinger_port are how to connect to the remote Harbinger::Server.

default_args get used in "start" and "instant" when forging new "DOOM 💀".

start

The typical way to start measuring some "DOOM 💀". Note example in "SYNOPSIS".

Actual implementation at "Harbinger::Client::Doom->start".

instant

 $client->instant(
    ident => 'man overboard',
    count => 1,
 );

Instead of measuring deltas as "DOOM 💀" typically does, this method is for measuring instantaneous events, maybe for counting or graphing them later. Sends the event immediately.

send

 $client->send($completed_doom);

Once "DOOM 💀" is ready to be sent to the server pass it to send.

LIGHTHOUSE ⛯

Beware the siren song (👄) of the 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 (⚠).

DOOM 💀

Measure the crushing weight, the glacial pace, the incredible demand which your application puts upon your database server with DOOM™

DOOMFUL ATTRIBUTES ☠

server

Something unique that identifies the machine that we are measuring the "DOOM 💀" for. A good idea is the ip address or the hostname. If this is not set "DOOM 💀" will not be sent or recorded.

ident

Something unique that identifies the task that we are measuring the "DOOM 💀" for. For a web server, PATH_INFO might be a good option, or for some kind of message queue the task type would be a good option.

pid

The pid of the process "DOOM 💀" is being recorded for. Has a sensible default, you probably will never need to set it.

port

The port that the service is listening on, if applicable. Leave alone if unknown or not applicable.

count

The count of things being done in this unit of "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.

milliseconds_elapsed

The total milliseconds elapsed during the unit of "DOOM 💀". If instant or unknown "DOOM 💀" leave empty.

db_query_count

The total queries executed during the unit of "DOOM 💀". If not applicable or unknown "DOOM 💀" leave empty.

memory_growth_in_kb

The total memory growth in kb during the unit of "DOOM 💀". If not applicable or unknown "DOOM 💀" leave empty.

query_logger

A tool to measure query count with DBIx::Class. Please only use as documented, underlying implementation may change. See "QUERYLOG 📜"

DOOMFUL METHODS 🔮

Harbinger::Client::Doom->start

Normally called via "start". Sets up some internal stuff to make automatic measuring of "memory_growth_in_kb" and "milliseconds_elapsed" work. Takes a hash and merges hash into the object via accessors.

NOTE: to automatically measure memory growth you need either Win32::Process::Memory or Proc::ProcessTable installed.

$doom->bode_ill

Increment the "DOOM 💀" "count"er.

$doom->finish

 $doom->finish( count => 32 );

Finalizes "memory_growth_in_kb" and "milliseconds_elapsed". As with "Harbinger::Client::Doom->start" takes a hash and merges it into the object via accessors. Returns the object to allow chaining.

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 "new". Adds query_log from "DOOM 💀" to harbinger.querylog in psgi ENV. See "QUERYLOG 📜".

After the query completes the "DOOM 💀" will automatically be sent.

If harbinger.ident is set it will be used for the "ident", otherwise PATH_INFO will be used.

harbinger.server, and harbinger.count are passed more or less directly.

harbinger.port will be passed if true, otherwise SERVER_PORT will be used.

Catalyst::TraitFor::Controller::Harbinger

This page intentionally left blank.

QUERYLOG 📜

You are recommended to apply the query log with DBIx::Class::QueryLog::Tee and 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 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 DBIx::Class::QueryLog::Conditional allows you to have the Harbinger loggers always on, but the pretty DBIx::Class console logger can still be set via environment variable, as usual.

Now to set the logger after whipping up some "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 local is preferred, but that's not always possible.

AUTHOR

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Arthur Axel "fREW" Schmidt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.