JMX4PERL(1) User Contributed Perl Documentation JMX4PERL(1)NAMEjmx4perl - JMX access tools and modules
SYNOPSISjmx4perl .... http://server:8080/jolokia ["info"]
jmx4perl .... <agent-url> read <mbean-name> <attribute-name> [path]
jmx4perl .... <agent-url> write <mbean-name> <attribute-name> <value> [path]
jmx4perl .... <agent-url> exec <mbean-name> <operation> <arg1> <arg2> ...
jmx4perl .... <agent-url> search <mbean pattern>
jmx4perl .... <agent-url> list [<domain-name>[:<mbean name>]]
jmx4perl .... <agent-url> attributes [max-depth max-list-size max-objects]
jmx4perl .... aliases
jmx4perl .... encrypt <password>
jmx4perl--help
jmx4perl--version [<agent-url>]
Options:
--product <id> Product to use for aliasing (ommits autodetection)
--user <user> Credential used for authentication
--password <pwd>
--proxy <url> URL to proxy
--proxy-user <user> Authentication information for a proxy
--proxy-password <pwd>
--target <jmx-url> JSR-160 JMX Service URL to be used as the target server
--target-user <user> Credential for the target server if --target is given
--target-password <pwd>
--config Path to an optional configuration file (default: ~/.j4p)
--history Print out the history of return values (if switched on and present)
--legacy-escape Used for contacting pre 1.0 Jolokia agent for MBeans containing
slashes in their name.
--method <get|post> Method to be used for HTTP request ("get" or "post")
--option key=val Options for tuning the output of jmx4perl. Known keys are
format : Either 'json' or 'data'
booleans : Pair of strings separated by slash to use for printing
boolean values (Default: [true]/[false])
indent : Space indent when printing complex data structures
--verbose Print out more information
DESCRIPTIONjmx4perl is a command line utility for an easy access of an
instrumented application server. Before you can use this tool, you need
to deploy a small agent application. In the following "agent-url" is
the URL for accessing this agent. If you use a configuration file, you
can use also a symbolic name as stored in the configuration file. See
JMX::Jmx4Perl::Manual for details.
With the "--option" (or "-o" for short) the output of jmx4perl can be
tuned. I.e. the way boolean values are printed can be tuned as well as
the data format to use for complex data structure. The known options
are
format
the value an be either "json" or <data> for printing out complex
data as JSON or as a Perl data structure. Default is "data".
booleans
Specify the pair of strings to use for boolean values for the
"data" output format. The value of this option should be given as a
string separated with a "/". The default value is "[true]/[false]".
method
Specify the HTTP method to use for requesting the server. This can
either be "get" or "post". By default "get" is used.
legacy-escape
Prior to version 1.0 Jolokia used a different escaping scheme for
GET requests which contains slashes. This option must be used, when
the server-side agent has a version < 1.0 and the MBean name
contains slashes ("/"). Alternatively, "--method post" can be used,
since the post method doesn't suffer from any escaping issues.
indent
Number of spaces to use for indenting the output of complex data
structures. Default are 4 spaces.
The options can be also put into the configuration file in a section
called "Jmx4Perl". For example:
<Jmx4Perl>
# 'json' or 'data'
Format json
# Boolean values: Default is [true]/[false]
Booleans 0/1
# Number of spaces to indent for complex
# data structures
Indent 4
</Jmx4Perl>
jmx4perl serves also an example of how to use the JMX::Jmx4Perl
package. See its documentation for more details on how to embed JMX
access into your programs.
COMMANDS
info
If you use jmx4perl without any command or with "info" as command, you
get a description about the server, including the application server's
product name and version. This works by autodetection and only for the
supported application servers (see JMX::Jmx4Perl::Manual for a list of
supported products). The only argument required is the url which points
to the deployed jmx4perl agent.
With "--verbose" "info" prints the system properties and runtime
arguments as well.
list
List meta data of all registered mbeans on the target application
server. This includes attributes and operations along whith their
descriptions and parameters (as far as they are provided by mbean's
info).
You can provide an inner path as an additional argument as well. See
JMX::Jmx4Perl::Request for an explanation about inner paths (in short,
it's some sort of XPath expression which selects only a subset of all
MBeans and their values). See JMX::Jmx4Perl, method "list()" for a more
rigorous documentation abouting listing of MBeans.
attributes
Show all attributes of all registerd mbeans and their values. For
simple scalar values they are shown on one line, for more complex data
structures, Data::Dumper is used. Please note, that it is normal, that
for certain attributes an error is returned (i.e. when this attribute
is not implemented on the server side e.g. or an MXMbean). To see the
full server side stacktrace for this errors, use "--verbose" as command
line option
The attribute list can get quite large (moren than 200 MB for JBoss 5).
To restrict the output you can use the following extra optional
parameters (given in this order):
maxDepth
Maximum nesting level of the returned JSON structure for a certain
MBean (default: 5)
maxCollectionSize
Maximum size of a collection after which it gets truncated
(default: 150)
maxObjects
Maximum overall objects to fetch for a certain MBean (default:
1000)
In the case of truncation, the JSON answer contains marker entries like
"[Object limit exceeded]" or "[Depth limit ...]". Loops are detected,
too which results in markers of the form "[Reference ...]"
read / get
Read an JMX attribute's value and print it out. The required arguments
are the MBean's name and the attribute's name. Additionally, you can
provide a path within the return value to pick a sub-value. See
JMX::Jmx4Perl::Request for a detailed explanation of paths.
The MBean's name and the attribute can be substituted by an alias name,
too.
For a single value, the value itself is printed (without additional
newline), for a more complex data structure, Data::Dumper is used.
If the option "--history" is given and history tracking is switched on
(see below), then the stored history is printed as well.
write / set
Write a JMX attribute's value and print out the value as it is returned
from the server. The required arguments are the MBean's name, the
attribute and the value to set. Optionally, a inner path can be
provided as well in which case a inner value is set. The MBean's name
and the attribute can be substituted by an alias name, too. See also
"aliases" for getting all available aliases.
The old value of the attribute (or the object pointed to by the inner
path) is printed out in the same as for "read"
To set a "null" value use "[null]" as argument, to set an empty string
use an empty argument (i.e. "" on the command line). These values are
interpreted special, so you can't use them literally as values.
If the option "--history" is given and history tracking is switched on
(see below), then the stored history is printed as well.
exec / call
Execute a JMX operation. The required arguments are the MBean's name,
the name of the operation to execute and the arguments required for
this operations (which can be empty if the operation doesn't take any
arguments). The return value is the return value of the operation which
can be "undef" in the case of a void operation.
A operation alias can also be used for the MBean's name and operation.
To use a "null" argument use "[null]", to set an empty string as
argument use an empty argument (i.e. "") on the command line. These
values are interpreted special, so you can't use them literally as
values.
For a single return value, the value itself is printed (without
additional newline), for a more complex data structure, Data::Dumper is
used.
If the option "--history" is given and history tracking is switched on
(see below), then the stored history is printed as well.
aliases
Print out all known aliases. See JMX::Jmx4Perl::Manual for a discussion
about aliases. In short, you can use an alias as a shortcut for an
MBean's and attribute's name.
search
Search for a certain MBean. As argument you should provide a pattern
like "*:j2eeType=Servlet,*". I.e you can use the wildcard "*" for the
domain name part, and properties as a whole (but not within a
key=property tuple). See
<http://java.sun.com/j2se/1.5.0/docs/api/javax/management/ObjectName.html>
for a complete explanation of how a pattern can look like. As a result
of this operation, a list of fully qualified MBean names is printed out
line by line which match the given pattern.
encrypt
Encrypt a given password so that it can be stored in its encrypted form
in a configuration file. Please note, that this is by no means secure
and only usual to avoid casual discovery of the password. Since
jmx4perl acts as a client it needs to be able to decrypt the password
on its own when contacting the agent, so it is a simple symmetric
encryptions. The password printed out can be used as "Password" value
for HTTP authentication and HTTP proxy authentication in configuration
files or at the command line.
HISTORY TRACKING
The agent knows about a history mode, which can remember a certain
amount return values from previous requests. This mode can be switched
on/off on a per attribute (+ inner path) and operation basis. By
default it is switched off completely. You can switch in on by
executing the "JMX4PERL_HISTORY_MAX_ATTRIBUTE" and
"JMX4PERL_HISTORY_MAX_OPERATION" operation with "exec" commands. This
is best explained by some example:
jmx4perl exec JMX4PERL_HISTORY_MAX_ATTRIBUTE java.lang:type=Memory HeapMemoryUsage used 10 <agent-url>
This switches on tracking of this particular attribute. I.e. each time
a "read" request is performed, the value is remembered along with a
timestamp on the server side. At maximum 10 entries are kept, the
oldest entries get shifted out after the eleventh read. Setting the
value to 0 will remove the history completely. You can't set the limit
beyond a certain hard limit, which can be found as attribute under the
alias "JMX4PERL_HISTORY_MAX_ENTRIES". Unfortunately, one can not use an
alias yet for the arguments of "JMX4PERL_HISTORY_MAX_ATTRIBUTE". Also
note, if you don't has an inner path, you need to use a "[null]" as the
argument before the max entry number.
For completely resetting the history, use
jmx4perl exec JMX4PERL_HISTORY_RESET <agent-url>
If you are curious about the size of the history for all entries, use
jmx4perl read JMX4PERL_HISTORY_SIZE <agent-url>
This will print out the history size in bytes.
SEE ALSO
JMX::Jmx4Perl - Entry point for programmatic JMX access which is used
by this tool.
check_jmx4perl - a production ready Nagios check using JMX::Jmx4Perl
jolokia - utility for downloading and managing Jolokia agents
j4psh - readline based JMX shell with context sensitive command line
completion.
LICENSE
This file is part of jmx4perl.
Jmx4perl is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 2 of the License, or (at your
option) any later version.
jmx4perl is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along
with jmx4perl. If not, see <http://www.gnu.org/licenses/>.
AUTHOR
roland@cpan.org
perl v5.20.2 2015-09-16 JMX4PERL(1)
