JMX

Introduction Copied

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 Copied

• You must have Java installed on the machine running the Netprobe. For information on supported Java versions, see Java support in Geneos Compatibility Matrix.
• Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see Configure the Java environment.

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 Copied

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.

Plug-In Configuration Copied

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)

You can safely update most of the configuration options on this plug-in without causing the Netprobe to restart. The exception is the jproperties option. If you update this option, then the Netprobe restarts.

If you are using this plugin with Gateway Hub, you must create a user defined data schema. For instructions, see Create a data schema.

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

connection Copied

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

Possible values:

Mandatory: Yes

connection > generic Copied

Specifies connection settings to a Java application.

connection > generic > serviceURL Copied

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 Copied

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

connection > generic > connectionDetails > host Copied

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 Copied

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

connection > generic > connectionDetails > urlPath Copied

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 Copied

This is the local Java application’s process ID.

connection > generic > username Copied

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

connection > generic > password Copied

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 Copied

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 Copied

Specifies connection settings to a WebSphere server.

connection > websphere > host Copied

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

connection > websphere > port Copied

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

connection > websphere > username Copied

Specifies the username to use when connecting to the server.

connection > websphere > password Copied

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 Copied

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

connection > websphere > sslKeyStoreDetails > sslClientKeyStore Copied

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 Copied

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 Copied

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 Copied

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 Copied

Specifies connection settings to a WebLogic server.

connection > weblogic > java.naming.provider.url Copied

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 Copied

Specifies the principal to use when connecting to the server.

connection > weblogic > java.naming.security.credentials Copied

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 Copied

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

connection > weblogic > sslClientCertificateKeyFile Copied

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

connection > weblogic > sslClientKeyPassword Copied

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 Copied

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

Possible values:

Mandatory: No

Default: Runtime MBean Server

aliases Copied

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 Copied

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 Copied

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

$1

Mandatory: Yes

aliases > alias > value Copied

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

java.lang:type=GarbageCollector,*

Mandatory: Yes

aliases > alias > attributePath Copied

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 Copied

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 Copied

Enable summary mode.

Mandatory: Yes

aliases > alias > summary > grouping Copied

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 Copied

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 Copied

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

Mandatory: No

headlines > headline Copied

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

Mandatory: No

headlines > headline > name Copied

The label to display for a particular headline

Mandatory: No

headlines > headline > value Copied

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 Copied

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

Mandatory: No

rows Copied

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

Mandatory: Yes

rows > columnLabels Copied

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

Mandatory: Yes

rows > columnMasks Copied

Describes the masks to use to format each row value with

Mandatory: Yes

rows > row Copied

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 Copied

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 Copied

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 Copied

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

Mandatory: Yes

columns > column > rowTemplate Copied

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 Copied

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

Mandatory: Yes

jproperties Copied

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

Caution: Java flags that are configured on this setting are inherited by all Java-based samplers running on the same Netprobe. For a full list of Java-based plugins, see Overview in Configure the Java environment.

For example, consider the following scenario:

1. Netprobe A is running the JMX and REST API samplers.
2. The JMX sampler uses the jproperties setting to enable TSL.
3. A REST API sampler on Netprobe A inherits the values configured in the jproperties setting. It is possible that the REST API sampler may encounter errors if the jproperties flags require data that is not present in the REST API sampler. To address this the JMX and REST API samplers must be run on separate Netprobes. Mandatory: No

jproperties > jproperty Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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.

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.

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:

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:

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

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

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:

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

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).

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 Copied

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 Copied

Attribute Names Copied

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 Copied

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 Copied

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 Copied

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 the Compatibility Matrix.

Required Software Copied

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.

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 Copied

• You must have Java installed on the machine running the Netprobe. For information on supported Java versions, see Java support in Geneos Compatibility Matrix.
• Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see Configure the Java environment.

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 Copied

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 Copied

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 Copied

Required Software Copied

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.

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.

• You must have Java installed on the machine running the Netprobe. For information on supported Java versions, see Java support in Geneos Compatibility Matrix.
• Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see Configure the Java environment.

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 Copied

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 Copied

The following connection settings need to be added:

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 Copied

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 Copied

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.

   java -jar wljarbuilder.jar
   

4. Rename the created wlfullclient.jar to weblogic.jar

5. Copy the following files from bea\wlserver\server\lib to your Netprobe folder.

   For Weblogic 10.3.6:

   weblogic.jar
   cryptoj.jar
   EccpressoCore.jar
   

   For Weblogic 12.1.1:

   weblogic.jar
   cryptoj.jar
   

6. Create a lib folder in your Netprobe directory.

7. Copy DemoTrust.jks from bea\wlserver\server\lib to netprobe\lib folder.

8. Define the following environment variables in your Netprobe startup script.

   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
   

9. In Gateway Setup Editor, kindly add the following java arguments in JMX plug-in Advanced > Jproperties.

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

10. Run the Netprobe using start_netprobe script.

Connect to a WebSphere 8.5.5.x server Copied

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 Copied

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.

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

Note

If you do not rename

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

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

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

<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>

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

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

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

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

"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

/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

/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

<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>

<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>

<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>

monitorRole     readonly
controlRole     readwrite

monitorRole     readonly
controlRole     readwrite
kyoto           readwrite

kyoto           origami

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

<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>

// 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>

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

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.

<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>

<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>

<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>

<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>

/** * 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;

}

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];        }
}

String[] splitData = csvData.split(",");
if(splitData.length < index)
{        throw new MaskException("Invalid Index");
}
return splitData[index];