X-Trace Tutorial 1 :: Application Instrumentation Walkthrough

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:

 
docs/tutorial-1.txt · Last modified: 2008/10/01 02:05 by andyk
 
Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki