E4JMS PlugIn Technical Reference

Introduction

The suite of E4JMS plugins is designed to monitor the JMS implementation by TIBCO. It is not suitable for monitoring the JMS implementations from other vendors.

To be able to establish a connection in EMS Server, the EMS user should have Administrator rights as required by the TIBCO EMS APIs.

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.

For Solaris Sparc 11.1 (branch: 0.175.1.0.0.24.2), there is a known issue with the ARCFOUR cipher that causes problems with any E4JMS plugin using SSL. It is recommended to install Patch 15879294: ORACLE SOLARIS 11.1 SRU 1.4. In case the fix cannot be installed, see the Solaris Sparc 11.1 ARCFOUR issue in Troubleshoot the Java configuration.

Views

The plugin produces a single view as follows:

E4JMS Bridges View

e4jms_image0

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalBridges The total number of bridges known to the server.

Table Legend

Name Description
source Get the type of the destination being bridged from
name Get the name of the destination being bridged from
queueTargets Get the destinations being bridged to which are of type Queue
topicTargets Get the destinations being bridged to which are of type Topic

E4JMS Connections View

e4jms_image1

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalConnections The total number of connections to the server
maxConnections The total number of connections available on this server. This number includes both the connections available for clients to connect on as well as those which are currently in use.

Table Legend

Name Description
connectionID Get the connection ID for this connection
username Get the username for this connection
starTime Get the creation time, in milliseconds, for this connection
upTime Get the time in seconds that this connection has been connected
type Get the connection type for this connection
clientID Get the clientID for this connection
sessionCount Get the number of sessions for this connection
consumerCount Get the number of consumers for this connection
producerCount Get the number of producers for this connection
clientVersion Get the version of the software being run by the client that created this connection
isAdmin Indicates whether or not the connection is a connection from an administration client, either tibjmsadmin or a client using this administration api
isXA Indicates whether or not the connection is an XA connection
isFT Indicates whether or not the connection is an FT connection, that is the connection has alternative URLs
isStarted Indicates whether or not the connection has been started by the client

E4JMS Durables View

e4jms_image2

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalDurables The total number of durables known to this server

Table Legend

Name Description
Name Get the name of this durable
topicName Get the topic name that this durable subscribes to
isActive Determine if this durable is connected or dormant
pendingMsgs Get the number of messages waiting to be delivered to this durable subscription
pendingMsgSize Get the total size, in bytes, of messages waiting to be delivered to this durable subscription
userName Get the name of the authenticated user whose connection this durable subscriber is currently using
clientID Get the client ID associated with this durable
consumerID Get the consumer ID associated with this durable
receiveOwnMsgs Indicates whether or not the durable has opted not to receive 'local' messages

E4JMS Non Durables View

e4jms_image12

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalNonDurables The total number of non-durable topic consumers/subscribers known to the server

Table Legend

Name Description
consumerID Get the consumer ID of a non-durable consumer
name Get the name of this non-durable consumer
destinationName The non-durable consumer's topic destination name
isConnected Determines if this non-durable consumer is connected to the server
pendingMsgs Get the number of pending messages for the non-durable topic consumer
pendingMsgSize Get the total combined size in bytes of pending messages for the non-durable topic consumer
userName Get the name of the authenticated user whose connection to this non-durable consumer is currently using
connectionID Get the connection ID associated with this non-durable consumer
receiveOwnMsgs Indicates whether or not the non-durable consumer has opted not to receive 'local' messages

E4JMS Queues View

e4jms_image3

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalQueues The total number of queues known to this server

Table Legend

Name Description
name The name of this queue
description The description of this queue
activeConsumers The number of consumers for this queue
queuedMsgs The total number of pending messages for this queue
percentFull The value for the amount of pending bytes consumed or allocated for this destination, e.g. currentPendingBytes divided by maxPendingBytes
bytesIncoming The value for the total size of messages in bytes
bytesOutgoing The value for the total size of messages in bytes
msgsIncoming The value for the total number of messages
msgsOutgoing The value for the total number of messages
currentPendingBytes The total size for all pending messages for this queue
maxPendingBytes The maximum number of message bytes that the server will store for pending messages bound for this destination
maxPendingMsgs The maximum number of messages that the server will store for pending messages bound for this destination.
isGlobal Determine if this destination is global
isImported Determine if this destination imports messages from other transports
isExclusive Determine if this queue is exclusive
isTemporary Determine if this destination is temporary
isDynamic Determine if this destination was created dynamically by a client application
receiverCount The value for the number of receivers of queue messages
unackedClientMsgCount The total number of unacknowledged messages that have been delivered to consumer applications
unackedRoutedMsgCount The total number of unacknowledged message that have been delivered to the queue owner
isRouteConnected Determine if the route for this queue is connected
maxRedelivery The maximum number of times the server will redeliver a message from this queue to its receivers
totalInboundBytes The value for the total size of inbound messages
totalOutboundBytes The value for the total size of outbound messages
totalIncomingMsgs The value for the total number of inbound messages
totalOutgoingMsgs The value for the total number of outbound messages
lastMessageReceivedOn The timestamp of the latest message in the queue. To enable this column, select 'Last message received on' on the columns option.
secondsSinceLastMessage The number of seconds since the last message was added to the queue. To enable this column, select 'Seconds since last message' on the columns option.

E4JMS Routes View

e4jms_image4

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalRoutes The total number of routes known to this server

Table Legend

Name Description
route Get the name of the remote server in this route
type Indicates whether or not the route is connected
URL Get the URL of the remote server in this route
stalled Indicates whether or not the route has stalled destinations.

E4JMS Server View

e4jms_image5

Table Legend

Name Description
asynchStorage Get the current size of the asynchronous message store
connections Get the number of connections to the server
durables Get the number of durable subscribers in the server.
inboundBytesRate Get the volume of inbound messages per second for the server as a whole
maxMsgMemSize Get the maximum allowed message memory
outboundBytesRate Get the volume of outbound messages per second for the server as a whole
inboundMsgRate The number of inbound messages per second for the server as a whole
outboundMsgRate The number of outbound messages per second for the server as a whole
pendingMsg Get the total number of pending messages for this server
pendingMsgSize Get the total size of pending messages for this server
percentUsedMsgMem usedMsgMemSize / maxMsgMemSize * 100
queues Get the number of queues in the server
server Get the name of the server
state Get the current state of the server
synchStorage Get the current size of the synchronous message store
topics Get the number of topics in the server
uptime The number of seconds that the server has been running
usedMsgMemSize Get the amount of memory in use to store messages
version Get the version of the server

E4JMS Topics View

e4jms_image6

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalTopics The total number of topics known to the server

Table Legend

Name Description
name The name of this destination
description The description of this destination
activeConsumers The number of consumers for this destination
activeDurables The current number of active durable subscribers for this topic.
numDurables The current number of durable subscribers for this topic
queuedMsgs The total number of pending messages for this destination
percentFull The value for the amount of pending bytes consumed or allocated for this destination, e.g. currentPendingBytes divided by maxPendingBytes
bytesIncoming The value for the total size of messages
bytesOutgoing The value for the total size of messages
msgsIncoming The value for the total number of messages
msgsOutgoing The value for the total number of messages
currentPendingBytes The total size for all pending messages for this destination
maxPendingBytes The maximum number of message bytes that the server will store for pending messages bound for this destination
maxPendingMsgs The maximum number of messages that the server will store for pending messages bound for this destination.
isGlobal Determine if this destination is global
isExported Determine if the topic is exported to Tibrv
isImported Determine if this destination imports messages from other transports
isTemporary Determine if this destination is temporary
isDynamic Determine if this destination was created dynamically by a client application
subscribers The current number of subscribers for this topic
totalInboundBytes The value for the total size of inbound messages
totalOutboundBytes The value for the total size of outbound messages
totalIncomingMsgs The value for the total number of inbound messages
totalOutgoingMsgs The value for the total number of outbound messages

E4JMS User Summary View

e4jms_image7

Headline Legend

Name Description
emsUrl Shows which hostname is currently running on the dataview.
totalUserSummary The total number of users.

Table Legend

Name Description
user The name of specific user on the server.
connections The number of connections opened by the user.

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

There are two ways to configure the plugin.

The first approach is suitable for monitoring a single server.

The second approach is suitable for monitoring a primary server and switching over to a backup server when the primary server goes down (without requiring re-configuration by the system administrator)

The following parameters can be configured for this plugin for the first approach:

singleHost > host

The name or IP address of the machine on which the E4JMS server is to be run.

Mandatory: Yes

singleHost > port

The port number of the E4JMS server that the plugin should attempt to connect to

Mandatory: Yes

singleHost > username

The user name for the plugin to use when establishing a connection to the E4JMS server

Mandatory: Yes

singleHost > password

The password for the plugin to use when establishing a connection to the E4JMS server.

As this is a mandatory field, if you need to connect to a server which is not protected by a password, you can enter blank text, which will ensure that no password is used when trying to connect to the EMS server.

Choose the appropriate field when specifying the password:

  • stdAES — use this to input your plaintext password. If you select stdAES, you can define your password directly in the sampler and store it in standard AES encryption hash in the Gateway.
  • var — use this to pass the password as a variable. The variable is defined in Managed entity > Advanced > Var. This is useful for situations where you have multiple samplers that use the same credentials.
  • extPwd — use this for passwords provided by an external provider. For more information, see Secure Passwords in Secure Passwords.

Mandatory: Yes

singleHost > protocol

The protocol for the plugin to use when establishing a connection to the E4JMS Server.

Mandatory: Yes

singleHost > protocol > ssl > trusted certificates

File name of CA certificates to trust as issuers of server certificates.

Mandatory: Yes

singleHost > protocol > ssl > expected hostname

The host name the client expect in the Common Name (CN) field of the server certificate. If this field is set, ssl_verify_hostname is enabled.

Mandatory: No

singleHost > protocol > ssl > cipher suites

Define the cipher suites that the client can use. This contains a colon separated string that follows the syntax stated in the Tibco EMS user guide.

Mandatory: No

The following parameters can be configured for this plugin for the second approach:

primaryServer > host

The name or IP address of the machine on which the primary E4JMS server is to be run.

Mandatory: Yes

primaryServer > port

The port number of the primary E4JMS server that the plugin should attempt to connect to

Mandatory: Yes

primaryServer > username

The user name for the plugin to use when establishing a connection to the primary E4JMS server

Mandatory: Yes

primaryServer > password

The password for the plugin to use when establishing a connection to the E4JMS server.

As this is a mandatory field, if you need to connect to a server which is not protected by a password, you can enter blank text, which will ensure that no password is used when trying to connect to the EMS server.

Choose the appropriate field when specifying the password:

  • stdAES — use this to input your plaintext password. If you select stdAES, you can define your password directly in the sampler and store it in standard AES encryption hash in the Gateway.
  • var — use this to pass the password as a variable. The variable is defined in Managed entity > Advanced > Var. This is useful for situations where you have multiple samplers that use the same credentials.
  • extPwd — use this for passwords provided by an external provider. For more information, see Secure Passwords in Secure Passwords.

Mandatory: Yes

primaryServer > protocol

The protocol for the plugin to use when establishing a connection to the E4JMS Server.

Mandatory: Yes

primaryServer > protocol > ssl > trusted certificates

File name of CA certificates to trust as issuers of server certificates.

Mandatory: Yes

primaryServer > protocol > ssl > expected hostname

The hostname the client expect in the Common Name (CN) field of the server certificate. If this field is set, ssl_verify_hostname is enabled.

Mandatory: No

primaryServer > protocol > ssl > cipher suites

Define the cipher suites that the client can use. This contains a colon separated string that follows the syntax stated in the Tibco EMS user guide.

Mandatory: No

backupServers > backupServer > host

The name or IP address of the machine on which a non-primary E4JMS server is to be run.

Mandatory: Yes

backupServers > backupServer > port

The port number of a non-primary E4JMS server that the plugin should attempt to connect to

Mandatory: Yes

backupServers > backupServer > username

The user name for the plugin to use when establishing a connection to a non-primary E4JMS server

Mandatory: Yes

backupServers > backupServer > password

The password for the plugin to use when establishing a connection to the E4JMS server.

As this is a mandatory field, if you need to connect to a server which is not protected by a password, you can enter blank text, which will ensure that no password is used when trying to connect to the EMS server.

Choose the appropriate field when specifying the password:

  • stdAES — use this to input your plaintext password. If you select stdAES, you can define your password directly in the sampler and store it in standard AES encryption hash in the Gateway.
  • var — use this to pass the password as a variable. The variable is defined in Managed entity > Advanced > Var. This is useful for situations where you have multiple samplers that use the same credentials.
  • extPwd — use this for passwords provided by an external provider. For more information, see Secure Passwords in Secure Passwords.

Mandatory: Yes

backupServers > protocol

The protocol for the plugin to use when establishing a connection to the E4JMS Server.

Mandatory: Yes

backupServers > protocol > ssl > trusted certificates

File name of CA certificates to trust as issuers of server certificates.

Mandatory: Yes

backupServers > protocol > ssl > expected hostname

The hostname the client expect in the Common Name (CN) field of the server certificate. If this field is set, ssl_verify_hostname is enabled.

Mandatory: No

backupServers > protocol > ssl > cipher suites

Define the cipher suites that the client can use. This contains a colon separated string that follows the syntax stated in the Tibco EMS user guide.

Mandatory: No

columns > column

An option which presents users with a drop-down list of column names, which when selected will be diplayed in the View. Users can select one or more columns from the drop-down list. When this option is used, the first column in the View is not customizable. The following will always be the first column of the View when this option is used:

  • name - for E4JMS Bridge, Durable, Queue and Topic
  • connectionID - for E4JMS Connection
  • route - for E4JMS Route
  • consumerID - for E4JMS Non Durables

Note: This option is not available for E4JMS Server and User Summary

Mandatory: No

javaproperties > property

An option to pass to the JVM that gets created by the net probe e.g. -Xmx128M would require the JVM to ensure its size does not exceed 128 MB in size.

Mandatory: No

regexFilters > regexFilter

You can apply the regular expression or regex filter to the Bridge, Durable, Non-Durable, Queue, Route, Topic, and User Summary views. If this configuration is defined, then any row whose first column does not match the regex filter is excluded from the view.

The regex filters should follow the Java regex specifications described in the API documentation for java.util.Pattern.

e4jms_image8

Mandatory: No

timeout

The amount of time (in seconds), that the system will try to connect to the EMS server, it will stop reconnecting when the timeout period has elapsed. The default timeout value is 5 seconds.

Deployment

Additional Files

The plugin requires the following additional files:

  • ITRS provided files:
    • geneos-plugins.jar
  • TIBCO E4JMS provided files:
    • jms.jar
    • tibjms.jar
    • tibjmsadmin.jar
    • tibcrypt.jar *
    • slf4j-api-1.4.2.jar *
    • slf4j-simple-1.4.2.jar *
  • Java Runtime Environment (JRE) provided files:
    • jsse.jar *

*Required for SSL connections only

For guidance on where these files should be placed, see Configure the Java environment in Configure the Java environment.

Diagnostics - configuration

Prerequisites:

Make sure your directory only contains these files and that they are named exactly as given below:

  • geneos-plugins.jar
  • jms.jar
  • tibjms.jar
  • tibjmsadmin.jar

If using SSL connections, the following are also required:

  • tibcrypt.jar
  • slf4j-api-1.4.2.jar
  • slf4j-simple-1.4.2.jar
  • jsse.jar

Command:

This must be specified on a single line.

For TCP connections:

C:\> java -jar geneos-plugins.jar ems
               <tcp://hostname:portnumber><username><"none" | password>For example,

C:\> java -jar geneos-plugins.jar ems
               tcp://localhost:7222
               admin
               none

For SSL connections:

C:\> java -jar geneos-plugins.jar ems
               <ssl://hostname:portnumber> <username><"none" | password><trustedCertificates><"none" | expectedHostname><"none" | cipherSuites>For example,

C:\> java -jar geneos-plugins.jar ems
               ssl://localhost:7234
               admin
               none
                   server_root.cert.pem
                   none
                   +ALL

Expected Output

Successfully connected to EMS-SERVER