Another piece of the tool puzzle.

One of the updates in Mustang b65 was the addition of the getAgentProperties method to the Attach API. This method gives tools access to a set of properties maintained in the Java virtual machine on behalf of agents. This may sound obscure but it gets interesting when you know that the JMX agent will create an agent property when it starts a local JMX connector server. A local JMX connector server is started when you start an application with -Dcom.sun.management.jmxremote or you start the management agent in a running application using the Attach API.

MemViewer.java is a simple "one page" example to demonstrate how a tool might use this method. MemViewer takes one argument to identify the target application and for this you use the process-id (or pid). MemViewer attempts to attach to the specified application and looks for the agent property named "com.sun.management.jmxremote.localConnectorAddress". If this property is set then it is the address of the local JMX connector server. If the property is not set then it means a local JMX agent is not running so MemViewer starts the management agent by loading a java agent named "management-agent.jar" into the target application. Once started, it re-obtains the agent properties to get the value of the agent property. Once MemViewer has the address of the connector server then it connects and prints information about each of the memory pools. Here is an example where MemViewer is used to print information about the memory used by a Java Web Start application.

C:\\> jps -l
2304 sun.tools.jps.Jps
2560 com.sun.javaws.Main

C:\\> java -classpath .;%JDK_HOME%\\lib\\tools.jar MemViewer 2560
                Pool         Used    Committed          Max
Perm Gen [shared-ro]      5279360      8388608      8388608
          Code Cache      4901696      4980736     33554432
          Eden Space       313968      1638400      4194304
Perm Gen [shared-rw]      7021848     12582912     12582912
         Tenured Gen     14466928     23662592     61997056
            Perm Gen     10631352     12582912     67108864
      Survivor Space       196608       196608       458752

If you examine MemViewer then you will see that the code is relatively simple. VirtualMachine.attach is used to attach to the target Java virtual machine. Once attached the getAgentProperties method is used to read the agent properties. If the management agent is not running then it constructs the name of the management agent and then uses the loadAgent method to load it into the target. The Attach API is a simple tool API for bootstraping agents into a running application and ships in the JDK in tools.jar. This means that tools.jar must be on the classpath when compiling or running. The JAR file "management-agent.jar" is the java agent with the Agent-Class attribute in the main manifest to specify the class name of the agent. The agent property com.sun.management.jmxremote.localConnectorAddress is set by the agent when the local JMX connector has started. This property will be documented along with the other properties on the Monitoring and Management with JMX page.

Finally, in the example output you will see that I used jps utility to get a list of the Java virtual machines that I was running. An alternative approach would have been to use the VirtualMachine.list method and prompt the user to select from a list.

Comments:

Happy new year, Alan! > The agent property com.sun.management.jmxremote.localConnectorAddress is set by the agent when the local JMX connector has started. I looked into the Agent source, it uses a private API to do so, sun.misc.VMSupport#getAgentProperties, right? I suppose other attach-on-demand agents face similar bootstrapping problems; is your intention that they bootstrap the management agent and then use JMX? Or would you consider planning a public #setAgentProperty? Right now, you've given us a rather powerful attach API but it's only really good for the management agent. In this case I would have preferred to include an API like so: VirtualMachine#startMBeanConnectorServer() VirtualMachine#getMBeanServerConnection() and a platform MBean that offers the "launch agent" capability. BTW: I noticed the mustang filenames have an "RC" in them now. Way to go! Best Matthias

Posted by Matthias on January 04, 2006 at 01:24 AM PST #

I'm sorry, I should really use preview.

Happy new year, Alan!

> The agent property com.sun.management.jmxremote.localConnectorAddress is set by the agent when the local JMX connector has started.

I looked into the Agent source, it uses a private API to do so, sun.misc.VMSupport#getAgentProperties, right? I suppose other attach-on-demand agents face the same bootstrapping problem; is your intention that they bootstrap the management agent and then use JMX? And if not, are you planning a public #setAgentProperty?

Right now, you've given us a rather powerful attach API but it's only really good for the management agent. In this case I would have preferred to include an API like so:

VirtualMachine#startMBeanConnectorServer()

VirtualMachine#getMBeanServerConnection()

and a platform MBean that offers the "launch agent" capability.

BTW: I noticed the mustang filenames have an "RC" in them now. Way to go!

Best
Matthias

Posted by Matthias on January 04, 2006 at 01:26 AM PST #

Hi Matthias. The loadAgent (or loadAgentLibrary) method can optionally pass an options string to the agent. This options string is passed to the agentmain method (or Agent_OnAttach function in the case of a native/JVMTI agent) and is typically be used to pass configuration and transport details to the agent. One obvious scenario is where the tool binds to a transport endpoint and then passes the address to the agent. For many cases (profilers, diagnostic utilities) this will work well and isn't too different to specifying an options string to the -agentlib or -javaagent options on the command line. There will however be cases where you want the agent to remain running after the tool disconnects or cases where the agent must choose a dynamic address without a way to communicate this to the front-end tool. For those cases an agent can include additional bootstraping code to communicate the existing configuration to the tool or it make it available to all tools as agent properties. As you've noted there isn't yet a public API to create these access properties - it has been talked about of course but it is probably something for after Mustang. For now only the JMX and JDWP agents that ship with the JDK create these properties. As regards a startJMXConnectorServer or similiar method - the Attach API can be used to start any java or native agent and it isn't tied the JMX agent.

Posted by alanb on January 04, 2006 at 02:44 AM PST #

Post a Comment:
Comments are closed for this entry.
About

user12820862

Search

Top Tags
Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today
News
Blogroll

No bookmarks in folder