File Coverage

blib/lib/JMX/Jmx4Perl/Alias.pm
Criterion Covered Total %
statement 40 45 88.8
branch 4 4 100.0
condition n/a
subroutine 9 11 81.8
pod 3 3 100.0
total 56 63 88.8


line stmt bran cond sub pod time code
1             #!/usr/bin/perl
2              
3             package JMX::Jmx4Perl::Alias;
4              
5 4     4   37664 use strict;
  4         7  
  4         106  
6 4     4   891 use Data::Dumper;
  4         9099  
  4         205  
7 4     4   2298 use JMX::Jmx4Perl::Alias::Object;
  4         10  
  4         107  
8 4     4   19 use Carp;
  4         7  
  4         2085  
9              
10             =head1 NAME
11              
12             JMX::Jmx4Perl::Alias - JMX alias names for jmx4perl
13              
14             =head1 DESCRIPTION
15              
16             Aliases are shortcuts for certain MBean attributes and
17             operations. Additionally, aliasing provides a thin abstraction layer which
18             allows to map common functionality with different naming schemes across
19             different application servers. E.g you can access the heap memory usage of your
20             application by using the alias C regardless how the specific
21             MBean and its attributes are named on the target application server. Specific
22             L take care about this mapping.
23              
24             Alias are normally named hierachically, from the most general to the most
25             specific, where the parts are separate by underscore
26             (C<_>). I.e. C specifies the total physical memory
27             installed on the machine.
28              
29             If you C this module, be aware that B aliases are imported in your
30             name space a subroutines (so that you an use them without a C<$>).
31              
32             Most of the methods in C which allows for aliases can take an
33             alias in two forms. Either as a constant import by using this module or as
34             string. The string can be either the name of the alias itself or, as an
35             alternative format, a lower cased variant where underscores are replaced by
36             colons. E.g C<"MEMORY_HEAP_USED"> and C<"memory:heap:used"> are both valid
37             alias names.
38              
39             Each alias is an object of the package L which
40             provides some additional informations about the alias.
41              
42             To print out all available aliases, sorted by name and with a short
43             description, you can use the C subroutine, e.g. like in
44              
45             perl -MJMX::Jmx4Perl::Alias -e 'JMX::Jmx4Perl::Alias::help'
46              
47             =head1 METHODS
48              
49             =over
50              
51             =cut
52              
53             my %ALIAS_MAP =
54             (attribute =>
55             {
56             # ========================================================================================================
57             SERVER_VERSION => ["Version of application server"],
58             SERVER_NAME => ["Name of server software"],
59             SERVER_ADDRESS => [ "IP Address of server, numeric"],
60             SERVER_HOSTNAME => [ "Hostname of server"],
61            
62              
63             # ========================================================================================================
64             # Standard Java VM Attributes
65             # Memory
66             MEMORY_HEAP => [ "Heap memory usage, multiple values", [ "java.lang:type=Memory", "HeapMemoryUsage" ]],
67             MEMORY_HEAP_USED => [ "Used heap memory", [ "java.lang:type=Memory", "HeapMemoryUsage", "used" ]],
68             MEMORY_HEAP_INIT => [ "Initially allocated heap memory", [ "java.lang:type=Memory", "HeapMemoryUsage", "init" ]],
69             MEMORY_HEAP_COMITTED => [ "Committed heap memory. That's the memory currently available for this JVM", [ "java.lang:type=Memory", "HeapMemoryUsage", "committed" ]],
70             MEMORY_HEAP_MAX => [ "Maximum available heap memory", [ "java.lang:type=Memory", "HeapMemoryUsage", "max" ]],
71              
72             MEMORY_NONHEAP => [ "Non-Heap memory usage, multiple values", [ "java.lang:type=Memory", "NonHeapMemoryUsage" ]],
73             MEMORY_NONHEAP_USED => [ "Used non-heap memory (like a 'method area')", [ "java.lang:type=Memory", "NonHeapMemoryUsage", "used" ]],
74             MEMORY_NONHEAP_INIT => [ "Initially allocated non-heap memory", [ "java.lang:type=Memory", "NonHeapMemoryUsage", "init" ]],
75             MEMORY_NONHEAP_COMITTED => [ "Committed non-heap memory", [ "java.lang:type=Memory", "NonHeapMemoryUsage", "committed" ]],
76             MEMORY_NONHEAP_MAX => [ "Maximum available non-heap memory", [ "java.lang:type=Memory", "NonHeapMemoryUsage", "max" ]],
77              
78             MEMORY_VERBOSE => [ "Switch on/off verbose messages concerning the garbage collector", ["java.lang:type=Memory", "Verbose"]],
79              
80             # Class loading
81             CL_LOADED => [ "Number of currently loaded classes", [ "java.lang:type=ClassLoading", "LoadedClassCount"]],
82             CL_UNLOADED => [ "Number of unloaded classes", [ "java.lang:type=ClassLoading", "UnloadedClassCount"]],
83             CL_TOTAL => [ "Number of classes loaded in total", [ "java.lang:type=ClassLoading", "TotalLoadedClassCount"]],
84            
85             # Threads
86             THREAD_COUNT => ["Active threads in the system", [ "java.lang:type=Threading", "ThreadCount"]],
87             THREAD_COUNT_PEAK => ["Peak thread count", [ "java.lang:type=Threading", "PeakThreadCount"]],
88             THREAD_COUNT_STARTED => ["Count of threads started since system start", [ "java.lang:type=Threading", "TotalStartedThreadCount"]],
89             THREAD_COUNT_DAEMON => ["Count of threads marked as daemons in the system", [ "java.lang:type=Threading", "DaemonThreadCount"]],
90            
91             # Operating System
92             OS_MEMORY_PHYSICAL_FREE => ["The amount of free physical memory for the OS", [ "java.lang:type=OperatingSystem", "FreePhysicalMemorySize"]],
93             OS_MEMORY_PHYSICAL_TOTAL => ["The amount of total physical memory for the OS", [ "java.lang:type=OperatingSystem", "TotalPhysicalMemorySize"]],
94             OS_MEMORY_SWAP_FREE => ["The amount of free swap space for the OS", [ "java.lang:type=OperatingSystem", "FreeSwapSpaceSize"]],
95             OS_MEMORY_SWAP_TOTAL => ["The amount of total swap memory available", [ "java.lang:type=OperatingSystem", "TotalSwapSpaceSize"]],
96             OS_MEMORY_VIRTUAL => ["Size of virtual memory used by this process", [ "java.lang:type=OperatingSystem", "CommittedVirtualMemorySize"]],
97             OS_FILE_DESC_OPEN => ["Number of open file descriptors", [ "java.lang:type=OperatingSystem", "OpenFileDescriptorCount"]],
98             OS_FILE_DESC_MAX => ["Maximum number of open file descriptors", [ "java.lang:type=OperatingSystem", "MaxFileDescriptorCount"]],
99             OS_CPU_TIME => ["The cpu time used by this process", [ "java.lang:type=OperatingSystem", "ProcessCpuTime"]],
100             OS_INFO_PROCESSORS => ["Number of processors", [ "java.lang:type=OperatingSystem", "AvailableProcessors"]],
101             OS_INFO_ARCH => ["Architecture", [ "java.lang:type=OperatingSystem", "Arch"]],
102             OS_INFO_NAME => ["Operating system name", [ "java.lang:type=OperatingSystem", "Name"]],
103             OS_INFO_VERSION => ["Operating system version", [ "java.lang:type=OperatingSystem", "Version"]],
104            
105             # Runtime
106             RUNTIME_SYSTEM_PROPERTIES => ["System properties", [ "java.lang:type=Runtime", "SystemProperties"]],
107             RUNTIME_VM_VERSION => ["Version of JVM", [ "java.lang:type=Runtime", "VmVersion"]],
108             RUNTIME_VM_NAME => ["Name of JVM", [ "java.lang:type=Runtime", "VmName"]],
109             RUNTIME_VM_VENDOR => ["JVM Vendor", [ "java.lang:type=Runtime", "VmVendor"]],
110             RUNTIME_ARGUMENTS => ["Arguments when starting the JVM", [ "java.lang:type=Runtime", "InputArguments"]],
111             RUNTIME_UPTIME => ["Total uptime of JVM", [ "java.lang:type=Runtime", "Uptime"]],
112             RUNTIME_STARTTIME => ["Time when starting the JVM", [ "java.lang:type=Runtime", "StartTime"]],
113             RUNTIME_CLASSPATH => ["Classpath", [ "java.lang:type=Runtime", "ClassPath"]],
114             RUNTIME_BOOTCLASSPATH => ["Bootclasspath", [ "java.lang:type=Runtime", "BootClassPath"]],
115             RUNTIME_LIBRARY_PATH => ["The LD_LIBRARY_PATH", [ "java.lang:type=Runtime", "LibraryPath"]],
116             RUNTIME_NAME => ["Name of the runtime", [ "java.lang:type=Runtime", "Name"]],
117              
118             # Jmx4Perl
119             JMX4PERL_HISTORY_SIZE => [ "Size of the history of all attributes and operations in bytes" , ["jolokia:type=Config","HistorySize"]],
120             JMX4PERL_HISTORY_MAX_ENTRIES => [ "Maximum number of entries per attribute/operation possible" , ["jolokia:type=Config","HistoryMaxEntries"]],
121             JMX4PERL_DEBUG => [ "Switch on/off debugging by setting this boolean" , ["jolokia:type=Config","Debug"]],
122             JMX4PERL_DEBUG_MAX_ENTRIES => [ "Maximum number of entries for storing debug info" , ["jolokia:type=Config","MaxDebugEntries"]],
123             },
124              
125             operation =>
126             {
127             # Memory
128             MEMORY_GC => [ "Run a garbage collection", [ "java.lang:type=Memory", "gc" ]],
129              
130             # Threads
131             THREAD_DEADLOCKED => [ "Find cycles of threads that are in deadlock waiting to acquire object monitors", [ "java.lang:type=Threading", "findMonitorDeadlockedThreads"]],
132             # TODO: Check for a default
133             THREAD_DUMP => [ "Create a thread dump" ],
134              
135             # Jmx4Perl
136             JMX4PERL_HISTORY_MAX_ATTRIBUTE => [ "Set the size of the history for a specific attribute" , ["jolokia:type=Config","setHistoryEntriesForAttribute"]],
137             JMX4PERL_HISTORY_MAX_OPERATION => [ "Set the size of the history for a specific operation" , ["jolokia:type=Config","setHistoryEntriesForOperation"]],
138             JMX4PERL_HISTORY_RESET => [ "Reset the history for all attributes and operations" , ["jolokia:type=Config","resetHistoryEntries"]],
139             JMX4PERL_DEBUG_INFO => [ "Print out latest debug info", ["jolokia:type=Config","debugInfo"]],
140             JMX4PERL_SERVER_INFO => [ "Show information about registered MBeanServers", ["jolokia:type=Config","mBeanServerInfo"]]
141             });
142              
143             my %NAME_TO_ALIAS_MAP;
144             my %ALIAS_OBJECT_MAP;
145             my $initialized = undef;
146              
147             # Import alias names directly into the name space
148             # of the importer
149             sub import {
150 7     7   125 my $callpkg = caller;
151 7 100       79 &_init() unless $initialized;
152 7         13 do {
153 4     4   21 no strict 'refs';
  4         8  
  4         1915  
154 7         83 for my $alias (keys %ALIAS_OBJECT_MAP) {
155 399         565 my $object = $ALIAS_OBJECT_MAP{$alias};
156 399     5   1133 *{$callpkg."::".$alias} = sub { $object };
  399         2209  
  5         1102  
157             }
158             };
159             }
160              
161             =item $alias = JMX::Jmx4Perl::Alias->by_name("MEMORY_HEAP_USAGE")
162              
163             Get an alias object by a name lookup. The argument provided must be a string
164             containing the name of an alias. If such an alias is not registered, this
165             method returns C.
166              
167             =cut
168              
169             sub by_name {
170 5     5 1 344 my $self = shift;
171 5         6 my $name = shift;
172 5         6 my $ret;
173 5         16 my $alias = $NAME_TO_ALIAS_MAP{$name};
174             #Try name in form "memory:heap:usage"
175 5 100       16 if ($alias) {
176 3         49 return $ALIAS_OBJECT_MAP{$alias};
177             }
178             # Try name in form "MEMORY_HEAP_USAGE"
179 2         10 return $ALIAS_OBJECT_MAP{$name};
180             }
181              
182             =item JMX::Jmx4Perl::Alias->all
183              
184             Get all aliases defined, sorted by alias name.
185              
186             =cut
187              
188             sub all {
189 0     0 1 0 return sort { $a->alias cmp $b->alias } values %ALIAS_OBJECT_MAP;
  0         0  
190             }
191              
192             =item JMX::Jmx4Perl::Alias::help
193              
194             Print out all registered aliases along with a short description
195              
196             =cut
197              
198             sub help {
199 0     0 1 0 my @aliases = &JMX::Jmx4Perl::Alias::all;
200 0         0 for my $alias (@aliases) {
201 0         0 printf('%-30.30s %4.4s %s'."\n",$alias->alias,$alias->type,$alias->description);
202             }
203             }
204              
205             # Build up various hashes
206             sub _init {
207 4     4   11 %NAME_TO_ALIAS_MAP = ();
208 4         7 %ALIAS_OBJECT_MAP = ();
209 4         13 for my $type (keys %ALIAS_MAP) {
210 8         13 for my $alias (keys %{$ALIAS_MAP{$type}}) {
  8         42  
211 228         390 my $name = lc $alias;
212 228         588 $name =~ s/_/:/g;
213 228         501 $NAME_TO_ALIAS_MAP{$name} = $alias;
214             $ALIAS_OBJECT_MAP{$alias} =
215             new JMX::Jmx4Perl::Alias::Object
216             (
217             alias => $alias,
218             name => $name,
219             type => $type,
220             description => $ALIAS_MAP{$type}{$alias}[0],
221 228         709 default => $ALIAS_MAP{$type}{$alias}[1],
222             );
223             }
224             }
225 4         15 $initialized = 1;
226             }
227              
228             =back
229              
230             =head1 ALIASES
231              
232             The currently aliases are as shown below. Note, that this information might be
233             outdated, to get the current one, use
234              
235             perl -MJMX::Jmx4Perl::Alias -e 'JMX::Jmx4Perl::Alias::help'
236              
237             CL_LOADED attr Number of currently loaded classes
238             CL_TOTAL attr Number of classes loaded in total
239             CL_UNLOADED attr Number of unloaded classes
240             JMX4PERL_DEBUG attr Switch on/off debugging by setting this boolean
241             JMX4PERL_DEBUG_INFO oper Print out latest debug info
242             JMX4PERL_DEBUG_MAX_ENTRIES attr Maximum number of entries for storing debug info
243             JMX4PERL_HISTORY_MAX_ATTRIBUTE oper Set the size of the history for a specific attribute
244             JMX4PERL_HISTORY_MAX_ENTRIES attr Maximum number of entries per attribute/operation possible
245             JMX4PERL_HISTORY_MAX_OPERATION oper Set the size of the history for a specific operation
246             JMX4PERL_HISTORY_RESET oper Reset the history for all attributes and operations
247             JMX4PERL_HISTORY_SIZE attr Size of the history of all attributes and operations in bytes
248             JMX4PERL_SERVER_INFO oper Show information about registered MBeanServers
249             MEMORY_GC oper Run a garbage collection
250             MEMORY_HEAP attr Heap memory usage, multiple values
251             MEMORY_HEAP_COMITTED attr Committed heap memory. That's the memory currently available for this JVM
252             MEMORY_HEAP_INIT attr Initially allocated heap memory
253             MEMORY_HEAP_MAX attr Maximum available heap memory
254             MEMORY_HEAP_USED attr Used heap memory
255             MEMORY_NONHEAP attr Non-Heap memory usage, multiple values
256             MEMORY_NONHEAP_COMITTED attr Committed non-heap memory
257             MEMORY_NONHEAP_INIT attr Initially allocated non-heap memory
258             MEMORY_NONHEAP_MAX attr Maximum available non-heap memory
259             MEMORY_NONHEAP_USED attr Used non-heap memory (like a 'method area')
260             MEMORY_VERBOSE attr Switch on/off verbose messages concerning the garbage collector
261             OS_CPU_TIME attr The cpu time used by this process
262             OS_FILE_DESC_MAX attr Maximum number of open file descriptors
263             OS_FILE_DESC_OPEN attr Number of open file descriptors
264             OS_INFO_ARCH attr Architecture
265             OS_INFO_NAME attr Operating system name
266             OS_INFO_PROCESSORS attr Number of processors
267             OS_INFO_VERSION attr Operating system version
268             OS_MEMORY_PHYSICAL_FREE attr The amount of free physical memory for the OS
269             OS_MEMORY_PHYSICAL_TOTAL attr The amount of total physical memory for the OS
270             OS_MEMORY_SWAP_FREE attr The amount of free swap space for the OS
271             OS_MEMORY_SWAP_TOTAL attr The amount of total swap memory available
272             OS_MEMORY_VIRTUAL attr Size of virtual memory used by this process
273             RUNTIME_ARGUMENTS attr Arguments when starting the JVM
274             RUNTIME_BOOTCLASSPATH attr Bootclasspath
275             RUNTIME_CLASSPATH attr Classpath
276             RUNTIME_LIBRARY_PATH attr The LD_LIBRARY_PATH
277             RUNTIME_NAME attr Name of the runtime
278             RUNTIME_STARTTIME attr Time when starting the JVM
279             RUNTIME_SYSTEM_PROPERTIES attr System properties
280             RUNTIME_UPTIME attr Total uptime of JVM
281             RUNTIME_VM_NAME attr Name of JVM
282             RUNTIME_VM_VENDOR attr JVM Vendor
283             RUNTIME_VM_VERSION attr Version of JVM
284             SERVER_ADDRESS attr IP Address of server, numeric
285             SERVER_HOSTNAME attr Hostname of server
286             SERVER_NAME attr Name of server software
287             SERVER_VERSION attr Version of application server
288             THREAD_COUNT attr Active threads in the system
289             THREAD_COUNT_DAEMON attr Count of threads marked as daemons in the system
290             THREAD_COUNT_PEAK attr Peak thread count
291             THREAD_COUNT_STARTED attr Count of threads started since system start
292             THREAD_DEADLOCKED oper Find cycles of threads that are in deadlock waiting to acquire object monitors
293             THREAD_DUMP oper Create a thread dump
294              
295             =head1 LICENSE
296              
297             This file is part of jmx4perl.
298              
299             Jmx4perl is free software: you can redistribute it and/or modify
300             it under the terms of the GNU General Public License as published by
301             the Free Software Foundation, either version 2 of the License, or
302             (at your option) any later version.
303              
304             jmx4perl is distributed in the hope that it will be useful,
305             but WITHOUT ANY WARRANTY; without even the implied warranty of
306             MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
307             GNU General Public License for more details.
308              
309             You should have received a copy of the GNU General Public License
310             along with jmx4perl. If not, see .
311              
312             A commercial license is available as well. Please contact roland@cpan.org for
313             further details.
314              
315             =head1 PROFESSIONAL SERVICES
316              
317             Just in case you need professional support for this module (or Nagios or JMX in
318             general), you might want to have a look at
319             http://www.consol.com/opensource/nagios/. Contact roland.huss@consol.de for
320             further information (or use the contact form at http://www.consol.com/contact/)
321              
322             =head1 AUTHOR
323              
324             roland@cpan.org
325              
326             =cut
327              
328             1;