JMX monitoring and management is built into Metro-based services
and clients. Monitoring allows one to view the state of parts of Metro
runtime system while it is in operation. Management allows one to
change values dynamically. The rest of this document will refer to
Metro monitoring and management as simply "monitoring".
Metro monitoring should not be confused with Metro's Web Service
Configuration Management (Metro CM). Monitoring enables one to view
the state of the Metro runtime, whereas Metro CM is for
(re)configuring a web service.
19.2. Enabling and Disabling Monitoring
Metro-based services have monitoring turned
on by default.
Metro-based clients have monitoring turned
off by default.
Clients are off by default because there is no standard way to
dispose of a client and release its resources. Metro does include a
proprietary method for disposing a proxy. Assuming you have an
AddNumbersPortType port = new AddNumbersService().getAddNumbersPort();
If you enable client monitoring it is recommended you
close client proxies when they are no longer used.
19.2.1. Enabling and disabling Metro monitoring via system
Metro has two system properties for controlling monitoring
scoped to the JVM:
The ManagedService assertion is placed inside
(or referenced from) the port element in the
endpoint's WSDL (if creating a service from WSDL) or in the
endpoint's configuration file (if creating a service from
This assertion is used by both Metro CM and monitoring. See
Metro CM for the meaning and operation of the
Metro monitoring is turned off for the specific endpoint if
the monitoring attribute is set to
false. If the policy assertion or the
monitoring attribute is not present, or the
monitoring attribute is set to true then
monitoring is turned on for that endpoint (unless endpoint
monitoring is turned off for the JVM).
19.2.3. Enabling and disabling client monitoring via policy
This is placed inside the
<service>/<port> element of the
*.xml file corresponding to the service referenced
from the src/java/META-INF/wsit-client.xml
configuration file. (Note: the example path to the
wsit-client.xml file is where the file is located
when building using NetBeans.)
When the monitoring attribute of
ManagedClient is set to true then
monitoring will be turned on for that specific client (unless the
client JVM property is set to false).
19.3. Monitoring Identifiers
19.3.1. Endpoint Monitoring Identifiers
220.127.116.11. Default Endpoint Monitoring Identifiers
Each endpoint is given a unique monitoring identifier
(also call "root name"). That identifier is made up of (in
The context path (if it is available).
The local part of the service name.
The local part of the port name.
For example, suppose one creates a web application with
a context path of /AddNumbersService and a Metro
web service is deployed under that context path with an
AddNumbersService service name and a
AddNumbersPort port name. Then the identifier
When deploying in GlassFish an INFO log
message is output to GlassFish's server.log file
when the monitoring root is created. In this example the
message would be:
Metro monitoring rootname successfully set to: amx:pp=/mon/server-mon[server],type=WSEndpoint,name=/AddNumbersService-AddNumbersService-AddNumbersPort
The name part is the identifier. The
amx:pp=... part reflects that this Metro endpoint
is federated under GlassFish's AMX tree. Note: when deploying
in non-GlassFish containers then Metro monitoring will be
under a top-level node: com.sun.metro.
Metro monitoring rootname successfully set to: amx:pp=/mon/server-mon[server],type=WSEndpoint,name=ExampleService
19.3.2. Client monitoring identifiers
18.104.22.168. Default Client Monitoring Identifiers
Each client stub is given a unique monitoring
identifier. That identifier is the endpoint address of the
service it will communicate with. For example, for a client of
the AddNumbersService above the identifier, as
shown in GlassFish's log, will be:
Metro monitoring rootname successfully set to: amx:pp=/mon/server-mon[server],type=WSClient,name=http-//localhost-8080/AddNumbersService/AddNumbersService
(Note that ':' characters have been replaced with '-'.
See below for more info.)
To give a user-assigned identifier use the
id attribute in the ManagedClient
19.3.3. Identifier Character Mapping
Some characters in a root name are converted to the '-'
character. This is to avoid the need to quote characters that are
not legal in JMX. The regular expression used to find and replace
those characters is:
19.3.4. Resolving Monitoring Root Name Conflicts
It is possible that two root names can be the same. This can
happen when deploying web services with the same service name and
port name under different context paths in non-GlassFish
containers because the context path is not available to the naming
mechanism when in other containers. This can also happen when two
different proxies are communicating with the same service.
When root names clash, then the rootname has
-<N> appended, where N is a unique
19.4. Available Monitoring Information
To show what monitoring information is available we will use two
This only exists on the endpoint side, scoped
Manages Reliable Messaging sequences.
This exists on both client and endpoints
sides, scoped per-stub and per-endpoint
In the screenshot there is
one client that is connected to the
two endpoints: a /s17... service and an
one WSNonceManager associated with the
two WSRMSCSessionManagers, one for each of
the two services
two WSRMSequenceManagers, one associated
with the client, the other with
Using Jmxterm you can find these same mbeans (note: the output
of beans show a lot of beans, this has been edited to
only show Metro's mbeans):
java -jar <Jmxterm-jar>
Welcome to JMX terminal. Type "help" for available commands.
#Connection to localhost:8686 is opened
#domain = amx:
19.4.1. WSClient Information
The following screenshot shows the top-level information
available for each client:
Figure 19.2. Monitoring - top-level information available for
Children: the WSRMSequenceManager that
is used by this client.
Container: the container in which the client is
deployed---in this case: GlassFish. Note that the actual
container object has not been instrumented with monitoring
so it Java class@address is printed.
Name: the root name given for this client.
Parent: show the WSClient under the AMX
qnameToPortInfoMap: an internal map used by the
serviceClass: The SEI (service endpoint
serviceName: From the WSDL.
wsdlDocumentLocation: Where the WSDL used to create
the client lives. (Note: when a service is created using
NetBeans it makes a local copy of the WSDL, therefore the
example shows a file instead of an
wsdlService: an internal data structure that is not
Children: in this example there are two other mbeans
associated with the example service.
addressingVersion: generally this will be
W3C unless explicitly using a different
version of addressing.
bindingID: the namespace for the type of binding
used for the service.
dumpHTTPMessages: when set to true then
HTTP messages received and sent by this service are
"dumped" into the log file. It is possible to dynamically
set this value. Just click on the value, type in the value
and hit return using JConsole. In jmxterm:
uniqueEndpointId: An identifier used by the reliable
messaging implementation. Note: this is
not related to client and endpoint
root name identifiers
The AMX mbean is created lazily. Therefore, if one deploys an
endpoint in GlassFish and then looks for the Metro
WSEndpoint mbeans using JConsole there are times where
the AMX mbean does not appear. To activate it start up the asadmin GUI
or CLI. Or use jmxterm and issue its domains
In some cases Metro endpoint mbeans will not appear until the
endpoint receives its first client invocation.
WSClient mbeans can appear and disappear quickly if
the stub is just used for one call then closed immediately. A stub
that uses reliable messaging or secure conversation generally stays
active longer since it will most likely be used for multiple