Roland Huß > jmx4perl-0.75 > jmx4perl

Download:
jmx4perl-0.75.tar.gz

Annotate this POD

CPAN RT

Open  3
View/Report Bugs
Source   Latest Release: jmx4perl-1.10

NAME ^

jmx4perl - JMX access tools and modules

SYNOPSIS ^

  jmx4perl .... http://server:8080/j4p ["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 --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)
   --verbose               Print out more information

DESCRIPTION ^

jmx4perl is a command line utility for easily accessing 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.

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 pathes (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 pathes.

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.

HISTORY TRACKING ^

The agent j4p 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

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

syntax highlighting: