AgentSpotter

From Agent Factory

Jump to: navigation, search

Contents

Introduction

AgentSpotter is a MAS performance analysis system, based on the mapping of conventional profiling concepts to agent-oriented concepts. AgentSpotter's platform-independent architecture is composed of a MAS run-time profiling data collection infrastructure and a suite of interactive visualisation tools (Flat Profile, Call Graph Tree View, and Space Time Diagram) that use the collected data to provide new insights into a MAS run-time performance.

Downloading AgentSpotter for Agent Factory 2.0

The latest distribution of AgentSpotter can be downloaded from here. This distribution works with the latest version of Agent Factory (v2.0).

NOTE as of 21/02/2010: an new release of Agent Factory is required to allow it to work with AgentSpotter, the current v2.0 found on sourceforge will *NOT* work with AgentSpotter. Please use the provided JAR files until an "official" release is published.

Installing

Decompress the full distribution ZIP in a directory of your choice. Note that AgentSpotter can run on Windows and Linux.

This distribution contains the following folders:

  • agentfactory: AF 2.0 libraries specially adapted for AgentSpotter.
  • agentspotterstation: AgentSpotter desktop application with interactive visualisations
  • profiler: libraries to use for profiling a running MAS
  • sample-profiles: sample profiles generated for my thesis

Profiling a MAS

Temporary Agent Factory library

Ensure that the JAR files provided in the "profiler" directory are properly referenced in your MAS AF project. You will need:

  • AgentSpotterFile.jar
  • AgentSpotterProfiler.jar
  • antlr-2.7.7.jar
  • sqlitejdbc-v053.jar
  • stringtemplate.jar
  • sigar/sigar.jar
  • sigar/*.*: Please ensure that the required *.so and *.dll files were properly decompressed in the "sigar" directory.

Profiler library

Until the AgentFactory distribution is officially updated to work with AgentSpotter, use the provided JAR files in the "agentfactory" directory instead of the regular Agent Factory Library i.e. remove the existing "AF-Library" reference in Eclipse or NetBeans and reference the following JAR files instead:

  • AF-AFAPL2-agentspotter.jar
  • AF-Ant-agentspotter.jar
  • AF-RMA-agentspotter.jar
  • AF-RTE-agentspotter.jar
  • AF-Support-agentspotter.jar

Code to add to main()

To profile a MAS add the following code to your Main class:

import com.agentfactory.agentspotter.AgentSpotter;
...
   DefaultAgentPlatform platform = new DefaultAgentPlatform();
...
   AgentSpotter profiler = new AgentSpotter(platform);
   // Set auto commit to force a database flush after every write (slower but safer)
   // profiler.setAutoCommit(true);
   profiler.start();
...

If you find out that "profile.aspot" is not correctly closed, try "setAutoCommit(true)" as shown in the comment.

Code to add to the main Swing JFrame

If your application uses a main Swing JFrame, do not forget to add the following statement to your in your frame init code:

   setDefaultCloseOperation(javax.swing.WindowConstants.EXIT_ON_CLOSE);

This will ensure that the database is properly closed when you close the main frame.

Resulting snapshot file: "profile.aspot"

After each run (a profiling "session"), a snapshot file called "profile.aspot" located in the root directory of the project will be updated (it is automatically created if it does not exist). This file stores all the profiling sessions for a given project.

Visualising Profiler Snapshots with the AgentSpotter Station

Starting the application

To be able to visualise the sessions store in the "profile.aspot" file, you have to run the AgentSpotter Station desktop application.

  • To start the application locate in the "agentspotterstation/bin" folder the "agenspotterstation.exe" executable (or the "agentspotterstation" shell script if you are running under linux) and run it.
  • When you run the application for the first time, some windows may not be visible. To make the most important windows visible go to the "Window" menu and select the "Bird's Eye Window" and "Snapshot Window" items. You can move and dock the windows around to organise the layout in a way that suits you.

Snapshot window

  • To work on a a profiling snapshot, locate the "AgentSpotter Snapshot" root item in the "Snapshot Windows", then right click on it to make the contextual menu appear, then select "Add Snapshot File..." to browse to an existing "profile.aspot" and include it in the list. If you close the program and come back later the link to the snapshot file will be preserved and displayed again in the "Snapshot Window".
  • You can also organise snapshot into folders by selecting the "Add Folder..." contextual menu item.
  • Once a snapshot is listed, you can click on the "+" sign to get a list of all the recorded sessions.
  • Double-clicking on a session will open the Space-Time diagram for the selected session.
  • Right-clicking on a session will open a contextual menu with the following choices:
    • View Summary: display the flat profile for the session.
    • View Space-Time Diagram: display the complete session performance analysis diagram.
    • View Call Graph: display a hierarchical profile.
    • Delete: delete the session from the snapshot.

Space-Time Diagram

A detailed discussion about the diagram can be found here. The main input control to navigate around is the mouse:

  • Point on something to get more details.
  • Left double-click on something to zoom on it.
  • Right double-click on something to unzoom from it.
  • Keep the left button depressed and move the mouse around to pan.
  • Keep the right button depressed and move the mouse around to zoom in and out.

Call Graph

A detailed discussion about the diagram can be found here. Note that the call graph generation can be very CPU intensive. It can take up to 5 minutes to run for a very long session. The diagram can be controlled with mouse the same way than the space time diagram. The search box in the bottom right corner can be very handy to highlight interesting data.

Note that there is a "Save Call Graph" menu item in "File" that allows you to save the current view as a PNG file.

Sample profiles

Some sample profiles are included in the "sample-profiles" folder of the distribution to allow you to review the features of AgentSpotter. The most interesting profiles are:

  • AF-Benchmark-Evaluation.aspot: 18 minute long session named "Fri, 3 Oct 2008...".
  • Agent-Herders-Evaluation.aspot: single 4 mn 40 run.
  • Agent-Sherpa-Evaluation.aspot: first run with 12 agents, second run with 2 agents only.
  • generated-on-linux.aspot: demonstrates that the CPU monitoring also works on Linux.

Publications

AgentSpotter is the product of this MSc. thesis. The following articles give a detailed explanation of the ideas behind AgentSpotter and show how the diagrams can be used and interpreted: