.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "CHI::Stats 3pm"
.TH CHI::Stats 3pm "2017-07-31" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CHI::Stats \- Record and report per\-namespace cache statistics
.SH "VERSION"
.IX Header "VERSION"
version 0.60
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # Turn on statistics collection
\&    CHI\->stats\->enable();
\&
\&    # Perform cache operations
\&
\&    # Flush statistics to logs
\&    CHI\->stats\->flush();
\&
\&    ...
\&
\&    # Parse logged statistics
\&    my $results = CHI\->stats\->parse_stats_logs($file1, ...);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1CHI\s0 can record statistics, such as number of hits, misses and sets, on a
per-namespace basis and log the results to your Log::Any logger.
You can then parse the logs to get a combined summary.
.PP
A single CHI::Stats object is maintained for each \s-1CHI\s0 root class, and tallies
statistics over any number of CHI::Driver objects.
.PP
Statistics are reported when you call the \*(L"flush\*(R" method. You can choose to
do this once at process end, or on a periodic basis.
.SH "METHODS"
.IX Header "METHODS"
.IP "enable, disable, enabled" 4
.IX Item "enable, disable, enabled"
Enable, disable, and query the current enabled status.
.Sp
When stats are enabled, each new cache object will collect statistics. Enabling
and disabling does not affect existing cache objects. e.g.
.Sp
.Vb 6
\&    my $cache1 = CHI\->new(...);
\&    CHI\->stats\->enable();
\&    # $cache1 will not collect statistics
\&    my $cache2 = CHI\->new(...);
\&    CHI\->stats\->disable();
\&    # $cache2 will continue to collect statistics
.Ve
.IP "flush" 4
.IX Item "flush"
Log all statistics to Log::Any (at Info level in the CHI::Stats
category), then clear statistics from memory. There is one log message for each
distinct triplet of root class, cache label,
and namespace. Each log message contains the string \*(L"\s-1CHI\s0
stats:\*(R" followed by a \s-1JSON\s0 encoded hash of statistics. e.g.
.Sp
.Vb 4
\&    CHI stats: {"absent_misses":1,"label":"File","end_time":1338410398,
\&       "get_time_ms":5,"namespace":"Foo","root_class":"CHI",
\&       "set_key_size":6,"set_time_ms":23,"set_value_size":20,"sets":1,
\&       "start_time":1338409391}
.Ve
.IP "parse_stats_logs" 4
.IX Item "parse_stats_logs"
Accepts one or more stats log files as parameters. Parses the logs and returns
a listref of stats hashes by root class, cache label, and namespace. e.g.
.Sp
.Vb 10
\&    [
\&        {
\&            root_class     => \*(AqCHI\*(Aq,
\&            label          => \*(AqFile\*(Aq,
\&            namespace      => \*(AqFoo\*(Aq,
\&            absent_misses  => 100,
\&            avg_compute_time_ms => 23,
\&            ...
\&        },
\&        {
\&            root_class     => \*(AqCHI\*(Aq,
\&            label          => \*(AqFile\*(Aq,
\&            namespace      => \*(AqBar\*(Aq,
\&            ...
\&        },
\&    ]
.Ve
.Sp
Lines with the same root class, cache label, and namespace are summed together.
Non-stats lines are ignored. The parser will ignore anything on the line before
the \*(L"\s-1CHI\s0 stats:\*(R" string, e.g. a timestamp.
.Sp
Each parameter to this method may be a filename or a reference to an open
filehandle.
.SH "STATISTICS"
.IX Header "STATISTICS"
The following statistics are tracked in the logs:
.IP "\(bu" 4
\&\f(CW\*(C`absent_misses\*(C'\fR \- Number of gets that failed due to item not being in the
cache
.IP "\(bu" 4
\&\f(CW\*(C`compute_time_ms\*(C'\fR \- Total time spent computing missed results in
compute, in ms (divide by number of computes to get average).
i.e. the amount of time spent in the code reference passed as the third
argument to \fIcompute()\fR.
.IP "\(bu" 4
\&\f(CW\*(C`computes\*(C'\fR \- Number of compute calls
.IP "\(bu" 4
\&\f(CW\*(C`expired_misses\*(C'\fR \- Number of gets that failed due to item expiring
.IP "\(bu" 4
\&\f(CW\*(C`get_errors\*(C'\fR \- Number of caught runtime errors during gets
.IP "\(bu" 4
\&\f(CW\*(C`get_time_ms\*(C'\fR \- Total time spent in get operation, in ms (divide by number of
gets to get average)
.IP "\(bu" 4
\&\f(CW\*(C`hits\*(C'\fR \- Number of gets that succeeded
.IP "\(bu" 4
\&\f(CW\*(C`set_key_size\*(C'\fR \- Number of bytes in set keys (divide by number of sets to get
average)
.IP "\(bu" 4
\&\f(CW\*(C`set_value_size\*(C'\fR \- Number of bytes in set values (divide by number of sets to
get average)
.IP "\(bu" 4
\&\f(CW\*(C`set_time_ms\*(C'\fR \- Total time spent in set operation, in ms (divide by number of
sets to get average)
.IP "\(bu" 4
\&\f(CW\*(C`sets\*(C'\fR \- Number of sets
.IP "\(bu" 4
\&\f(CW\*(C`set_errors\*(C'\fR \- Number of caught runtime errors during sets
.PP
The following additional derived/aggregate statistics are computed by
parse_stats_logs:
.IP "\(bu" 4
\&\f(CW\*(C`misses\*(C'\fR \- \f(CW\*(C`absent_misses\*(C'\fR + \f(CW\*(C`expired_misses\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`gets\*(C'\fR \- \f(CW\*(C`hits\*(C'\fR + \f(CW\*(C`misses\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`avg_compute_time_ms\*(C'\fR \- \f(CW\*(C`compute_time_ms\*(C'\fR / \f(CW\*(C`computes\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`avg_get_time_ms\*(C'\fR \- \f(CW\*(C`get_time_ms\*(C'\fR / \f(CW\*(C`gets\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`avg_set_time_ms\*(C'\fR \- \f(CW\*(C`set_time_ms\*(C'\fR / \f(CW\*(C`sets\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`avg_set_key_size\*(C'\fR \- \f(CW\*(C`set_key_size\*(C'\fR / \f(CW\*(C`sets\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`avg_set_value_size\*(C'\fR \- \f(CW\*(C`set_value_size\*(C'\fR / \f(CW\*(C`sets\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`hit_rate\*(C'\fR \- \f(CW\*(C`hits\*(C'\fR / \f(CW\*(C`gets\*(C'\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1CHI\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Jonathan Swartz <swartz@pobox.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Jonathan Swartz.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.