1CHI::Stats(3)         User Contributed Perl Documentation        CHI::Stats(3)
2
3
4

NAME

6       CHI::Stats - Record and report per-namespace cache statistics
7

VERSION

9       version 0.61
10

SYNOPSIS

12           # Turn on statistics collection
13           CHI->stats->enable();
14
15           # Perform cache operations
16
17           # Flush statistics to logs
18           CHI->stats->flush();
19
20           ...
21
22           # Parse logged statistics
23           my $results = CHI->stats->parse_stats_logs($file1, ...);
24

DESCRIPTION

26       CHI can record statistics, such as number of hits, misses and sets, on
27       a per-namespace basis and log the results to your Log::Any logger.  You
28       can then parse the logs to get a combined summary.
29
30       A single CHI::Stats object is maintained for each CHI root class, and
31       tallies statistics over any number of CHI::Driver objects.
32
33       Statistics are reported when you call the "flush" method. You can
34       choose to do this once at process end, or on a periodic basis.
35

METHODS

37       enable, disable, enabled
38           Enable, disable, and query the current enabled status.
39
40           When stats are enabled, each new cache object will collect
41           statistics. Enabling and disabling does not affect existing cache
42           objects. e.g.
43
44               my $cache1 = CHI->new(...);
45               CHI->stats->enable();
46               # $cache1 will not collect statistics
47               my $cache2 = CHI->new(...);
48               CHI->stats->disable();
49               # $cache2 will continue to collect statistics
50
51       flush
52           Log all statistics to Log::Any (at Info level in the CHI::Stats
53           category), then clear statistics from memory. There is one log
54           message for each distinct triplet of root class, cache label, and
55           namespace. Each log message contains the string "CHI stats:"
56           followed by a JSON encoded hash of statistics. e.g.
57
58               CHI stats: {"absent_misses":1,"label":"File","end_time":1338410398,
59                  "get_time_ms":5,"namespace":"Foo","root_class":"CHI",
60                  "set_key_size":6,"set_time_ms":23,"set_value_size":20,"sets":1,
61                  "start_time":1338409391}
62
63       parse_stats_logs
64           Accepts one or more stats log files as parameters. Parses the logs
65           and returns a listref of stats hashes by root class, cache label,
66           and namespace. e.g.
67
68               [
69                   {
70                       root_class     => 'CHI',
71                       label          => 'File',
72                       namespace      => 'Foo',
73                       absent_misses  => 100,
74                       avg_compute_time_ms => 23,
75                       ...
76                   },
77                   {
78                       root_class     => 'CHI',
79                       label          => 'File',
80                       namespace      => 'Bar',
81                       ...
82                   },
83               ]
84
85           Lines with the same root class, cache label, and namespace are
86           summed together.  Non-stats lines are ignored. The parser will
87           ignore anything on the line before the "CHI stats:" string, e.g. a
88           timestamp.
89
90           Each parameter to this method may be a filename or a reference to
91           an open filehandle.
92

STATISTICS

94       The following statistics are tracked in the logs:
95
96       •   "absent_misses" - Number of gets that failed due to item not being
97           in the cache
98
99       •   "compute_time_ms" - Total time spent computing missed results in
100           compute, in ms (divide by number of computes to get average).  i.e.
101           the amount of time spent in the code reference passed as the third
102           argument to compute().
103
104       •   "computes" - Number of compute calls
105
106       •   "expired_misses" - Number of gets that failed due to item expiring
107
108       •   "get_errors" - Number of caught runtime errors during gets
109
110       •   "get_time_ms" - Total time spent in get operation, in ms (divide by
111           number of gets to get average)
112
113       •   "hits" - Number of gets that succeeded
114
115       •   "set_key_size" - Number of bytes in set keys (divide by number of
116           sets to get average)
117
118       •   "set_value_size" - Number of bytes in set values (divide by number
119           of sets to get average)
120
121       •   "set_time_ms" - Total time spent in set operation, in ms (divide by
122           number of sets to get average)
123
124       •   "sets" - Number of sets
125
126       •   "set_errors" - Number of caught runtime errors during sets
127
128       The following additional derived/aggregate statistics are computed by
129       parse_stats_logs:
130
131       •   "misses" - "absent_misses" + "expired_misses"
132
133       •   "gets" - "hits" + "misses"
134
135       •   "avg_compute_time_ms" - "compute_time_ms" / "computes"
136
137       •   "avg_get_time_ms" - "get_time_ms" / "gets"
138
139       •   "avg_set_time_ms" - "set_time_ms" / "sets"
140
141       •   "avg_set_key_size" - "set_key_size" / "sets"
142
143       •   "avg_set_value_size" - "set_value_size" / "sets"
144
145       •   "hit_rate" - "hits" / "gets"
146

SEE ALSO

148       CHI
149

AUTHOR

151       Jonathan Swartz <swartz@pobox.com>
152

154       This software is copyright (c) 2021 by Jonathan Swartz.
155
156       This is free software; you can redistribute it and/or modify it under
157       the same terms as the Perl 5 programming language system itself.
158
159
160
161perl v5.38.0                      2023-07-20                     CHI::Stats(3)
Impressum