Skip to content

Latest commit

 

History

History
433 lines (236 loc) · 13.9 KB

README.md

File metadata and controls

433 lines (236 loc) · 13.9 KB
Raw

Protocol Documentation

Table of Contents

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)