Incubator/Metrics: Adding Packet Handler

From Globus

This document explains how to add a new packet handler to the usage statistics receiver.

1. Write a packet class that represents the component-specific usage information. The packet class should extend the org.globus.usage.packets.IPTimeMonitorPacket class and implement the packCustomFields() and unpackCustomFields() functions.

Example:

 public class FooPacket extends IPTimeMonitorPacket {
    
   public static final int COMPONENT = 100; // this value must be registered
   public static final int VERSION = 1;
    
   private int fooCount;
    
   public void setFooCount(int count) {
       this.fooCount = count;
   }
   
   public int getFooCount() {
       return this.fooCount;
   }
   
   public void packCustomFields(CustomByteBuffer buf) {
       super.packCustomFields(buf);
       buf.putInt(this.fooCount);
   }
    
   public void unpackCustomFields(CustomByteBuffer buf) {
       super.unpackCustomFields(buf);
       this.fooCount = buf.getInt();
   }
 }

Note: The packet component number must be first registered. See the page for a list of currently registered components. Update that page with your component number.

2. Write a packet handler class required by the usage statistics receiver. The packet handler class will instantiate the appropriate packet class and write the packet information to the database. The packet handler class should extend the org.globus.usage.receiver.handlers.DefaultPacketHandler class and implement the doCodesMatch(), instantiatePacket(), and makeSQLInsert() functions.

Example:

 public class FooPacketHandler extends DefaultPacketHandler {
  
   public FooPacketHandler(String db, String table)
       throws SQLException {
       super(db, table);
   }
   
   public boolean doCodesMatch(short componentCode, short versionCode) {
       return (componentCode == FooPacket.COMPONENT && 
               versionCode == FooPacket.VERSION);
   }
   
   public UsageMonitorPacket instantiatePacket(CustomByteBuffer rawBytes) {
       return new FooPacket();
   }
   
   protected PreparedStatement makeSQLInsert(UsageMonitorPacket pack) 
       throws SQLException {
       
       FooPacketHandler myPacket = (FooPacketHandler)pack;
       
       PreparedStatement ps = con.prepareStatement("INSERT INTO " + this.table + 
          " (component_code, version_code, send_time, ip_address, fooCount) VALUES (?, ?, ?, ?, ?)");
    
       // general info   
       ps.setShort(1, myPakcet.getComponentCode());
       ps.setShort(2, myPacket.getPacketVersion());
       ps.setTimestamp(3, new Timestamp(myPacket.getTimestamp()));
       if (myPacket.getHostIP() == null) {
           ps.setString(4, "unknown");
       } else {
           ps.setString(4, myPacket.getHostIP().toString());
       }
       
       // component-specific info
       ps.setInt(5, myPacket.getFooCount());
   }
 }

3. Define SQL schema for table that represents the packet information in a database. Add the new table definition to the usage/java/receiver/samples/etc/create_guss_tables_postgre.sql file. If you database is already in use make sure to update it with the new table.

Example:

 CREATE TABLE foo_packets (
   id SERIAL,
   component_code SMALLINT NOT NULL,
   version_code SMALLINT NOT NULL,
   send_time TIMESTAMP,
   ip_address VARCHAR(64) NOT NULL,
   fooCount INT,  
   PRIMARY KEY (id)
 );

4. Register your packet handler class with the usage statistics receiver. Modify the org.globus.usage.receiver.samples.ExampleReceiver class to instantiate your packet handler class and pass the appropriate database information.

Example:

 ...
 String fooTable = props.getProperty("foo-table");
 FooPacketHandler fooPacketHandler = new FooPacketHandler(databaseURL, fooTable);
 receiver.registerHandler(fooPacketHandler);
 ...

5. Update the configuration file with the new table name. Make sure to update the usage/java/receiver/source/etc/receiver.properties.sample sample file. If the usage receiver is already deployed make sure to update the $GLOBUS_LOCATION/etc/globus_usage_receiver/receiver.properties file.

Example:

 ...
 foo-table = foo_packets
 ...