Protocol Documentation

Table of Contents

• dropsonde-protocol/events/envelope.proto

  • Envelope

  • Envelope.TagsEntry

  • Envelope.EventType

• dropsonde-protocol/events/error.proto

  • Error

• dropsonde-protocol/events/http.proto

  • HttpStartStop

  • Method

  • PeerType

• dropsonde-protocol/events/log.proto

  • LogMessage

  • LogMessage.MessageType

• dropsonde-protocol/events/metric.proto

  • ContainerMetric
  • CounterEvent
  • ValueMetric

• dropsonde-protocol/events/uuid.proto

  • UUID

• Scalar Value Types

Top

dropsonde-protocol/events/envelope.proto

Envelope

Envelope wraps an Event and adds metadata.

Field	Type	Label	Description
origin	string	required	Unique description of the origin of this event.
eventType	Envelope.EventType	required	Type of wrapped event. Only the optional field corresponding to the value of eventType should be set.
timestamp	int64	optional	UNIX timestamp (in nanoseconds) event was wrapped in this Envelope.
deployment	string	optional	Deployment name (used to uniquely identify source).
job	string	optional	Job name (used to uniquely identify source).
index	string	optional	Index of job (used to uniquely identify source).
ip	string	optional	IP address (used to uniquely identify source).
tags	Envelope.TagsEntry	repeated	key/value tags to include additional identifying information.
httpStartStop	HttpStartStop	optional
logMessage	LogMessage	optional
valueMetric	ValueMetric	optional
counterEvent	CounterEvent	optional
error	Error	optional
containerMetric	ContainerMetric	optional

Envelope.TagsEntry

Field	Type	Label	Description
key	string	optional
value	string	optional

Envelope.EventType

Type of the wrapped event.

Name	Number	Description
HttpStartStop	4
LogMessage	5
ValueMetric	6
CounterEvent	7
Error	8
ContainerMetric	9

Top

dropsonde-protocol/events/error.proto

Error

An Error event represents an error in the originating process.

Field	Type	Label	Description
source	string	required	Source of the error. This may or may not be the same as the Origin in the envelope.
code	int32	required	Numeric error code. This is provided for programmatic responses to the error.
message	string	required	Error description (preferably human-readable).

Top

dropsonde-protocol/events/http.proto

HttpStartStop

An HttpStartStop event represents the whole lifecycle of an HTTP request.

Field	Type	Label	Description
startTimestamp	int64	required	UNIX timestamp (in nanoseconds) when the request was sent (by a client) or received (by a server).
stopTimestamp	int64	required	UNIX timestamp (in nanoseconds) when the request was received.
requestId	UUID	required	ID for tracking lifecycle of request.
peerType	PeerType	required	Role of the emitting process in the request cycle.
method	Method	required	Method of the request.
uri	string	required	Destination of the request.
remoteAddress	string	required	Remote address of the request. (For a server, this should be the origin of the request.)
userAgent	string	required	Contents of the UserAgent header on the request.
statusCode	int32	required	Status code returned with the response to the request.
contentLength	int64	required	Length of response (bytes).
applicationId	UUID	optional	If this request was made in relation to an appliciation, this field should track that application's ID.
instanceIndex	int32	optional	Index of the application instance.
instanceId	string	optional	ID of the application instance.
forwarded	string	repeated	This contains http forwarded-for [x-forwarded-for] header from the request.

Method

HTTP method.

Name	Number	Description
GET	1
POST	2
PUT	3
DELETE	4
HEAD	5
ACL	6
BASELINE_CONTROL	7
BIND	8
CHECKIN	9
CHECKOUT	10
CONNECT	11
COPY	12
DEBUG	13
LABEL	14
LINK	15
LOCK	16
MERGE	17
MKACTIVITY	18
MKCALENDAR	19
MKCOL	20
MKREDIRECTREF	21
MKWORKSPACE	22
MOVE	23
OPTIONS	24
ORDERPATCH	25
PATCH	26
PRI	27
PROPFIND	28
PROPPATCH	29
REBIND	30
REPORT	31
SEARCH	32
SHOWMETHOD	33
SPACEJUMP	34
TEXTSEARCH	35
TRACE	36
TRACK	37
UNBIND	38
UNCHECKOUT	39
UNLINK	40
UNLOCK	41
UPDATE	42
UPDATEREDIRECTREF	43
VERSION_CONTROL	44

PeerType

Type of peer handling request.

Name	Number	Description
Client	1	Request is made by this process.
Server	2	Request is received by this process.

Top

dropsonde-protocol/events/log.proto

LogMessage

A LogMessage contains a "log line" and associated metadata.

Field	Type	Label	Description
message	bytes	required	Bytes of the log message. (Note that it is not required to be a single line.)
message_type	LogMessage.MessageType	required	Type of the message (OUT or ERR).
timestamp	int64	required	UNIX timestamp (in nanoseconds) when the log was written.
app_id	string	optional	Application that emitted the message (or to which the application is related).
source_type	string	optional	Source of the message. For Cloud Foundry, this can be "APP", "RTR", "DEA", "STG", etc.
source_instance	string	optional	Instance that emitted the message.

LogMessage.MessageType

MessageType stores the destination of the message (corresponding to STDOUT or STDERR).

Name	Number	Description
OUT	1
ERR	2

Top

dropsonde-protocol/events/metric.proto

ContainerMetric

A ContainerMetric records resource usage of an app in a container.

Field	Type	Label	Description
applicationId	string	required	ID of the contained application.
instanceIndex	int32	required	Instance index of the contained application. (This, with applicationId, should uniquely identify a container.)
cpuPercentage	double	required	CPU based on number of cores.
memoryBytes	uint64	required	Bytes of memory used.
diskBytes	uint64	required	Bytes of disk used.
memoryBytesQuota	uint64	optional	Maximum bytes of memory allocated to container.
diskBytesQuota	uint64	optional	Maximum bytes of disk allocated to container.

CounterEvent

A CounterEvent represents the increment of a counter. It contains only the change in the value; it is the responsibility of downstream consumers to maintain the value of the counter.

Field	Type	Label	Description
name	string	required	Name of the counter. Must be consistent for downstream consumers to associate events semantically.
delta	uint64	required	Amount by which to increment the counter.
total	uint64	optional	Total value of the counter. This will be overridden by Metron, which internally tracks the total of each named Counter it receives.

ValueMetric

A ValueMetric indicates the value of a metric at an instant in time.

Field	Type	Label	Description
name	string	required	Name of the metric. Must be consistent for downstream consumers to associate events semantically.
value	double	required	Value at the time of event emission.
unit	string	required	Unit of the metric. Please see http://metrics20.org/spec/#units for ideas; SI units/prefixes are recommended where applicable. Should be consistent for the life of the metric (consumers are expected to report, but not interpret, prefixes).

Top

dropsonde-protocol/events/uuid.proto

UUID

Type representing a 128-bit UUID.

The bytes of the UUID should be packed in little-endian byte (not bit) order. For example, the UUID f47ac10b-58cc-4372-a567-0e02b2c3d479 should be encoded as UUID{ low: 0x7243cc580bc17af4, high: 0x79d4c3b2020e67a5 }

Field	Type	Label	Description
low	uint64	required
high	uint64	required

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than $2^{28}$.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than $2^{56}$.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)