The x.Link agent

The xLink agent is a C++ shared library (.DLL) that runs as part of the Java Virtual Machine (JVM) process. It communicates with the JVM using the Java Virtual Machine Programmer's Interface (JVMPI). The purpose of the agent is to instrument the byte code of relevant methods.

The x.Link agent has so far been built on Windows 32 and Solaris platforms.

Building on Win32 Platforms

There are two choices for building the xLink agent on Windows 32 platforms. Either use the Microsoft compilers or use the latest GNU Cygwin. Cygwin has a dependency on the Cygwin.dll. This is a large .dll containing much code unrelated to x.Link, it requires an additional component to install and is also released under the GPL license which can cause problems for commercial software. However the most recent 2.9.5 gcc (g++-2) can also statically link the required code. Note that 3.0+ version of gcc do not work.

You may need to edit makefile.w32 to set the following variables to reflect your envirnment:-

JAVAHOME=c:/usr/jdk1.3.1_02
GCC=g++-2

Then launch the build process

$ make -f makefile.w32
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 access.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 field.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 method.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 classfile.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 agent.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 attribute.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Ic:/java/j2sdk1.4.1_01/include -Ic
:/java/j2sdk1.4.1_01/include/win32 bytecode.cc
g++-2 -O2 -c -mno-cygwin -mwindows -DDEBUG=1 -Wall -Ic:/java/j2sdk1.4.1_01/inclu
de -Ic:/java/j2sdk1.4.1_01/include/win32 netclient.cc
netclient.cc: In function `bool currentDate(char *)':
netclient.cc:142: warning: unused variable `unsigned char b[13]'
netclient.cc:219: warning: control reaches end of non-void function `currentDate
(char *)'
g++-2 -mno-cygwin -mwindows -Wl,--add-stdcall-alias -shared -o xLink.dll timer.o
access.o field.o method.o classfile.o agent.o attribute.o bytecode.o netclient.
o -lws2_32
strip xLink.dll

Their are some warnings during the build. These need to be fixed.

Building on Solaris

x.Link has been built with the 2.9.5 GNU C++ compiler on Solaris 2.8. See the file makefile.sun for details.

x.Link is currently dynamically linked, you need libstdc++.so to run the agent. This should be changed to static linking in the future.

External Interfaces

The following external interfaces are defined by the agent:

JNIEXPORT jint JNICALL JVM_OnLoad(JavaVM *jvm, char *options, void *reserved)

This method is called at startup. The JVM should be invoked with the following flags:

-XrunxLink:server=10.179.129.148,port=4445

The server and port arguments are passed to JVM_OnLoad in the options argument. This method registers the JVMPI_EVENT_CLASS_LOAD_HOOK event and initialises the high precisions timers through a call to init_timer().

The following JNI method enables a Java routing to get a micro second precision timer.

JNIEXPORT jlong JNICALL Java_uk_co_kimble_xlink_Timer_getMicros(JNIEnv *, jclass)

When porting to another architecture the routine getMicros in timer.cc will need to be implemented.

Agent start-up

To test the agent edit the file run.sh and follow the instructions. You will also need to set the server and port where you are running your collector agent (see above).

Start the collector agent

$ ./run.sh

This will run a test program and send sample to the collector agent which you can view. Note the time values are currently not displayed correctly, this is a todo.

Class File Parsing

Performance Enhancements

Stop parsing after superclass/class is a non-match for filter

Stop parsing if there are no relevant methods

x.link wire protocol

The x.Link agent communicates with the Collector server using the User Datagram Protocol (UDP). This is a connectionless lightweight protocol ideally suited for transmitting small packets of data across a LAN. For the configuration part, a request/response protocol is implemented on-top of UDP to ensure reliable data transmission. It is possible for timing data to be lost if the collector server is not fast enough to keep up with all the agents, for example when x.Link is used to measure a clustered environment or if too many classes are monitored.

The protocol is used to decided which classes and methods to monitor, all configuration information being held with the centralised Collector server and it is used to return results to the collector

The Collector is built around the Jetty embedded http server. This provides an easy to use and familiar Web front end for viewing data. This has the advantage that x.Link can be installed on the other side of a firewall. System administrators frequently allow HTTP traffic through firewalls while blocking other ports. There are separate collector threads which gather data and store it in an internal database. The number of threads is user configurable.

As the protocol is well documented it would be possible to build an entirely new front end, perhaps using parts of the existing code. For example this could be Swing based or even written in another language such as Visual Basic.

All communication between agent and collector is through the CollectorThread class.

Configuration Protocol

The configuration protocol is used to decide which methods should be instrumented. It is used as each class is loaded. It has a high overhead so runs in its own thread. It uses UDP, this has a payload limit of 512 bytes. Currently fully qualified class or method names exceeding this length cannot be transmitted. Messages have the following format:

Request

lang=DE>C[C|S|M]name:

C: is followed by the fully qualified name of a class

S: is followed by the fully qualified name of a superclass

M: is followed by a method name and signature

The name is terminated by the colon ‘:’ character. The maximum length is 512 characters, so the name section is limited to 509 characters.

Response

[-|+]id

The response is a number representing the Primary Key of the requested name in the Collector database. This is preceeded by either a minus ‘-‘ indicating that the name is not on the filter list or a ‘+’ indicating that the name is on the filter list. The string is terminated by a null ‘\0’ character.

Note for classes the superclass may be on the filter list, so we tempoarily store a reference to the class in the Collector database even if it isn’t on the watch list. The agent will then send the name of the superclass, if this is not on the watch list the class is removed from the collector database.

Names

M:Class Name.Method Name:Time in uSecs:Timestamp in uSecs:

Note that Class Name and Method name will be compressed to the numberic ids returned by the configuration protocol in future releases.