Wire Agent Data

Data block sent from agent to server is a sequence of tuples of two types:

• string ref definition (TAG=0x01) - defines (typed) string reference;
• method ref definition (TAG=0x02) - defines method triple (consisting of class, method and signature refs);

Data is submitted via HTTP /submit/agent URI with the following parameters:

• host - host UUID;
• data - CBOR data encoded in base64 (use either this parameter or one of following);
• zdata - zlib compressed CBOR data encoded in base64;
• ldata - LZ4 compressed CBOR data encoded in base64;

Wire trace data

Trace data is submitted via collector HTTP API described in last section.

Trace Records

Raw trace is a data stream produced directly by tracer. This format is optimized for agents in order to minimize agent overhead but in doing so it requires some post processing in collector.

Each trace is encoded as variable-length array containing information on current method call:

(TAG=0x03)[methodId,tstart,begin?,attr1?,attr2?,...,sub1,sub2...,attrn?,attrn+1?,...,exception?,epilog,BRK]

• method_id - method ID as assigned when instrumenting class;
• tstart - time since JVM start (in nanoseconds);

Epilog (TRACE_END) is tagged CBOR array that contains one 64-bit word (with optional second word) containing following data:

(TAG=04)[tstamp,calls,flags]

• tstamp - is number of ticks since JVM start; a tick is calculated as System.nanoTime() >> 16 (2¹⁶ ns);
• calls - number of (instrumented) method calls (1 if no methods were called from current method);if this number exceeds 2^24-1, it is set to 0 and 64-bit variant is appended (long_calls);
• flags (optional) - currently only error flag (0x01);

After prolog there can be arbitrary number of attribute maps or subordinate trace records. Also, exception can be added if thrown by method.

TraceBegin

TraceBegin structure marks beginning of a trace.

(TAG=05)[clock,traceId,spanId,parentId]

• clock - current time (as from System.currentTimeMillis());
• spanId - span ID (optional, 64-bit long int);
• parentId - parent ID (optional, 64-bit long int);

TraceAttr

Normal attributes are attached to current method:

(TAG=0x06)[attrId,attrVal]

Where both keys and values can be of arbitrary (possibly recursive) type. Note that both keys or value can be or contain string-refs and similar types.

Upward attributes can be attached to upward method that marks start of a trace:

(TAG=0x06)[traceId,attrId,attrVal]

If traceId = 0, attributes will be attached to any upwards record in the stack. If traceID != 0, appropriate trace top will be selected.

Note that upward attributes

Exceptions

Full exception info is encoded as tagged 5-element array:

(TAG=0b)[id,class,message,cause,stack0,stack1,...,BRK]

• id - (not certainly unique ID) result of System.identityHashCode(e);
• class - exception class name (string);
• message - exception message (string);
• cause - cause ID (encoded as uint, id of exception marked as cause) or 0;
• stackN - single stack trace element;

Each stack element is a string com.myapp.MyClass.myMethod(MyClass.java:123).

Symbols (TAG=0x0d)

(TAG=0x0c)[id,s]

Where:

• id - local ID (assigned by agent)
• s - string;

Method ref (TAG=0x0e)

(TAG=0x0e)[id,classId,methodId,signatureId]

Where:

• id - local ID (assigned by agent);
• class - class name ref (string ref);
• method - method name ref (must be of type 3);
• signature - method signature ref (must be of type 4);

Agent attributes (TAG=0x0f)

(TAG=0x0f){key,val}

Where:

• key - attribute key (string);
• val - attribute value (string);

ZICO Collector HTTP API

Agent registration: /agent/register

POST request with application/json or application/edn map with following keys:

• rkey - registration key (can be distributed)
• name - agent name (eg. zorka.hostname);
• uuid - agent UUID (optional: pass if previously registered);
• akey - authentication key (for previously registered agents)
• app - application (name, not UUID);
• env - environment (name, not UUID);
• attrs - custom agent attribute map (optional);

Returns map containing following fields:

• uuid - host uuid;
• authkey - authentication key (to be used later )

Status codes:

• 200 - success (host already registered);
• 201 - success (new host registered);
• 400 - arguments missing or invalid;
• 401 - access denied;
• 500 - internal error (in collector);

Authenticating and creating session /agent/session

POST request application/json or application/edn map with following keys:

• uuid - agent UUID (obtained from /agent/register);
• authkey - authentication key (obtained from /agent/register);

Returns map containing following fields:

• session - session UUID;

Status codes:

• 200 - success;
• 400 - missing arguments;
• 401 - access denied;

Submitting agent metadata

TBD

Submitting traces

TBD