1#  You may distribute under the terms of either the GNU General Public License
2#  or the Artistic License (the same terms as Perl itself)
3#
4#  (C) Paul Evans, 2020 -- leonerd@leonerd.org.uk
5
6package IO::Async::Metrics;
7
8use strict;
9use warnings;
10
11# Metrics support is entirely optional
12our $METRICS;
13eval {
14   require Metrics::Any and
15      Metrics::Any->VERSION( '0.05' ) and
16      Metrics::Any->import( '$METRICS',
17         name_prefix => [qw( io_async )],
18      );
19};
20
21=head1 NAME
22
23C<IO::Async::Metrics> - report metrics about C<IO::Async> to C<Metrics::Any>
24
25=head1 DESCRIPTION
26
27This module contains the implementation of metrics-reporting code from
28C<IO::Async> to provide information about its operation into L<Metrics::Any>.
29
30=cut
31
32sub import
33{
34   my $class = shift;
35   my $caller = caller;
36   my ( $varname ) = @_;
37
38   $varname =~ s/^\$//;
39
40   no strict 'refs';
41   *{"${caller}::${varname}"} = \$METRICS;
42}
43
44=head1 METRICS
45
46The following metrics are reported:
47
48=head2 io_async_forks
49
50A counter giving the number of times that C<fork(2)> has been called by the
51L<IO::Async::Loop>.
52
53=head2 io_async_notifiers
54
55A gauge giving the number of L<IO::Async::Notifiers> currently registered
56with the Loop.
57
58=head2 io_async_processing
59
60A time distribution giving the amount of time spent processing IO events. This
61time does not include the time spent blocking on the underlying kernel system
62call to wait for IO events, but only the time spent in userland afterwards to
63handle them.
64
65=head2 io_async_resolver_lookups
66
67A labelled counter giving the number of attempted lookups by the
68L<IO::Async::Resolver>.
69
70This metric has one label, C<type>, containing the type of lookup;
71e.g. C<getaddrinfo>.
72
73=head2 io_async_resolver_failures
74
75A labelled counter giving the number of Resolver lookups that failed. This is
76labelled as for C<io_async_resolver_lookups>.
77
78=head2 io_async_stream_read
79
80A counter giving the number of bytes read by L<IO::Async::Stream> instances.
81Note that for SSL connections, this will only be able to count bytes of
82plaintext, not ciphertext, and thus will be a slight under-estimate in this
83case.
84
85=head2 io_async_stream_written
86
87A counter giving the number of bytes written by Stream instances. Note again
88for SSL connections this will only be able to count bytes of plaintext.
89
90=cut
91
92if( defined $METRICS ) {
93   # Loop metrics
94   $METRICS->make_gauge( notifiers =>
95      description => "Number of IO::Async::Notifiers registered with the Loop",
96   );
97   $METRICS->make_counter( forks =>
98      description => "Number of times IO::Async has fork()ed a process",
99   );
100   $METRICS->make_timer( processing_time =>
101      name => [qw( processing )],
102      description => "Time spent by IO::Async:Loop processing IO",
103      # Override bucket generation
104      bucket_min => 0.001, bucket_max => 1, # 1msec to 1sec
105      buckets_per_decade => [qw( 1 2.5 5 )],
106   );
107   $METRICS->make_gauge( loops =>
108      description => "Count of IO::Async::Loop instances by class",
109      labels => [qw( class )],
110   );
111
112   # Resolver metrics
113   $METRICS->make_counter( resolver_lookups =>
114      name => [qw( resolver lookups )],
115      description => "Number of IO::Async::Resolver lookups by type",
116      labels => [qw( type )],
117   );
118   $METRICS->make_counter( resolver_failures =>
119      name => [qw( resolver failures )],
120      description => "Number of IO::Async::Resolver lookups that failed by type",
121      labels => [qw( type )],
122   );
123
124   # Stream metrics
125   $METRICS->make_counter( stream_written =>
126      name => [qw( stream written )],
127      description => "Bytes written by IO::Async::Streams",
128      units => "bytes",
129   );
130   $METRICS->make_counter( stream_read =>
131      name => [qw( stream read )],
132      description => "Bytes read by IO::Async::Streams",
133      units => "bytes",
134   );
135}
136
137=head1 AUTHOR
138
139Paul Evans <leonerd@leonerd.org.uk>
140
141=cut
142
1430x55AA;
144