Geneos

JMX Plug-In - Technical Reference

Introduction

The JMX plug-in can connect to Java applications which expose their state in accordance with the JMX specification. The application exposes state in the form of managed beans (mbeans) each of which has attributes whose values can be retrieved. The plug-in can be configured to connect to the monitored application, look-up specific mbeans and retrieve the values of their attributes. These applications can include off-the-shelf applications such as WebSphere and WebLogic as well as bespoke-in-house Java applications.

Java requirements

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

Views

View

The plug-in produces a single view, a representative example of which is given below. Since the user is responsible for producing the contents of the view there is intentionally no reference to headline or table legends.

jmx_server_image16

Plug-In Configuration

Caution: When you update the configuration of certain Java-based plug-ins, including this one, the Netprobe running it has to restart. Be aware of other potentially unrelated plug-ins that can be affected when you configure this particular plug-in.

The plug-in parameters below describe how to configure a JMX plugin to connect to a WebLogic, WebSphere or Java application (e.g. Tomcat 6.0)

The following parameters can be configured for this plug-in:

connection

Describes the type of application to which the plug-in will attempt to connect and monitor.

Possible values:

Setting Description
Generic The plug-in should be configured to connect to a Java application that can be monitored via JMX
WebLogic The plug-in should be configured to connect to a WebLogic server that can monitored via JMX
WebSphere The plug-in should be configured to connect to a WebSphere server that can be monitored via JMX

Mandatory: Yes

connection > generic

Specifies connection settings to a Java application.

connection > generic > serviceURL

Specifies the location where the monitored application resides, e.g.

service:jmx:rmi:///jndi/rmi://192.168.10.161:25000/jmxrmi

For more granularity, the connectionDetails can be used instead. See section Connecting using the JMXMP protocol.

connection > generic > connectionDetails

This allows more granularity and can be used instead of serviceURL.

connection > generic > connectionDetails > host

The ip address (e.g. 192.168.10.161) or resolved host name (e.g. itrspc27) of the machine on which the monitored application runs.

connection > generic > connectionDetails > port

The port which the monitored application accepts connections on (e.g. 25000).

connection > generic > connectionDetails > urlPath

The part of the serviceUrl which appears after the port number, excluding the leading front-slash. For example, if the serviceUrl is:

service:jmx:rmi:///jndi/rmi://192.168.10.161:25000/jmxrmi

Then, the urlpath is specified as:

jmxrmi
connection > generic > jmxId

connection > generic > jmxId

This is the local Java application's process ID.

connection > generic > username

Specifies the username with which to connect to a secured Java application.

connection > generic > password

Specifies the password with which to connect to a secured Java application. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > generic > timeout

Specifies the number of milliseconds to wait for connections to be established or JMX commands to return. This setting should not be used unless it is found that the sampler seems to be waiting for inordinate amounts of time to connect to an application which is clearly down. This allows a timeout which the user decides is appropriate, for which to wait for a connection, before deciding that the application should be considered down.

Default: 10000

Unit: milliseconds (ms)

connection > websphere

Specifies connection settings to a WebSphere server.

connection > websphere > host

Specifies the location where the server resides (e.g. 192.168.10.200).

connection > websphere > port

Specifies the port on which to connect to the server (e.g. 8881).

connection > websphere > username

Specifies the username to use when connecting to the server.

connection > websphere > password

Specifies the password to use when connecting to the server. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > websphere > type

The protocol for the connection to use when sending and receiving information (e.g. SOAP).

connection > websphere > sslKeyStoreDetails > sslClientKeyStore

The keystore file which contains the client private key and certificate. Supports Java Key Store (JKS) and PKCS12 format. File extension should be .jks or .p12 (e.g. clientKeyStoreFile.jks).

connection > websphere > sslKeyStoreDetails > sslClientKeyStorePassword

The client keystore password. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > websphere > sslTrustStoreDetails > sslClientTrustStore

The client truststore that contains trusted signer certificates. Supports Java Key Store (JKS) and PKCS12 format. File extension should be .jks or .p12 (e.g. clientTrustStoreFile.jks).

connection > websphere > sslTrustStoreDetails > sslClientTrustStorePassword

The client trust store password. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > weblogic

Specifies connection settings to a WebLogic server.

connection > weblogic > java.naming.provider.url

Specifies the location where the server resides e.g.

t3://192.168.10.200:7011

In case of SSL-secured connection, the server location might be like:

t3s://192.168.10.200:7002

connection > weblogic > java.naming.security.principal

Specifies the principal to use when connecting to the server.

connection > weblogic > java.naming.security.credentials

Specifies the credentials to use when connecting to the server. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > weblogic > sslClientCertificateFile

Specifies the client certificate file (e.g. C:clientcert.pem).

connection > weblogic > sslClientCertificateKeyFile

Specifies the client certificate key file (e.g. C:clientkey.pem).

connection > weblogic > sslClientKeyPassword

Specifies the password to open the client keystore to read the client certificate file. To set an encrypted password, click on the "Set Password" button, then enter and confirm the password to be used.

connection > weblogic > MBean Server

This allows the user to select how to access the Weblogic MBeans.

Possible values:

MBean Server Description
Runtime MBean Server Allows the user to access MBeans of a specific Weblogic server instance.
Domain Runtime MBean Server Allows the user to access domain wide MBeans. The user will have a single access point for MBeans that exist in all Managed Servers. Only Admin server has an instance of this MBean server.

Mandatory: No
Default: Runtime MBean Server

aliases

Allows the user to specify one or more mbean using simple names. The idea is that specifying simple names here, the user can use these 'aliases' when constructing expressions to display in the rows of data.

Mandatory: Yes

aliases > alias

Used to refer to either a single managed bean or a set of managed beans, or -if an attribute path is specified- a set of one or more attributes within a managed bean. The alias name must be unique to other alias names and must start with a dollar symbol.

For example the following alias refers to a single managed bean:

$1=java.lang:type=GarbageCollector,name=Eden Space

For example the following alias refers to a set of zero or more managed beans:

$2=java.lang:type=GarbageCollector,*

Mandatory: Yes

aliases > alias > name

A name with which to identify an expression which resolves to a single or many mbeans e.g.

$1

Mandatory: Yes

aliases > alias > value

The value with which to associate with the name of an alias e.g.

java.lang:type=GarbageCollector,*

Mandatory: Yes

aliases > alias > attributePath

The path to an attribute within a managed bean. This path can contain basic filter expressions to narrow down sub-attributes within container attributes. e.g.

LastGcInfo.memoryUsageAfterGc[match(key,'Perm Gen.*')]

- match all items within

LastGcInfo.memoryUsageAfterGc

with a key value beginning "Perm Gen". The filter value should contain a valid regex pattern especially if it's a wildcard filter. Thus, in the example above, ".*" is used instead of "*" to get all keys that starts with "Perm Gen".

If -as will normally be the case- the attribute is a container (e.g. a TabularData object) then the attribute path must end in a filter expression (e.g. MyAttribute[*]).

See section Attribute Paths for more details.

Mandatory: No

aliases > alias > summary

In summary mode, the MBean alias combines multiple MBean instances into one (or morelogical instance(s) which can be displayed using summary functions. This allows the easy display of statistical data for multiple MBeans or MBean Attributes.

If a Summary MBean is displayed in the normal way (not using a summary function) then the first MBean instance will be used.

Mandatory: No

aliases > alias > summary > enable

Enable summary mode.

Mandatory: Yes

aliases > alias > summary > grouping

Optional parameter for grouping the summary MBeans. MBeans aliases can be grouped into multiple logical instances matching on the grouping parameter. If no grouping parameter is specified then the alias will always map to a single instance combining all MBeans, if a grouping parameter is used then the alias can map to multiple instances each combining a subset of the MBeans.

For example, if thealias value was "java.lang:type=MemoryPool,*" and the grouping parameter was "Type" we would expect the alias to map to two grouped instances, one of Type "HEAP" and the other of Type "NON_HEAP" - each mapping to more than one MBean.

Grouped Summary MBeans can only be displayed using column mode. If they are referenced in row mode> or headline variables, only the first group will be returned.

Grouping parameters can either be attributes within the MBean or key properties of the MBean. To specify that the parameter is an attribute it can prefixed with a full stop, to specify that the parameter is a key property it can be prefixed with a colon. If no prefix is used, key properties will be searched first, followed by attributes.

Mandatory: No

aliases > alias > showCommands

Allows the user to control command generation for any combination of headlines, table cells, dataviews and samplers. If enabled and ticked then this ensures commands are generated for this alias. If disabled (or enabled and unticked), then commands are not generated.
Mandatory: No
Default: The default behaviour is for commands not to be generated.

Note: Currently, commands are not supported for WebLogic and WebSphere JMX.

headlines

Allows the user to specify the name, value, mask for each headline that they wish to see.

Mandatory: No

headlines > headline

Describes the label to use for a headline and the expression to evaluate and display as its value.

Mandatory: No

headlines > headline > name

The label to display for a particular headline

Mandatory: No

headlines > headline > value

The expression to evaluate and display as the value for a particular headline. The Alias (for example: $1) value should not have a wildcard (*) character and should return a single MBean. An error message is displayed when a wildcard alias is used.

Mandatory: No

headlines > headline > mask

The mask with which to format the value of a particular headline

Mandatory: No

rows

Identifies the values to display for each row in the dataview.

Mandatory: Yes

rows > columnLabels

Describes the labels to use for each of the column headers in the table.

Mandatory: Yes

rows > columnMasks

Describes the masks to use to format each row value with

Mandatory: Yes

rows > row

Describes the expressions or string literals to display for each cell in a particular row.

See section Attribute Paths for more details.

Mandatory: Yes

columns

Describes the columns that should comprise the dataview. Consists of one or more column instances, each of which describe both a column header and an expression to evaluate for a cell in that column.

Mandatory: Yes

columns > column

Describes what to label a table column header and provides an expression to evaluate as the row value for that column.

Mandatory: Yes

columns > column > label

The name to display as a column header for a particular column

Mandatory: Yes

columns > column > rowTemplate

The expression to evaluate as the value of a cell in a particular column with. This can be an mbean expression or an objectname expression.

An mbean expression makes use of one or more dot-delimited attributes on an mbean with an optional quoted literal e.g.

($1.Uptime + $1.Downtime) 'secs'

An objectname expression makes use of colon-delimited fields on an objectname using quoted literals to separate each field e.g.

$1:type '/' $1:index '/'

Dot-delimited attribute paths can contain filter expressions. E.g.

$1.LastGcInfo.memoryUsageAfterGc[key='Perm Gen']

- returns the child object within LastGcInfo.memoryUsageAfterGc where the key value equals "Perm Gen".

See section Attribute Paths for more details.

If a summary MBean alias is being references then summary functions can be used.

max($1.value)

Mandatory: Yes

columns > column > mask

The mask with which to format the value of a cell in a particular column with

Mandatory: Yes

jproperties

Holds a list of properties that can be used to configure how the JVM is created.

Mandatory: No

jproperties > jproperty

Allows user to specify a comma separated list of supported JVM arguments. This comprises those flags which begin with -D or the -verbose flag. Flags starting with -X are JVM implementation dependent and may or may not work.

For example,

JProperties=-Xms2M,-Xmx4M,-verbose

Mandatory: No

idAttributes

Allows the user to specify a way of uniquely identifying several mbeans, each of which were located using a common mbean expression.

Mandatory: No
Deprecated: Yes: Do NOT use this setting; use RowTemplateSet instead.

idAttributes > idAttribute

Used to to create an id to identify each of several mbeans which have no uniquely identifying attribute. For example, suppose you have an MBean alias.

$1 = java.lang:type=Geneos, *

which evaluates to 2 Mbeans with these objectnames

java.lang:type=Geneos,host=WinBox, port=3344, os=Vista
java.lang:type=Geneos,host=SunBox, port=4455, os=Solaris5.8

Now suppose that the mbeans have no attribute which uniquely identifies them. How would the user differentiate between each? Ideally we would like to have a leading column in the dataview called Id, that hold a unique id for each mbean. Since an objectname uniquely identifies each mbean, we would like to compose this id using values from that objectname. We don't want to automatically use the objectname as the id, since some objectnames are very, very long !

If you now specify 3 idAttribute instances with the names os, host and port, an Id column will now be displayed in the dataview. Each entry in that column will contain an id which uniquely identifies each row. This id will be created by conjoining the values matching os, host and port in that mbean's objectname.

So in our example, we would end up with an Id column which looks like this

Id
Vista/WinBox/3344
Solaris5.8/SunBox/4455

We recommend using the IdAttribute parameter if you use an MBean alias which evaluates to multiple Mbeans and those MBean do not have a unique attribute suitable for distinguishing one from the other.

Mandatory: No
Deprecated: Yes: use RowTemplateSet instead.

exclusionList

A list of comma-delimited key-value pairs which are matched against the key-value pairs of the objectnames of each of the returned mbeans. If all the key-value pairs are matched, that mbean's attributes are not published.

For example, suppose you have an MBean alias

$1 = earth.insect:type=Ant, *

which evaluates to 3 Mbeans with these objectnames:

earth.insect:type=Ant, name=Pharaoh
earth.insect:type=Ant, name=Fire
earth.insect:type=Ant, name=Thief*

and you specify the following exclusion list

ExlusionList
name=Thief
name=Fire*

Then only the following mbeans are eligible to be published:

earth.insect:type=Ant, name=Pharaoh*

Mandatory: No

private logJavaMemoryInfo

Whether Java memory consumption statistics should be written to the netprobe log file or not. This is useful if you suspect that the plug-in is consuming large amounts of memory and you need to ascertain whether this is happening in the JVM or in the netprobe.

Mandatory: No

Attribute Paths

Attribute Paths can be used within the MBean alias > alias parameter and within the rows > row > value or columns > column > rowTemplate parameters. An attribute path is a drill down into attributes and sub-attributes of a bean using a dot-delimited path.

E.g. a.b.c

Collection Filters

Where an attribute is a collection type (e.g. TabularData or CompositeData) its children can be reduced to a sub-set using a collection filter. These objects can be reference by either index or search filters. An example of these types is represented using the java.lang.Runtime object's SystemProperties attribute. Using Java's JConsole, the following represents that object.

jmx_server_image57

SystemProperties attribute of java.lang.Runtime is an instance of TabularDataSupport, which is an instance based on java.util.Map. This property contains a key-value pair.

jmx_server_image58

The above object and attribute will be used in the example as we describe the options on how to access TabularDataSupport using the attributePath.

The following Collection Filters are supported:

  • [*] — returns all sub-objects.
  • [match(attribute, 're')] — returns all sub-objects where the specified attribute matches a regular expression.

Note: The attribute itself can be a dot-delimited path to a sub-attribute.

For example, getting the value with key of java.class.version, first define the Alias with attributePath that filters the SystemProperties using the match format:

jmx_server_image63

Regular expression must be enclosed with either single or double quote. You can now reference the value or key attribute of the item to be returned:

jmx_server_image64

Having these setup the output in the metrics view should display the '50' as the value.

jmx_server_image65

You can search not only by key, but using either of all attributes. For example, rather than key search the TabularDataSupport by value:

jmx_server_image66

Having the example above as configured for the attibutePath we can access the item and display the key instead.

  • [attribute = 'value']: Lookup child object where the specified attribute exactly matches a regular expression.

Note: The attribute can itself be a dot-delimited path to a sub-attribute.

Example use of this method is as follows:

jmx_server_image67

This should output the value that matches the whole string of 'java.runtime.version':

jmx_server_image68

Look up or filter by value or any other attribute can also be used in this option.

  • [#num]: Lookup an element in a container by index number. Index starts with zero (0).

jmx_server_image69

jmx_server_image70

Note: The index item shown by the JConsole might differ from the item being reference by the plugin.

Typically the collection filter should map to only one sub-object within a row > value or rowTemplate expression. In the case that it maps to multiple objects only the first will be used. Within an MBean Alias where a Column Style setup is used, a filter may well map to multiple objects.

Summary Functions

When an MBean alias is specified as being a summary of multiple MBeans, summary functions should be used to display it. These have the format:

function($1.attributePath)

Summary functions can form part of a composite expression (e.g. "max($1.size) / 1000"), but composite expressions are not permitted within a summary function (e.g. "max($1.size /1000)" is not supported).

The following functions are supported:

  • max: returns the maximum value
  • min: return the minimum value
  • avg: returns the average (mean) value
  • sum: returns the total value
  • count: returns a count of the MBean instances

Note: This still requires a valid attribute path in the argument, even though this will be ignored e.g. count($1.somethingIrrelevant) - returns the number of MBeans that $1 maps to.

Summary functions used on non-summary MBean Aliases will be ignored.

Current Limitations

Attribute Names

Attribute names can consist of alphanumeric characters and the following special characters:


 <space> . / ~ ! @ # $ % ^ & * ( ) { } | \ _ + ` - = ; < > ? '

However, when using these special characters, the attribute name will have to be enclosed in double quotes (") so as to prevent ambiguity when determining the attribute path. An example of ambiguity with attribute names is the following:

$1.number of partitions

The attribute name could either be 'number', 'number of' or 'number of partitions'. A correct way of setting the attribute name can be:

$1."number of partitions"

The following special characters also must not be at the end of an attribute name (can be put at the strt and at the middle if the attribute name):

<space> . / ~ ! @ # $ % ^ & * ( ) { } | \ _ + ` - = ; < > ? '

Attribute Types

The requested attribute must be either a primitive (e.g. boolean, short, integer, long, float, double) or a reference type java.lang.Long or a reference to an object for which toString() has been overidden to provide a sensible human viewable value. If an attribute is requested which violates these constraints, then the information published to the dataview is likely to not be useful. Please see section How to configure plug-in to connect to a Java application for some exceptions to this rule.

Whitespaces in MBean Aliases

The plug-in does not accept mbean aliases that contain leading or trailing whitespace. It does however, accept mbean aliases which contain whitespace within the actual alias.

Connect to a WebLogic 10.x server

Note: Beginning Geneos 4.x.x, this plugin no longer supports connection on WebLogic 9.x. To view the versions that the JMX plugin supports, see Application and plug-in specific information in 5.x Compatibility Matrix.

Required Software

To be able to successfully run the jmx-plugin you need to ensure that you have all of the following software. Each binary can be retrieved from the vendor specified after its name. See http://docs.oracle.com/cd/E12840_01/wls/docs103/client/jarbuilder.html for instructions on how to build the wlfullclient.jar. Once you have built this file you need to rename to weblogic.jar otherwise the plugin will not recognise it and will fail to work properly. The Java Runtime can be freely downloaded from www.javasoft.com. Please ensure that the Java Runtime you download and install is the same as the version used by the WebLogic server to avoid possible incompatibility issues.

WindowsSolarisLinuxAIX
netprobe.windows.exe ITRSnetprobe.sun ITRSnetprobe.linux ITRSnetprobe.aix ITRS
geneos-plugins.jar ITRSgeneos-plugins.jar ITRSgeneos-plugins.jar ITRSgeneos-plugins.jar ITRS
launchpad.dll ITRSliblaunchpad.so ITRSliblaunchpad.so ITRSliblaunchpad.so ITRS
weblogic.jar ORACLEweblogic.jar ORACLEweblogic.jar ORACLEweblogic.jar ORACLE
Java Runtime ORACLEJava Runtime ORACLEJava Runtime ORACLEJava Runtime ORACLE

The ITRS resources are bundled in the Netprobe binary package, which you can download from ITRS Downloads.

Note: You must not use the weblogic.jar found in the weblogic 10 installation. It is not a self-contained file and the plugin will not be able to work with it. You must follow the steps outlined in the link above to create wlfullclient.jar, rename that to weblogic.jar and ensure that your netprobe use that instead. You must also ensure that the Java version you use to build wlfullclient.jar is the same version as that used by the weblogic server otherwise you will have problems using the jar file that gets built due to versioning incompatibilities.

For Weblogic 10.3.6:

weblogic.jar
cryptoj.jar
EccpressoCore.jar

For Weblogic 12.1.1:

weblogic.jar
cryptoj.jar

Java requirements

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

Validating environment and server reachability

To validate that the environment is correctly configured, the plugin should be run in diagnostics mode. The plugin attempts to connect to the WebLogic server, request the names of its managed beans and displays those names to standard out. For example, assuming the server resides on 192.168.10.200 and is listening on port 7011 and accepts the username and password of weblogic then you can type in the following command on a single line:

JMX API implementation:

C:\> java -jar geneos-plugins.jar jmx WebLogicJmxApi t3://192.168.10.200:7011 weblogic weblogic

Deprecated implementation:

C:\> java -jar geneos-plugins.jar jmx WebLogic t3://192.168.10.200:7011 weblogic weblogic

If the attempt to connect is successful the plugin should print the names of all the managed beans known to the server to standard out. It should also print out the type, name and value for each managed bean attribute that it finds. If for some reason it cannot retrieve the value for a particular attribute, it should display the message "ERROR - Could not retrieve value" for the value of that attribute.

Single managed bean sampler configuration

This example assumes that the example Medical Records application which comes bundled with the WebLogic server has been started up and is now fully initialised. It is an intentionally minimal bare bones example designed to show an example configuration when using the mbean alias (com.bea: Name=MedRecServer,Type=ServerRuntime) which resolves to a unique managed bean.

<sampler name="2-3-4">
    <plugin>
        <jmx-server>
            <connection>
                <weblogic>
                    <java.naming.provider.url>
                        <data>t3://192.168.10.200:7011</data>
                    </java.naming.provider.url>
                    <java.naming.security.principal>
                        <data>weblogic</data>
                    </java.naming.security.principal>
                    <java.naming.security.credentials>
                        <data>weblogic</data>
                    </java.naming.security.credentials>
                    <sslDetails>
                    </sslDetails>
                </weblogic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>com.bea: Name=MedRecServer,Type=ServerRuntime</data>
                    </value>
                </alias>
            </aliases>
            <rows>
                <columnLabels>
                    <label>
                        <data>Attribute</data>
                    </label>
                    <label>
                        <data>Value</data>
                    </label>
                </columnLabels>
                <row>
                    <value>
                        <data>HealthState,$1.HealthState</data>
                    </value>
                </row>
            </rows>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Multiple managed bean sampler configuration

This example assumes that the example Medical Records application which comes bundled with the WebLogic server has been started up and is now fully initialised. It is an intentionally minimal bare bones example designed to show an example configuration when using the mbean alias (com.bea:Type=ExecuteQueueRuntime,*) which resolves to a list of zero or more managed beans.

<sampler name="2-3-5">
    <plugin>
        <jmx-server>
            <connection>
                <weblogic>
                    <java.naming.provider.url>
                        <data>t3://192.168.10.200:7011</data>
                    </java.naming.provider.url>
                    <java.naming.security.principal>
                        <data>weblogic</data>
                    </java.naming.security.principal>
                    <java.naming.security.credentials>
                        <data>weblogic</data>
                    </java.naming.security.credentials>
                    <sslDetails>
                    </sslDetails>
                </weblogic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>com.bea:Type=ExecuteQueueRuntime,*</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>Queue Name</label>
                    <rowTemplate>
                        <data>$1.Name</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>Total Threads</label>
                    <rowTemplate>
                        <data>$1.ExecuteThreadTotalCount</data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Connect to a WebLogic server using an SSL-secured connection

Required Software

To be able to successfully run the jmx-plugin you need to ensure that you have all of the following software. Each binary can be retrieved from the vendor specified after its name. The weblogic.jar should be retrieved from the user's own WebLogic installation. The Java Runtime can be freely downloaded from www.javasoft.com. Please ensure that the Java Runtime you download and install is the same as the version used by the WebLogic server to avoid possible incompatibility issues.

WindowsSolarisLinuxAIX
netprobe.windows.exe ITRSnetprobe.sun ITRSnetprobe.linux ITRSnetprobe.aix ITRS
geneos-plugins.jar ITRSgeneos-plugins.jar ITRSgeneos-plugins.jar ITRSgeneos-plugins.jar ITRS
launchpad.dll ITRSliblaunchpad.so ITRSliblaunchpad.so ITRSliblaunchpad.so ITRS
weblogic.jar ORACLEweblogic.jar ORACLEweblogic.jar ORACLEweblogic.jar ORACLE
EccpressoCore.jar ORACLEEccpressoCore.jar ORACLEEccpressoCore.jar ORACLEEccpressoCore.jar ORACLE
Java Runtime ORACLEJava Runtime ORACLEJava Runtime ORACLEJava Runtime ORACLE

The ITRS resources are bundled in the Netprobe binary package, which you can download from ITRS Downloads.

Note: For WebLogic 10 installation, you must not use the weblogic.jar found in the weblogic 10 installation. It is not a self-contained file and the plugin will not be able to work with it. You must follow the steps outlined in the link above to create wlfullclient.jar, rename that to weblogic.jar and ensure that your netprobe use that instead. You must also ensure that the java version you use to build wlfullclient.jar is the same version as that used by the weblogic server otherwise you will have problems using the jar file that gets built due to versioning incompatibilities.

Java requirements

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

Validating environment and server reachability

To validate that the environment is correctly configured, the plugin should be run in diagnostics mode. The plugin attempts to connect to the WebLogic server, request the names of its managed beans and displays those names to standard out. For example, assuming the server resides on 192.168.10.200 and is listening on SSL port 7002 and accepts the username and password as weblogic and the client certificate and key files and key password (optional) are clientkey.pem, clientcert.pem and keypass respectively, then you can type in the following command on a single line:

JMX API implementation:

C:\> java -jar geneos-plugins.jar jmx WebLogicJmxApi t3s://192.168.10.200:7002 weblogic weblogic clientkey.pem clientcert.pem keypass

Deprecated implementation:

C:\> java -jar geneos-plugins.jar jmx WebLogic t3s://192.168.10.200:7002 weblogic weblogic clientkey.pem clientcert.pem keypass

In the above command,

  1. t3s is the WebLogic proprietary protocol used to communicate over SSL
  2. 7002 is the default SSL port for WebLogic server
  3. PEM is the Privacy Enhanced Mail (PEM) extension where the certificate is stored in base 64-encoding
  4. The password is optional and is required to open the client keystore to read the client certificate if it is encrypted.
  5. For production version, a certifying authority such as Verisign, Entrust etc provide digitally signed client certificates which can be trusted by the WebLogic server.
  6. For test purpose, one can use the java Certgen or Sun Microsystem's keytool to create the client certificates.

If the attempt to connect is successful the plugin should print the names of all the managed beans known to the server to standard out. It should also print out the type, name and value for each managed bean attribute that it finds. If for some reason it cannot retrieve the value for a particular attribute, it should display the message "ERROR - Could not retrieve value" for the value of that attribute.

Configuring connection settings

The following connection settings need to be added:

jmx_server_image134

Or equivalent xml:

<connection>
        <weblogic>
                <java.naming.provider.url>
                        <data>t3s://192.168.10.200:7002</data>
                </java.naming.provider.url>
                <java.naming.security.principal>
                        <data>weblogic</data>
                </java.naming.security.principal>
                <java.naming.security.credentials>
                        <data>weblogic</data>
                </java.naming.security.credentials>
                <sslDetails>
                        <SSLClientCertificateFile>
                                <data>clientkey.pem</data>
                        </SSLClientCertificateFile>
                        <SSLClientCertificateKeyFile>
                                <data>clientcert.pem</data>
                        </SSLClientCertificateKeyFile>
                        <password>
                                <stdAES>+encs+F9F29CF67AFA80F117FA3961A3ED370D</stdAES>
                        </password>
                </sslDetails>
        </weblogic>
</connection>

Configuring Advanced JProperties settings

To connect to an SSL-secured JMX application, the plug-in needs to be configured with few jproperties, so that it can successfully connect to the application.

//Jproperties
-Dweblogic.home=\path\to\bea\wlserver_x.x\server
-Dweblogic.security.TrustKeyStore=DemoTrust

The weblogic home location is required because WebLogic searches for TrustKeyStore under weblogic_homelib folder. So, one can specify -Dweblogic.home=. and copy the TrustKeyStore file in the Netprobe folder. In above example, DemoTrust is the default trust keystore configured with Weblogic Server. It is not advisable to use this default Trust KeyStore. Instead, one should use the CustomTrust KeyStore and specify it in JProperties as:

//Jproperties
-Dweblogic.home=\path\to\bea\wlserver_x.x\server
-Dweblogic.security.TrustKeyStore=CustomTrust
-Dweblogic.security.CustomTrustKeyStoreFileName=<TrustKeyStoreFile>-Dweblogic.security.CustomTrustKeyStorePassPhrase=<password>

There are some optional settings that may be required depending upon the configuration:

//Optional Jproperties:
-Dweblogic.security.SSL.ignoreHostnameVerification=true

Above setting to be used to set off strict host name verification in case when one gets a Host name Verification failure error.

//Optional SSL debug Jproperties:
-Dssl.debug=true
-Dweblogic.StdoutDebugEnabled=true

These settings turn on extra SSL debug option and produce more output in the Netprobe log in case of any problem.

Connect to a Weblogic server using one-way SSL

To connect JMX plug-in to Weblogic using one-way SSL, follow these steps:

  1. Create the wlfullclient.jar for JDK 1.6 client application.
  2. Go to bea\wlserver\server\lib
  3. Use this command to create wlfullclient.jar in the server/lib directory.
  4. java -jar wljarbuilder.jar
  5. Rename the created wlfullclient.jar to weblogic.jar
  6. Copy the following files from bea\wlserver\server\lib to your Netprobe folder.
  7. For Weblogic 10.3.6:

    weblogic.jar
    cryptoj.jar
    EccpressoCore.jar

    For Weblogic 12.1.1:

    weblogic.jar
    cryptoj.jar
  8. Create a lib folder in your Netprobe directory.
  9. Copy DemoTrust.jks from bea\wlserver\server\lib to netprobe\lib folder.
  10. Define the following environment variables in your Netprobe startup script.
  11. setenv JAVA_HOME /usr/java/jdk1.6.0_45/jre
    setenv LD_LIBRARY_PATH $JAVA_HOME/lib/i386:$JAVA_HOME/lib/i386/client:/home/dev/netprobe:.
    setenv PATH $JAVA_HOME/bin:$PATH
  12. In Gateway Setup Editor, kindly add the following java arguments in JMX plug-in Advanced > Jproperties.
  13. -Dweblogic.home=<netprobe_dir>

    This argument tells where the lib folder can be located which contains the DemoTrust.jks file.

    -Dweblogic.security.SSL.ignoreHostnameVerification=true

    This argument tells that the server's host name will not be verified since we're using demo or self-signed certificates.

    -Dweblogic.security.TrustKeyStore=DemoTrust

    This argument is only used if you are using the demo certificates.

  14. Run the Netprobe using start_netprobe script.

Connect to a WebSphere 8.5.5.x server

Note: Beginning Geneos 4.x.x, this plugin no longer supports connection on WebSphere 6.x. To view the versions that the JMX plugin supports, see Application and plug-in specific information in 5.x Compatibility Matrix.

Required Software

To be able to successfully run the JMX plugin, you need to ensure that you have all of the following software. Each binary can be retrieved from the vendor specified after its name.

For WebSphere 8.5.5.0, the com.ibm.ws.admin.client_8.5.0.jar should be retrieved from the user's own WebSphere installation and renamed to websphere.jar. The com.ibm.ws.orb_8.5.0.jar should be retrieved from the user's own WebSphere installation.

WindowsSolarisLinuxAIX
netprobe.windows.exe ITRSnetprobe.sun ITRSnetprobe.linux ITRSnetprobe.aix ITRS
geneos-plugins.jar ITRSgeneos-plugins.jar ITRSgeneos-plugins.jar ITRSgeneos-plugins.jar ITRS
launchpad.dll ITRSliblaunchpad.so ITRSliblaunchpad.so ITRSliblaunchpad.so ITRS
websphere.jar IBMwebsphere.jar IBMwebsphere.jar IBMwebsphere.jar IBM
Java Runtime ORACLEJava Runtime ORACLEJava Runtime ORACLEJava Runtime ORACLE
    

The ITRS resources are bundled in the Netprobe binary package, which you can download from ITRS Downloads.

Note: If you do not rename com.ibm.ws.admin.client_<version>.jar to websphere.jar then the plugin will not be able to use it and the netprobe will not work as expected.

For SSL connections:

The WebSphere JMX plugin requires IBMJSSE2 which ships with IBM SDK and WebSphere bundled Java. Plugin will show an error message if IBMJSSE2 provider is not available.

It also requires com.ibm.ws.security.crypto_<version>.jar which can be retrieved from <websphere_installation_dir>/plugins folder. It should be copied into the Netprobe directory and renamed to com.ibm.ws.security.crypto.jar.

There's also a known issue when both websphere.jar and weblogic.jar exists in the classpath / Netprobe directory. WebSphere will not work properly due to a class conflict. The solution is to modify websphere.jar by following these steps:

  1. Extract websphere.jar in a directory. (e.g. /extractedJar)
  2. Go to the folder META-INF/services (e.g. /extractedJar/META-INF/services)
  3. Create a file named javax.xml.parsers.DocumentBuilderFactory
  4. The file should contain the classname org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
  5. Create the new websphere.jar using an archiving tool (e.g. 7Zip, etc). Add all the contents of the folder /extractedJar to the archive.
  6. Change the file extension of the archive file to jar.
  7. Make sure the folder structure of the new archive is the same as the original websphere.jar. The folder META-INF should be on the root of the archive.

Note: The parser class in step 4 is only available in IBM SDK. Using the modified WebSphere.jar in an Oracle JDK will generate a NoClassDefFoundError.

Java requirements

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

When using SSL connections, an IBM SDK is required. The IBM SDK is only available Linux and IBM AIX. Win32 support is only available for IBM system:

setenv JAVA_HOME /usr/java/ibm-java-i386-60/jre
setenv LD_LIBRARY_PATH $JAVA_HOME/lib/i386/j9vm
setenv PATH $JAVA_HOME/bin:$PATH

Validating environment and server reachability

To validate that the environment is correctly configured, the plugin should be run in diagnostics mode. The plugin attempts to connect to the WebSphere server, request the names of its managed beans and displays those names to standard out. For example, assuming that the server resides on 192.168.10.200 and is listening on port 8880 and accepts the username and password of websphere, then you can type in the following command on a single line:

C:\> java -jar geneos-plugins.jar jmx WebSphere 192.168.10.200 8880 websphere websphere SOAP

For SSL connections:

C:\> java -jar geneos-plugins.jar jmx WebSphere 192.168.10.200 8880 websphere websphere SOAP <clientTrustFile.jks> <clientTrustPassword> <clientKeyFile.jks> <clientKeyPassword>

If the attempt to connect is successful the plugin should print the names of all the managed beans known to the server to standard out. It should also print out the type, name and value for each managed bean attribute that it finds. If for some reason it cannot retrieve the value for a particular attribute, it should display the ERROR - Could not retrieve value message for the value of that attribute.

Single managed bean sampler configuration in WebSphere 8.5.5

This example assumes that an instance of WebSphere 8.5.5 server has been started up on a machine where the WebSphere Application Server or WAS855_HOST has its running docker and port.

<sampler name="WAS855_template">
    <plugin>
        <jmx-server>
            <connection>
                <websphere>
                    <host>
                        <var ref="WAS855_HOST"></var>
                    </host>
                    <port>
                        <var ref="WAS855_PORT"></var>
                    </port>
                    <type>
                        <var ref="WAS855_TYPE"></var>
                    </type>
                    <sslKeyStoreDetails></sslKeyStoreDetails>
                    <sslTrustStoreDetails></sslTrustStoreDetails>
                </websphere>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>WebSphere:name=JVM,process=nodeagent,platform=proxy,node=node01,j2eeType=JVM,J2EEServer=nodeagent,version=8.5.5.0,type=JVM,mbeanIdentifier=JVM,cell=cell01,spec=1.0</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>Java Vendor</label>
                    <rowTemplate>
                        <data>$1.javaVendor</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>Java Version</label>
                    <rowTemplate>
                        <data>$1.javaVersion</data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>pet>

How to configure plug-in to connect to a Java application

Caution: The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read Configure the Java environment to help you understand your Java installation.

Validating environment and reachability for remote application

To validate that the environment is correctly configured, the plugin should be run in diagnostics mode. The plugin attempts to connect to the Java application, request the names of its managed beans and displays those names to standard out. For example, assuming the application resides on 192.168.10.200 and is listening on port 5003 then you can type in the following command on a single line. The value 4000 represents how long the application should wait (in milliseconds) before timing out and the jmxrmi is the value of the url path.

C:\> java -jar geneos-plugins.jar jmx Generic rmi:///jndi/rmi 192.168.10.200 5003 4000 jmxrmi *:*

If the attempt to connect is successful the plugin should print the names of all the managed beans known to the JVM that the monitored Java application runs within to standard out. It should also print out the type, name and value for each managed bean attribute that it finds. If for some reason it cannot retrieve the value for a particular attribute, it should display the message "ERROR - Could not retrieve value" for the value of that attribute.

Note: You must ensure that the Java application has been started up using special command line flags which enable clients to monitor its state via JMX.

For example, the following starts up a Java application called MyJavaApplication.jar and allows clients to retrieve its state via JMX calls to it on port 5003:

java    -Dcom.sun.management.jmxremote
        -Dcom.sun.management.jmxremote.port=5003
        -Dcom.sun.management.jmxremote.ssl=false
        -Dcom.sun.management.jmxremote.authenticate=false
        -jar MyJavaApplication.jar

Note: If the application you intend to connect to is secured by a username/password pair as described in section Connecting to applications using password and access files , then you need to additionally provide the user name and password file when running the jar file in this diagnostics mode. In the example below, we assume that the application is secured with the username of kyoto and a password of origami.

C:\> java -jar geneos-plugins.jar jmx Generic rmi:///jndi/rmi 192.168.10.200 5003 4000 jmxrmi *:* kyoto origami

Note: If the application you intend to connect to uses the JMXMP protocol the URI needs to be constructed slightly differently and you may need to have additional JAR files in the working directory. Please see section Connecting using the JMXMP protocol for more details.

Validating environment and reachability for local application

To validate that the environment is correctly configured, the plugin should be run in diagnostics mode. The plugin attempts to connect to the Java application, request the names of its managed beans and displays those names to standard out. For example, assuming the application resides on a communal box and has been started as a local application with a unique identifier called XXX and with a timeout of 5000 milliseconds e.g.

java -Dcom.sun.management.jmxremote -jar MyJavaApplication.jar XXX 5000

To connect to this application, you need to run the geneos-plugins.jar, passing it the location of where the JavaJRE is installed as the value of the java.home variable and the location of the directory in which the attach library exists as the value of the java.library.path variable.

The examples below demonstrate how to do this for the Windows, Linux and Solaris platforms.

Note: The command must all be on 1 line; it has been split below to make it easier for you to see its different parts.

Windows

"C:\Program Files (x86)\Java\jre1.6.0_12\bin"\java
-Djava.library.path="C:\Program Files (x86)\Java\jre1.6.0_12\bin"
-Djava.home="C:\Program Files (x86)\Java\jre1.6.0_12"
-jar geneos-plugins.jar jmx Local XXX 5000

Note: Part of connecting to a local application involves listing all Java processes to locate the one identified by the unique id. This requires the existence of a directory identified by an environment variable called TMP. If this environment variable is undefined or is defined but points to a non-existent directory, then the plug-in will be unable to get information on the Java processes and thus be unable to connect to the local application. To fix this problem you can create a directory called tmp and point to it e.g. set TMP=C:\tmp

Linux

/usr/java/jre1.6.0_06/bin/java
-Djava.library.path=/usr/java/jre1.6.0_06/lib/i386
-Djava.home=/usr/java/jre1.6.0_06
-jar geneos-plugins.jar jmx Local XXX 5000

Solaris

/usr/jre1.6.0_06/bin/java
-Djava.library.path=/usr/jre1.6.0_06/lib/sparc
-Djava.home=/usr/jre1.6.0_06
-jar geneos-plugins.jar jmx Local XXX 5000

If the attempt to connect is successful the plugin should print the names of all the managed beans known to the JVM that the monitored Java application runs within to standard out. It should also print out the type, name and value for each managed bean attribute that it finds. If for some reason it cannot retrieve the value for a particular attribute, it should display the message "ERROR - Could not retrieve value" for the value of that attribute.

Single managed bean sampler configuration (Remote Application)

This example assumes that the monitored Java application has been started up as described above and is now fully loaded. It is an intentionally minimal bare bones example designed to show an example configuration when using the mbean alias (java.lang:type=Runtime) which resolves to a unique managed bean.

<sampler name="2-5-4">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=Runtime</data>
                    </value>
                </alias>
            </aliases>
            <rows>
                <columnLabels>
                    <label>
                        <data>ClassPath</data>
                    </label>
                    <label>
                        <data>LibraryPath</data>
                    </label>
                </columnLabels>
                <row>
                    <value>
                        <data>$1.ClassPath,$1.LibraryPath </data>
                    </value>
                </row>
            </rows>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Single managed bean sampler configuration (Local Application)

This example assumes that the monitored Java application has been started up as described above and is now fully loaded. It is an intentionally minimal bare bones example designed to show an example configuration when using the mbean alias (java.lang:type=Runtime) which resolves to a unique managed bean.

<sampler name="8096-win">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <jmxId>
                        <data>MyUniqueID</data>
                    </jmxId>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=Runtime</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>ClassPath</label>
                    <rowTemplate>
                        <data>$1.ClassPath</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>LibraryPath</label>
                    <rowTemplate>
                        <data>$1.LibraryPath </data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Note: JMXID should be the same unique string with which the monitored application has been started with.

Multiple managed bean sampler configuration

This example assumes that the monitored Java application has been started up as described above and is now fully loaded. It is an intentionally minimal bare bones example designed to show an example configuration when using the mbean alias (java.lang:type=GarbageCollector,*) which resolves to a list of zero or more managed beans.

<sampler name="2-5-5">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=GarbageCollector,*</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>CollectionTime</label>
                    <rowTemplate>
                        <data>$1.CollectionTime</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>CollectionCount</label>
                    <rowTemplate>
                        <data>$1.CollectionCount</data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Connections established between the Netprobe to the JMX-enabled Java application

The Netprobe connects to the JMX-enabled Java application on the first sample of the plug-in, and reuses the connection for succeeding samples. For example, consider three JMX samplers:

  • Sampler 01 is connecting to Java application A.
  • Sampler 02 is connecting to Java application A.
  • Sampler 03 is connecting to Java application B.

The effect of this is that the Netprobe only creates two connections:

  • One connection to Java application A.
  • Another connection to Java application B.

The Netprobe also keeps the connection open. Therefore, Sampler 01 and Sampler 02 shares the same connection to Java application A.

Connecting to applications using password and access files

Java supports the use of password files and access files to restrict access to a jmx-enabled application. In this case the plugin also needs to provide a username and password before being allowed to connect to and retrieve information from the application.

We explain how to configure a sample Java application for authenticated access and then show how to configure the plugin to connect to that application. The instructions given are suitable for UNIX and LINUX.

Please see http://java.sun.com/j2se/1.5.0/docs/guide/management/security-windows.html for instructions on how to secure an application for windows.

Securing the application

The first thing to ensure is that we have a valid rolename-permission pair in the access file that resides inside the JRE installation directory i.e. $JRE/lib/management/jmxremote.access:

By default the following rolename-permission pairs exist:

monitorRole     readonly
controlRole     readwrite

So we add our own entry choosing kyoto as our rolename and granting it readwrite access. Our file should now look like this:

monitorRole     readonly
controlRole     readwrite
kyoto           readwrite

We then create a local password file called jmxremote.password in our current working directory for the java application. We need to chmod 600 the file otherwise Java will complain and not use the file. We then add our rolename along with origami as the password of our choice.

The jmxremote.password file should now look like this:

kyoto           origami
Assuming our application is a standalone class file called JmxServer we can now start the application passing the following flags to the Java command:
java    -Dcom.sun.management.jmxremote
        -Dcom.sun.management.jmxremote.port=5003
        -Dcom.sun.management.jmxremote.ssl=false
        -Dcom.sun.management.jmxremote.authenticate=true
        -Dcom.sun.management.jmxremote.password.file=jmxremote.password
        JmxServer

Note: We have now specified true for the authenticate flag and passed in the absolute path of where to find the jmxremote.password file.

Finally we configure a jmx-generic plugin to connect to our secured application and retrieve information about the garbage collectors currently running in its JVM.

Note: The password is encrypted to prevent it being displayed in plaintext in the configuration file:

<sampler name="2-7-1">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                    <username>
                        <data>kyoto</data>
                    </username>
                    <password>
                        <stdAES>+encs+DEB9AA8E492C4CFDD274DE66BDF08BFC</stdAES>
                    </password>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=GarbageCollector,*</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>CollectionTime</label>
                    <rowTemplate>
                        <data>$1.CollectionTime</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>CollectionCount</label>
                    <rowTemplate>
                        <data>$1.CollectionCount</data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Note: Microsoft.VC80.CRT redistributables are required when using AES-256 passwords in Windows machines.

Connecting using an SSL-secured connection

To connect to an SSL-secured JMX application, the plug-in needs to be configured with specific jproperties, so that it can successfully connect to the application. These jproperties are used to configure the type of connection that the plug-in needs to create. A detailed description of these properties and what they mean can be found on Sun's web site which defines how to create SSL connections e.g.

http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html

// Assumes the following variables have been defined (e.g. in a Type)
// groupProtocol = protocol
// serviceUrlSsl = service:jmx:rmi:///jndi/rmi://localhost:19763/jmxrmi

<sampler name="withssl">
    <var-group>
        <var ref="groupProtocol"></var>
    </var-group>
    <sampleInterval>
        <data>5</data>
    </sampleInterval>
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <var ref="serviceUrlSsl"></var>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=Runtime</data>
                    </value>
                    <showCommands>
                        <headlines>true</headlines>
                        <tableColumns>true</tableColumns>
                        <dataviews>true</dataviews>
                        <samplers>true</samplers>
                    </showCommands>
                </alias>
                <alias>
                    <name>$2</name>
                    <value>
                        <data>java.lang:type=Threading,*</data>
                    </value>
                    <showCommands>
                        <headlines>true</headlines>
                        <tableColumns>true</tableColumns>
                        <dataviews>true</dataviews>
                        <samplers>true</samplers>
                    </showCommands>
                </alias>
            </aliases>
            <rows>
                <columnLabels>
                    <label>
                        <data>ClassPath</data>
                    </label>
                    <label>
                        <data>LibraryPath</data>
                    </label>
                </columnLabels>
                <row>
                    <value>
                        <data>$1.ClassPath, $1.LibraryPath</data>
                    </value>
                </row>
            </rows>
            <jproperties>
                <jproperty>
                    <data>-Dcom.sun.management.jmxremote.ssl=true</data>
                </jproperty>
                <jproperty>
                    <data>-Dcom.sun.management.jmxremote.ssl.need.client.auth=true</data>
                </jproperty>
                <jproperty>
                    <data>-Djavax.net.ssl.keyStore=</data>
                    <var ref="sslDirectory"></var>
                    <data>\sslcertificates\jmxplugin\jmx.goodkeystore</data>
                </jproperty>
                <jproperty>
                    <data>-Djavax.net.ssl.keyStorePassword=plugpassword</data>
                </jproperty>
                <jproperty>
                    <data>-Djavax.net.ssl.trustStore=</data>
                    <var ref="sslDirectory"></var>
                    <data>\sslcertificates\jmxplugin\jmx.goodtruststore</data>
                </jproperty>
                <jproperty>
                    <data>-Djavax.net.ssl.trustStorePassword=plugtrustword</data>
                </jproperty>
            </jproperties>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Connecting using the JMXMP protocol

Up until now we have been using the JMXRMI protocol with which to connect to an application to monitor it. However, we are also allowed to connect using other protocols. For example, another common protocol is JMXMP. To connect to an application which exposes its state via a connector that uses the JMXMP protocol we need to make two changes in the manner in which we connect to it.

Firstly, we need to specify the new protocol in the serviceURL sampler parameter e.g.

<connection>
        <generic>
                <serviceURL>
                        <var ref="serviceUrlSsl"></var>
                </serviceURL>
        </generic>
</connection>

Secondly, as additional classes are needed to establish this type of connection, we need to get some additional files. These can be downloaded from Sun's website. You need to download the latest JMX Remote API Reference Implementation and extract rmissl.jar, jmxremote.jar and jmxremote_optional.jar. These files should then be stored in the same directory as the netprobe.

Supported Connection Settings

The following values can be configured in the Settings section for Generic samplers:

  • host - the ip address of resolved hostname of the machine on which the JMX application runs
  • port - the port on which to connect to the JMX application
  • urlpath - the urlpath to use when connecting to the JMX application
  • timeout - milliseconds to wait for connections to be established or JMX commands to return. This setting should not be used unless it is found that the sampler seems to be waiting for inordinate amounts of time to connect to an application which is clearly down. This allows a timeout which the user decides is appropriate, for which to wait for a connection, before deciding that the application should be considered down.
  • serviceUrl - combines the host, port and urlpath into a single URL. If this is used, then host, port and urlpath should not be used.
  • JAVA_HOME - allows the user to specify the path upto where the JRE resides. This only needs to be specified, if you have started your application as a local application. Must be used in conjunction with JMXID. See section How to configure plug-in to connect to a Java application for an example set-up for Windows.
  • JMXID - allows the user a way of identifying the local application to connect to. See section How to configure plug-in to connect to a Java application for an example set-up for Windows.

The official Sun Java documentation has the following to say about ServiceUrls:

A serviceUrl must conform to the following format:

The address is an Abstract Service URL for SLP, as defined in RFC 2609 and amended by RFC 3111.
It must look like this:

service:jmx:protocol:sap

Here, protocol is the transport protocol to be used to connect to the connector server. It is a
string of one or more ASCII characters, each of which is a letter, a digit, or one of the characters
+ or -. The first character must be a letter. Uppercase letters are converted into lowercase ones.

sap is the address at which the connector server is found. This address uses a subset of the syntax
defined by RFC 2609 for IP-based protocols. It is a subset because the user@host syntax is not
supported.

The other syntaxes defined by RFC 2609 are not currently supported by this class.

The supported syntax is:

//[host[:port]][url-path]

Square brackets [] indicate optional parts of the address. Not all protocols will recognize all
optional parts.

The host is a host name, an IPv4 numeric host address, or an IPv6 numeric address enclosed
in square brackets.

The port is a decimal port number. 0 means a default or anonymous port, depending on the protocol.

The host and port can be omitted. The port cannot be supplied without a host.

The url-path, if any, begins with a slash (/) or a semicolon (;) and continues to the end of the address.
It can contain attributes using the semicolon syntax specified in RFC 2609. Those attributes are not parsed
by this class and incorrect attribute syntax is not detected.

Although it is legal according to RFC 2609 to have a url-path that begins with a semicolon, not
all implementations of SLP allow it, so it is recommended to avoid that syntax.

Case is not significant in the initial service:jmx:protocol string or in the host part of the address.
Depending on the protocol, case can be significant in the url-path.

Note: Although the urlpath starts off with a leading slash, the plug-in will add a leading slash itself. So do not add the leading slash if specifying a urlpath as a connection setting.

Arithmetic Expression Support

The user can compose symbolic expressions using the managed bean attributes which are numbers. These symbolic expressions are converted into arithmetic expressions and then evaluated to yield a final value.

There is also support for appending a string to the end of the final calculated result to aid understanding of what is being viewed.

Note: As attributes are permitted to contain hyphens (e.g. $1.bytes-read) and these are used in arithmetic expressions (e.g. $1.bytes-read - 5) please ensure that there are spaces on either side of the minus symbol. If you do not put spaces on either side of the minus symbol, the plug-in assumes you are looking for a single attribute (e.g. $1.bytes-read-5) As this attribute is unlikely to exists, the dataview will display a message indicating that this attribute does not exist.

Displaying non-atomic attributes

The plugin can only display sensible values for attributes which are primitives or reference type java.lang.Long or which are non-primitive but have sensible display representations provided for them by the implementer of the managed bean to which they belong.

However, the plugin also has built-in support for displaying the value of attributes which are not part of the set described above but which occur so commonly that we have made special provisions for them.

The examples below assume that the user has configured an instance of the plugin to connect to a Java application listening for jmx requests on port 5003 and demonstrates how the plugin treats some attributes in a special way.

Note: This special treatment of non-standard attributes is currently only available for Java applications. It is not currently available for WebLogic and WebSphere.

Displaying attributes that are arrays

When the plugin is asked to display an attribute which is an array of objects, it creates a space-separated string of items, where each item in the string represents an item from the array. It is this space-separated string that is displayed as the final value of the attribute. The example below makes use of a managed bean with the name java.lang:type=Threading that has an attribute called AllThreadIds which is an array of longs. It also makes use of a managed bean with the name java.lang:type=GarbageCollector,name=MarkSweepCompact that has an attribute called MemoryPoolNames which is an array of strings.

So the example set-up below

<sampler name="2-9-1">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=Threading</data>
                    </value>
                </alias>
                <alias>
                    <name>$2</name>
                    <value>
                        <data>java.lang:type=GarbageCollector,name=MarkSweepCompact</data>
                    </value>
                </alias>
            </aliases>
            <rows>
                <columnLabels>
                    <label>
                        <data>AllThreadIds</data>
                    </label>
                    <label>
                        <data>MemoryPoolNames</data>
                    </label>
                </columnLabels>
                <row>
                    <value>
                        <data>$1.AllThreadIds,$2.MemoryPoolNames</data>
                    </value>
                </row>
            </rows>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

produces a example view that may look like this

jmx_server_image236

Displaying attributes of type CompositeData

It is not useful displaying an attribute of type CompositeData as by its nature it is composed of multiple items. So the plugin allows the user to specify a specific field in that attribute to display instead. The example below makes use of all the managed beans of type MemoryPool. Each of these managed beans contain an attribute of type CompositeData called PeakUsage. This attribute has field called committed of type long and another field called max also of type long.

The set-up below demonstrates how to retrieve and displays these fields.

<sampler name="2-9-2">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=MemoryPool,*</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>PeakUsage</label>
                    <rowTemplate>
                        <data>$1.PeakUsage.committed</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>MaxUsage</label>
                    <rowTemplate>
                        <data>$1.PeakUsage.max</data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

This produces a view that may look like this

jmx_server_image242

Displaying attributes that are Maps

Another non-atomic data type would be Maps, or data that are structured using a unique key returning a value. Just like in regular attribute paths, Map members can be accessed two ways: first, by using the [key='keyName'] expression, or by using the [match(key,'keyNameExp')] expression, the latter which can accept filters. So for example, to access the managed bean java.lang:type=GarbageCollector,name=MarkSweepCompact and the attribute committed under the key Code Cache which is stored in the Map memoryUsageAfterGc which in turn is under LastGcInfo, the setup below can be used.

<sampler name="2-9-2">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=GarbageCollector,name=MarkSweepCompact</data>
                    </value>
                </alias>
            </aliases>
            <columns>
                <column>
                    <label>Code Cache Committed</label>
                    <rowTemplate>
                        <data>$1.LastGcInfo.memoryUsageAfterGc[key=&apos;Code Cache&apos;].value.committed</data>
                    </rowTemplate>
                </column>
                <column>
                    <label>MaxUsage</label>
                    <rowTemplate>
                        <data>$1.PeakUsage.max</data>
                    </rowTemplate>
                </column>
            </columns>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

Using Format masks

Sometimes the retrieved value of an attribute is returned as a long but would really be more readable if it were formatted as a date. For example, in the managed bean with the name java.lang:type=Runtime there is an attribute called StartTime of type long. It represents the time when the Java virtual machine was started up as the number of milliseconds elapsed between the Epoch (00:00:00 GMT on January 1, 1970) and the point in time at which it was started. This is obviously not as intuitive as displaying the actual date at the virtual machine was started at.

The example below shows how to format this specific value as a date and ignore any other attributes being retrieved. It demonstrates how to do this for both headline values and table values.

Note: The format mask values can also be applied to mbean aliases representing multiple managed beans.

<sampler name="2-10">
    <plugin>
        <jmx-server>
            <connection>
                <generic>
                    <serviceURL>
                        <data>service:jmx:rmi:///jndi/rmi://192.168.10.200:5003/jmxrmi</data>
                    </serviceURL>
                </generic>
            </connection>
            <aliases>
                <alias>
                    <name>$1</name>
                    <value>
                        <data>java.lang:type=Runtime</data>
                    </value>
                </alias>
            </aliases>
            <headlines>
                <headline>
                    <name>StartTime</name>
                    <value>
                        <data>$1.StartTime</data>
                    </value>
                    <mask>
                        <data>DATE</data>
                    </mask>
                </headline>
                <headline>
                    <name>Uptime</name>
                    <value>
                        <data>$1.Uptime</data>
                    </value>
                    <mask>
                        <data>IGNORE</data>
                    </mask>
                </headline>
            </headlines>
            <rows>
                <columnLabels>
                    <label>
                        <data>StartTime</data>
                    </label>
                    <label>
                        <data>Uptime</data>
                    </label>
                </columnLabels>
                <columnMasks>
                    <mask>
                        <data>DATE</data>
                    </mask>
                    <mask>
                        <data>IGNORE</data>
                    </mask>
                </columnMasks>
                <row>
                    <value>
                        <data>$1.StartTime,$1.Uptime</data>
                    </value>
                </row>
            </rows>
            <idAttributes></idAttributes>
        </jmx-server>
    </plugin>
</sampler>

This produces a view that may look like this

jmx_server_image247

Built-in Format Masks

There are two types of Format Masks: Built-in Masks and Custom Masks. There are 5 built-in Masks included by default and can be readily be used. These are:

MaskDescription
DATEUsed to format data into Date formatting. Expected raw value in long type.
IGNOREDoes not perform any format masking and outputs the raw value as is. Since using Mask requires defining each row or column to have definition, rows which not require masking will need to use IGNORE.
Member

Masking for extracting attributes of String literals that has key-pair attributes via comma separated format. This mask supports the Coherence Member attribute. The expected string data example is as follows:

Member(Id=1, Timestamp=2012-09-19 16:45:32.985, Address=167.143.236.201:8088, MachineId=41557, Location=site:,machine:wdvra00a0016,process:27821, Role=CoherenceServer)

Usage:
Member(AttributeNameToDisplay)
Member(Id) - Outputs "1"
Member(Role) - Outputs "CoherenceServer"
Members

Format mask for handling array of Member format, this mask provides searching of set based on attribute key-value pair matching.

Expected data format:

Member(Id=1, Timestamp=2012-09-19 16:45:32.985, Address=167.143.236.201:8088, MachineId=41557, Location=site:,machine:wdvra00a0016,process:27821, Role=CoherenceServer)

Member(Id=2, Timestamp=2012-09-19 16:53:44.287, Address=167.143.236.201:8090, MachineId=41557, Location=site:,machine:wdvra00a0016,process:3258, Role=CoherenceConsole)

Usage:
Members(Key=ValueSearch,AttributeNameToDisplay)
Members(Id=2,Role)
This will output "CoherenceConsole", since the second set having the Id=2 pair.
Stats

Mask to handle the Stats String literal format. The Stats format can have multiple sets of items that is separated by a double carriage return. Stats expected format by Stats mask is based on WebSphere Stats, if stats format of other application server differs from WebSphere then a custom mask should be develop to support. If there are multiple or nested Stats present, a Stats Name can be specified to identify the target Stats object. If there are multiple or nested Stats present and the target Stats object is not specified, the first inner Stats object will be used

Usage:
Stats(Key=ValueSearch,AttribeNameToDisplay[,Stats Name])

Custom Format Masks

Extracted data can sometimes have a different format compared to data handled by built-in Member and Stats masks. It can be data from JMX known objects or data outputted by custom beans. In order to have greater flexibility in handling different kinds of data, the capability to create custom Format Masks is available. Client developers can create their own masking by implementing the ITRS JMX Java Mask interface.

Below is the Mask interface:

/**
 * Copyright 2012 ITRS Group Ltd
 */
package com.itrsgroup.jmx.masks;

public interface Mask {

        /**
         * Returns the masked, formatted, or extracted data based on
         * {@link java.lang.Object} data and array of {@link String} arguments.
         * Arguments will be passed as found in the Mask field.
         *
         * @param data - Raw data from JMX
         * @param args - Array of {@link String} based arguments
         * @return String
         * @throws MaskException
         */
        String get(Object data, String[] args) throws MaskException;

}
Implementing Mask

When format masking is required and custom masking is defined, the plugin will call the get(Object, String[]) method of the Mask implementation.

The method will receive an Object which can be in the form of String object. This object is the representation of the value based on the configured Row or Column value.

jmx_server_image259

The String[] of arguments will have the data inside the Mask parenthesis. If there are multiple arguments, it must be separated by using comma. Each comma delimited data will be passed as array item. For the example above, the args have a single item containing "Role" string on the first element.

The method get() must return String which will be the value of the dataview cell being masked.

As example, let us assume that the value will have this format:

"35,John,Engineer,Male"

We will be creating a mask for it, which requires to reference an index of the data from the comma delimited string literal. We expect that the first argument is the index of the data to be extracted.

package com.itrsgroup.jmx.masks;

public class CSV implements Mask
{
        public String get(Object data, String[] args) throws MaskException {

                int index = Integer.parseInt(args[0]);
                String csvData = (String) data;
                String[] splitData = csvData.split(",");
                return splitData[index];
        }
}

First, we need to implement the Mask interface, where we will be required to implement the get() method. In the implementation, we assume that the first index of the arguments is the required index of data to be extracted. On the succeeding lines we split the string literal into multiple strings using comma as separator. To make it easier we used the split function of the String object. Lastly, we return the string reference by the passed index argument.

jmx_server_image260

We directly used the CSV mask in the Mask field. The argument passed is "1". In the example above the CSV class name was used as the Mask name, and anything else that is in between the parenthesis will be considered as arguments. It is the responsibility of the developer of the Mask to identify the arguments and validate them.

jmx_server_image265

If the masking can fail then the method must throw a MaskException. The exception message will be used as the actual dataview cell data.
String[] splitData = csvData.split(",");
if(splitData.length < index)
{
        throw new MaskException("Invalid Index");
}
return splitData[index];

For example, if the index is beyond the actual size of the comma separated data, then it should throw a MaskException.

jmx_server_image266

By default, the package name of the Mask should be com.itrsgroup.jmx.masks, if in any case another package name is given, the complete name should be configured in the Mask field, as shown below

jmx_server_image267

Deploying Masks

All masks can be packaged as a separate Java Archive (jar), and must be deployed and copied on the same folder as the netprobe executable or the geneos-plugins.jar.

jmx_server_image268

The archive will be automatically loaded on restarting the Netprobe and will be ready for use.

Running JMX commands

By default the JMX plug-in exposes all management operations on mbeans in the form of right-click commands. These commands appear on samplers, dataviews, headline cells and dataview cells. The user can click a command to invoke the corresponding operation against the appropriate mbean. These right-click menus only appear on cells that reference a single mbean (as opposed to those cells which reference more than one mbean) For operations which need the user to supply values, a dialog appears when the command is selected, into which the user can add the appropriate arguments.

Note: This functionality is not available in the legacy gateway but only in Gateway2 onwards.

The view below shows an example of a right-click command being selected

jmx_server_image269

and the resulting dialog which appears allows users to add their own argument(s)

jmx_server_image274

The results or error messages (if any) are then displayed in ActiveConsole in the Output window.

jmx_server_image275

Sometimes you may not want commands to be generated. Or you may only want a subset of the available commands to be published. This can be achieved by toggling the showCommands option which is available where the aliases are defined. By default command generation occurs for all aliases. This option allows you to tailor command generation for just those aliases that you actully use.