view release on metacpan or  search on metacpan

lib/Endoscope.pm  view on Meta::CPAN

=head2 remove

  $e->remove("foo.pl", 42);

Remove any query assigned to the file/line pair.

=head2 apply

  $e->apply();

C<apply> synchronizes the set of 'added' or 'removed' queries with the
underlying system, L<Devel::Probe>. Call this after 'adding' or 'removing'
queries, or to reset 'once' queries after they've fired. If Endoscope is
integrated with a web application, this would be called once per request early
in the request handling lifecycle.

=head2 clear

C<clear> removes all queries from settings. Call C<apply> to remove them for
real.

=head1 PERFORMANCE

C<Endoscope> and supporting libraries C<Devel::Probe> and C<Devel::Optic>
attempt to be suitable for usage in performance sensitive production
environments. However, 'performance sensitive' covers a wide range of
situations. As a rule of thumb, if the code you're querying strives to minimize
subroutine calls for performance reasons, it would be best to stick to the
default 'once' setting for queries, and be mindful of the amount of work
performed in the 'monitor'.

=head2 BENCHMARK

Benchmarking is very difficult, and for the sake of this document I'm going to
quote results from my laptop. The goal of this benchmark report is to give you
a general sense of how C<Endoscope> performs. Your milage may vary.

NOTE: all of the C<Endoscope> tests are conducted with at least one query
active and firing each time the associated code is executed. If no queries are
configured, C<Endoscope> has no measurable overhead. The recommended setup is
for C<Endoscope> to be installed and listening, and have the program expose
a privileged interface for system operators to set queries which execute once,
dump some information, and then remove themselves. This model of integration
should be suitable for all but the tightest performance requirements.

=head3 TEST SETUP

The testbed is a "Hello World" Mojolicious application using Mojolicious in the
following configuration:

	$ mojo version
	CORE
	  Perl        (v5.28.1, linux)
	  Mojolicious (8.17, Supervillain)

	OPTIONAL
	  Cpanel::JSON::XS 4.04+  (4.09)
	  EV 4.0+                 (4.25)
	  IO::Socket::Socks 0.64+ (n/a)
	  IO::Socket::SSL 2.009+  (2.066)
	  Net::DNS::Native 0.15+  (n/a)
	  Role::Tiny 2.000001+    (2.000006)

	This version is up to date, have fun!

The test machine has 16gb of RAM and an Intel Core i7-8650U (4 cores, 8 threads) CPU.

=head3 TEST PROGRAMS

Baseline program:

	use Mojolicious::Lite;

	get '/hello' => sub {
		my $c = shift;
		my $app = app;
		$c->render(text => "hello!\n");
	};

	app->start;

C<Endoscope> variant program:

	use Mojolicious::Lite;
	use Endoscope;
	my $scope = Endoscope->new(monitor => sub {
		my ($file, $line, $query, $result) = @_;
		app->log->debug("$file/$line/$query = $result");
	});
	$scope->add(__FILE__, __LINE__ + 6, '$app', 1); # 1 means 'run it every time that line executes'
	$scope->apply();

	get '/hello' => sub {
		my $c = shift;
		my $app = app;
		$c->render(text => "hello!\n");
	};

	app->start;

These programs store 'app' into C<$app> in order to give C<Endoscope> a large structure to query.

The Mojo app is running in 'production' mode.

    $ perl test.pl daemon -m production

This avoids measuring the performance of printing logs to C<STDERR>.

The load generator is L<wrk2|https://github.com/giltene/wrk2>, invoked in the following way:

    $ wrk 'http://localhost:3000/hello' -R 2500 -d 60

=head4 HOW TO READ THE RESULTS

The test cases use a target request rate of 2500 RPS. This exceeds the baseline
single-core performance of Mojolicious on my laptop. As such, the latency
numbers look really high: we are saturating the test programs.

I did this because lower request rates, like 2000 RPS, resulted in
both test programs easily managing the request rates with average latencies in