Formats - adjacentlink/opentestpoint GitHub Wiki

Probe Message Name Format

OpenTestPoint probe name format consists of a tree like naming convention where each element in the name tree is separated by a '.'. The more elements in a probe name, the more specific the probe name. This naming convention follows the ZeroMQ PUB/SUB subscription filter model. Client subscriptions are compared to published messages and those subscription names that match the published message name from the start of the published name through the length of the subscription name are delivered.

For example, a probe named A.B.C.D may belong to a family of probes consisting of A.B.C.D, A.B.C.E and A.B.C.F. Subscribing to a probe named A.B.C.D will only match that single probe. Specifying A.B.C will match A.B.C.D, A.B.C.E and A.B.C.F. Likewise, specifying just A will match all probes that start with A.

Probe Measurement Data Wire Format

Probe measurement data are sent using a ZeroMQ PUB socket as a multi-part message containing two parts. The first part of the message is the probe name in [Probe Message Name Format](#Probe Message Name Format). The second part of the message is a ProbeReport message defined using the Google Protocol Buffer specification shown below:

package OpenTestPoint;

option optimize_for = SPEED;
    
message ProbeReport
{
  enum MessageType
  {
    TYPE_DATA = 1;
    TYPE_ERROR = 2;
  }

  message Data
  {
    required string name = 1;
    required string module = 2;
    required uint32 version = 3;
    required bytes blob = 4;
  }

  message Error
  {
    required string description = 1;
  }
  
  required uint32 index = 1;
  required string tag = 2;
  required bytes uuid = 3;
  required uint64 timestamp = 4;
  required MessageType type = 5;

  optional Data data = 6;
  optional Error error = 7;
}

ProbeReport messages are subdivided into one of two types: DATA and ERROR. Every ProbeReport message contains the following fields:

Field	Description
index	The index of the probe. Each probe instantiated by the same Controller is assigned a unique sequential index.
tag	The tag assigned to the Controller owning the reporting probe instance. The tag is assigned via XML and usually the node hostname.
uuid	The UUID of the Controller owning the reporting probe instance.
timestamp	The timestamp of the report. By default all probes report every 5 seconds on second boundaries evenly divisible by 5.
type	The message type used to identify whether the probe report contains data or an error message.

ProbeReport messages with type set to TYPE_DATA will have a Data message present in the report data member. The Data message has the following fields:

Field	Description
name	The name of the Google Protocol Buffer message for the measurement
module	The Python module containing the Google Protocol Buffer message class and specialized formatters.
version	The version of the message.
blob	The serialized Google Protocol Buffer message.

ProbeReport messages with type set to TYPE_ERROR will have an Error message present in the report error member. The Error message has the following field:

Field	Description
description	The description of the error.

Example Application

The below Python script subscribes to receive EMANE.VirtualTransport.Counters.General probe messages and prints the received message information.

import zmq
import uuid
import otestpoint.interface.probereport_pb2 as probereport_pb2

context = zmq.Context()

subscriber = context.socket(zmq.SUB)

subscriber.connect('tcp://localhost:9002')

subscriber.setsockopt(zmq.SUBSCRIBE,'EMANE.VirtualTransport.Counters.General')

while True:
    msgs = subscriber.recv_multipart()

    report = probereport_pb2.ProbeReport()

    report.ParseFromString(msgs[1])
    
    print 'probe name:',msgs[0]
    print 'timestamp:',report.timestamp
    print 'tag:',report.tag
    print 'index:',report.index
    print 'uuid:',uuid.UUID(bytes=report.uuid)
    print 'data name:',report.data.name
    print 'data module:',report.data.module
    print 'data version:',report.data.version
    print 'data length:',len(report.data.blob)
    print

Below is a sample of the output produced by the above script.

probe name: EMANE.VirtualTransport.Counters.General.node-8
timestamp: 1469219070
tag: node-8
index: 2
uuid: 4f719efe-d8f4-4b35-bf15-9f4328664986
data name: Measurement_emane_virtualtransport_counters_general
data module: otestpoint.emane.virtualtransport
data version: 1
data length: 151

probe name: EMANE.VirtualTransport.Counters.General.node-4
timestamp: 1469219070
tag: node-4
index: 2
uuid: f53a2f17-c0d2-4f72-8b83-38bc958722c6
data name: Measurement_emane_virtualtransport_counters_general
data module: otestpoint.emane.virtualtransport
data version: 1
data length: 151
<...truncated for listing...>

Probe Message Stream Format

Probe Message Stream Format uses length prefix framing, where the length of the serialized ProbeReport message is output as an unsigned 32-bit integer value (4 bytes) in network byte order preceding the output of the serialized message.