---------------------------- KraftMonitor (version 1.10) Ted Francis. Dept of Computing Science University of Aberdeen Written: 17th July 1998 ---------------------------- ====== README ====== This file contains instructions for installing, compiling and running the *KraftMonitor visualisation tool* in conjunction with a Linda server and Prolog clients within the KRAFT architecture The Monitor traces communication taking place between KRAFT agents, and displays this information to the user in a graphical way. It is intended that this tool will be used as an aid to debugging existing KRAFT facilities, developing new ones, and demonstrating KRAFT in a more user-friendly manner. The introduction of the Monitor has required some additions to the Linda server code, and this is detailed below. CHANGES from release 1.00 ------------------------- This release differs from the previous in the following ways: -it allows monitoring of remote sites, via the Java-Linda gateway mechanism. The gateway code has been adapted to allow this, detailed below -the monitor can recognise 'register' performatives sent by other agents, this allows the agent to provide information about its role, resource type, etc, and this will affect the way it is graphically represented by the Monitor. -the monitor can read in 'batch' files of kraft_msg terms, and display them to the user as if they had been sent by actual agents. -It can also SAVE 'batch' files of the current activity being visualised. How the Monitor works --------------------- On starting up the Monitor connects to a Linda server, and "outs" a predicate of the form: monitor() This will instruct Linda to send duplicates of any kraft messages that subsequently pass through it. The Monitor, if required will also monitor remote sites, in conjunction with its local site. It achieves this by "outing" a predicate to its local Linda server of the form: remote_monitor(on, , ) The adapted Java gateway recognises this predicate, and routes it to the gateway at . The remote gateway, on receipt of this, then "outs" the 'local' monitor predicate to its Linda server: monitor() The (remote) linda server then makes duplicate messages for as before. The gateway routing mechanism can then deliver these messages back to the Monitor's site in the normal way. NB: For correct monitoring of remote sites, the monitor *must* know the name of its local site (as well as those of any remote sites it wishes to monitor). This is so that above can be of the form krl(, ) so that gateways can successfully route messages back to the Monitor. ------------------- Linda, on receiving a kraft message ("outed" from a client), and seeing the presence of any "monitor" predicates, will wrap a copy of the original message into a properly formed CCQL 'forward' message destined to , and "out" it to the 'blackboard', along with the original message. The original message will be picked up by its intended receiver in the normal way. The Monitor, like any other KRAFT facility, will be listening for messages to itself on Linda. On receiving one, it will extract the original message from the 'forward' it receives. It then displays this message graphically as an arrow passing between two red circles representing the sender and receiver of the message. More detail about the message can be found by clicking in the centre of the arrow, and it can also be seen in the text area below. As more messages are displayed, the user can step back and forth through the messages by using the Prev and Next buttons. The 'Mode' set determines whether the Monitor will not update its display until the user presses 'next' (Step by Step mode), or whether it will update automatically when a new message is sent to the Monitor (Continuous mode). The speed option affects the speed of automatic update. Advantages ---------- - This architecture means that agents' activity can be monitored without the agents knowing of the presence of the Monitor. So NO agent code need be adapted to be 'monitorable', only the Linda server is adapted. - Information destined for the Monitor can be delivered using the same mechanism as all information in KRAFT, using Linda servers and/or gateways, not via, e.g. another socket connection to each KRAFT agent. (also, although the number of messages passed through the system is increased, it is only a linear increase, not an exponential one). - As the Monitor deals with properly formed CCQL messages, there is room for expansion if more information needs to be communicated to it. The Monitor would be 'seen' as a normal KRAFT agent by other agents. e.g. the Monitor could 'advertise' its location to a facilitator, so that agents could locate a Monitor, 'register' with it providing some information about themselves. All these messages would be in the format already used within KRAFT. ------------------- Directory structure ------------------- kraft_linda-1.21 - **parent directory** | | |--monitor/ - this directory | |--classes/ - contains .class files for all Java code | (including Monitor/Linja/gateway) | |--src/ - contains .java source files for Monitor code | | |--docs/ - contains javadoc (HTML) documentation for all monitor code (plus a list of the classes/methods in the gateway code) (type netscape packages.html to view) The commands given below are assumed to be from the parent directory kraft_linda-1.21, unless stated otherwise. ============ Instructions ============ 1) Installing 2) Running 3) Compiling 4) Changes to existing software ------------- 1) Installing ------------- a) From **this** directory (monitor/). Type 'setenv CLASSPATH $cwd/classes' so the Java virtual machine knows where to find all the Java code. b) Set up the modified kraft-Linda library in the usual way: (1. change directory back to kraft_linda-1.21/) 2. Edit "Makefile.inc" to tailor for your system, by setting the correct paths for Prolog 3. Compile the components by: make For example: make sgi_sicstus or make sparc_quintus or make sparc_sicstus or make hp_sicstus 4. Set up the environment variable HOST or HOSTTYPE to match your machine. 5. Edit the file "prolog/machine_map.pl" to map your HOST or HOSTTYPE to the corresponding platform: host_map(,) ---------- 2) Running ---------- a) Start a Linda server in a window: cd prolog/linda prolog | ?- [linda_server]. | ?- linda. b) Note the port number chosen by the Linda server from the line: "Server address is 'ip_address:port'" c) In other windows, start some Prolog clients like this: cd prolog/messaging prolog | ?- [messaging]. | ?- init_messaging([server_host:, server_port:]). d) Start the Monitor by typing: java kraft.monitor.KraftMonitor e) From the Monitor's menu bar, choose the Monitor->Setup menu, and fill in the Monitor's name, Linda host and port. Click OK and the Monitor will be ready to visualise any messages in the kraft_msg format that pass through the Linda server. f) as a simple example with two prolog clients, client1 and client2: Client1: | ?- receive_message(client1, M). This will make client1 block, waiting to receive a kraft message Client2: | ?- compose_message(client2,client1,tell, [sender:client2, receiver:client1, content:some_content], M), send_message(M). This will make client2 send a simple message to client1. You should see that client1 does receive the message, AND the interaction has been visualised by the Monitor. g) For remote site monitoring ----------------------------- - start up a gateway for the linda_server as in previous versions: cd gateway java kraft.gateway.GatewayTest -c config_file -mn gateway_name -mp gateway_port -lh linda_host -lp linda_port (some example config files are in kraft_linda-1.21/gateway) - ensure gateways and Linda servers are started for any 'remote' sites you wish to monitor - From the Monitor-->Setup menu. Set the monitor's details as before, *including* the monitor's local site name, and the remote sites to be monitored (space or comma delimited). If clients now send messages to each other (remotely or locally), this will be visualised. ------------ 3) Compiling ------------ All the Java code comes pre-compiled, but to re-compile everything, type the following from the kraft_linda-1.21 directory: javac -d monitor/classes Linja/*.java gateway/*.java monitor/src/*.java monitor/src/adapter/*.java monitor/src/monitor/display/*.java monitor/src/monitor/tools/*.java NB: run this twice to ensure full compilation takes place ------------------------------- 4) Changes to existing software ------------------------------- The files that have been added/adjusted to incorporate the Monitor with Linda are shown below FILE DIRECTORY: linda_server.pl kraft_linda-1.21/prolog/linda/ messaging.pl kraft_linda-1.21/prolog/messaging/ message_format.pl kraft_linda-1.21/prolog/messaging/ transport.pl kraft_linda-1.21/prolog/messaging/ The Linda files have been modified as follows: linda_server.pl - takes into account the "monitor" predicate, - duplicates messages in kraft_msg format to the Monitor - uses 'message_format' module to produce properly- formed kraft_msg tuples when making these duplicates messaging.pl - This still provides the original Messaging API (user should not have to use the 2 modules below) - separated original file into three: 'messaging.pl', 'message_format.pl' and 'transport.pl'. - done so that linda_server module could make use of the 'message_format' module without having access to 'transport' message_format.pl - provides properly formed kraft_msg tuples to the above two modules transport.pl - provides transport mechanism for 'messaging' module The most significant changes to the Gateway code are in the file: kraft_linda-1.21/gateway/SocketGateway.java It has been modified to recognise the "remote_monitor" predicate, route it correctly, and "out" "monitor" predicates appropriately