Table of Contents

1. Introduction
2. Setting up X-Trace
3. Compile and run Client and Server application
4. Instrument the communication protocol
5. Instrument the Client with X-Trace
6. Instrument the Server with X-Trace

Introduction

This tutorial is designed to walk you through the X-Trace instrumentation of a simple client-server java application, starting with the setup of the backend, and working through the insertion of real X-Trace report statements. These are just simple examples of how to do the instrumentation. For details on these calls and their parameters, please refer to the X-Trace Java API (javadoc).

Setting up X-Trace

1. Download and uncompress the X-trace distribution from http://sourceforge.net/projects/xtraceprj/
2. from inside the uncompressed directory, run bin/backend.sh
3. log into http://localhost:8080 to view the X-Trace backend web interface

Compile and run Client and Server application

1. change your current directory to docs/tutorials/tutorial1/, then run the following::

   javac -cp . chatapp/ChatMessage.java
   javac -cp . chatapp/Client.java
   javac -cp . chatapp/Server.java
   java -cp . chatapp.Server
   java -cp . chatapp.Client /* do this in a different terminal */
   

2. Try out sending messages using the client, you should see responses from the server

Instrument the communication protocol

1. Add the X-Trace metadata to the messages our application uses, uncomment the metadata class member which looks like this::

   byte[] xtraceMD;
   

Instrument the Client with X-Trace

1. Open docs/tutorials/tutorial1/Client.java, we will be adding (by uncommenting) 7 lines of code to this class...

2. At the beginning of the file, uncomment the following lines of code to import the X-Trace classes we'll use to instrument their Client class::

   import edu.berkeley.xtrace.XTraceContext;
   import edu.berkeley.xtrace.XTraceMetadata;
   

3. Setup the trace and first report generation by uncommenting the following line of code at the top of the main() function in the Client class::

   XTraceContext.startTrace("Client", "Run Tutorial 1" , "tutorial");
   

4. Uncomment the following two lines of code which are instrumentation points that will be triggered to send X-Trace reports with each message the client sends to the server::

   XTraceContext.logEvent("ChatClient", "SendUsersMessage", "Message", msgObjOut.message);
   msgObjOut.xtraceMD = XTraceContext.getThreadContext().pack();
   

5. Uncoment two more lines of code which are the instrumentation points that will send a report:

   XTraceContext.setThreadContext(XTraceMetadata.createFromBytes(msgObjIn.xtraceMD,0,16));
   XTraceContext.logEvent("ChatClient", "ReceivedServersMessage");
   

6. Compile Client.java, you will need to include the location of the x-trace

   javac -cp /tmp/xtrace/lib/xtrace-2.0.jar:. chatapp/Client.java
   

Instrument the Server with X-Trace

1. Open docs/tutorials/tutorial1/Server.java, we will be adding 4 lines of code to this class...

2. At the beginning of the file, uncomment the following lines of code to import the X-Trace classes we'll use to instrument thei Client class::

   import edu.berkeley.xtrace.XTraceContext;
   import edu.berkeley.xtrace.XTraceMetadata;
   

3. Uncomment the following two lines of code which are instrumentation points that will be triggered to send X-Trace reports with each message that is recieved from the client::

   XTraceContext.setThreadContext(XTraceMetadata.createFromBytes(msgObjIn.xtraceMD,0,16));
   XTraceContext.logEvent("ChatServer", "ReceivedClientsMessage");
   

4. Uncoment the two lines of code which are the instrumentation points that will send a report whenever the server replies to the client with a message::

   XTraceContext.logEvent("ChatServer", "SendingMessage", "Message", msgObjOut.message);
   msgObjOut.xtraceMD = XTraceContext.getThreadContext().pack();
   

5. Compile Server.java, you will need to include the location of the x-trace:

   javac -cp /tmp/xtrace/lib/xtrace-2.0.jar:. chatapp/server.java
   

Collect some traces!

1. Run the Server, from within docs/tutorials/tutorial1::

   java -cp /tmp/xtrace/lib/xtrace-2.0.jar:. chatapp.Server
   

2. Run the Client, from within docs/tutorials/tutorial1::

   java -cp /tmp/xtrace/lib/xtrace-2.0.jar:. chatapp.Client
   

3. Try it out, type come messages and see the Server's responses

View the X-Trace Graphs

1. Use a web browser to go to http://localhost:8080 and view the table of traces. The interface looks like this:
   
2. Click on the "Applet" link under the "Graphs" column of the table of traces to view a graph of your trace (make sure you have graphviz installed (http://www.graphviz.org/) for this to work). You should see a graph that looks similar to this: