Communication Protocol

What is this page about?

It describes the communication protocol between Greg server and client.

Use it to write a new client for your favourite language.

The protocol

The protocol is just over tcp. The whole protocol is little-endian. All timestamps are int64 - nanoseconds since 1970-01-01 00:00:00 UTC.

(this means that timestamps should not be computed using the system clock, which is amenable to anomalies like manual time changes, leap seconds etc. - the purpose of Greg is not precision of timestamps, but precision of durations. A way of implementation is to capture the system time at initialization and use a high-precision interval timer to compute the "current timestamp" as "initial time + elapsed time").

There are two parts: messages and calibration.

Messages

Clients MUST periodically send batches of messages. Size of these batches MUST NOT exceed 10,000.

Server listens to messages on port 5676 by default (see ConfigurationGuide).

A batch has the following format:

• uuid (16 bytes) - a GUID unique to the client process. Server associates clock offset with each such GUID.
• useCompression (1 byte) - a boolean: whether gzip compression will be used for messages. 0 = false, 1 = true.
• body (remaining) - messages; probably gzip-compressed, depending on useCompression.

Body is a sequence of records, with (int32)1 before each record and (int32)0 after the last record. Each record has the following format:

• timestamp (int64) - event generation timestamp
• machineLenBytes (int32)
• machine (machineLenBytes bytes) - an UTF8-encoded string with name of the client machine
• msgLenBytes (int32)
• msg (msgLenBytes bytes) - the UTF8-encoded message

Calibration

Clients MUST periodically initiate "calibration cycles" with server. They are initiated by the client but, after initiation, "controlled" by the server. Clients MUST use TCP no-delay. Server listens for calibration cycles on port 5677 by default.

The interaction is as follows:

• Client writes its uuid (16 bytes) - see above.
• loop:
  • Client reads and ignores an int64 (server's timestamp)
  • Client writes an int64 (client's timestamp)

The loop proceeds until server closes the connection.