Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Protocol Documentation

Table of Contents

Top

quilkin/relay/v1alpha1/relay.proto

AggregatedControlPlaneDiscoveryService

The Manager Discovery Service provides an RPC for a management service to upstream its configuration to a relay service. This RPC works essentially the same as xDS, except instead of the client connecting to the server to receive configuration, the client is connecting to the server send its configuration.

This service enables the relay to merge the configuration of all currently live management servers as a single aggregated xDS server without the relay needing to maintain a list of xDS servers to connect to in the relay itself.

Method NameRequest TypeResponse TypeDescription
StreamAggregatedResources.envoy.service.discovery.v3.DiscoveryResponse stream.envoy.service.discovery.v3.DiscoveryRequest streamThis RPC is not supported but remains here as part of the xDS standard, as Quilkin only uses a delta configuration transport for performance reasons.
DeltaAggregatedResources.envoy.service.discovery.v3.DeltaDiscoveryResponse stream.envoy.service.discovery.v3.DeltaDiscoveryRequest streamDelta (Incremental) xDS implementation, used by agents and/or management servers to update the relay with their configuration
SubscribeDeltaResources.envoy.service.discovery.v3.DeltaDiscoveryRequest stream.envoy.service.discovery.v3.DeltaDiscoveryResponse streamUsed by proxies to subscribe to changes from the relay

Top

quilkin/config/v1alpha1/config.proto

Cluster

FieldTypeLabelDescription
localityLocality
endpointsEndpointrepeated

ClusterMap

FieldTypeLabelDescription
clustersClusterrepeated

Datacenter

FieldTypeLabelDescription
hoststring
qcmp_portuint32
icao_codestring

Endpoint

FieldTypeLabelDescription
hoststring
portuint32
metadatagoogle.protobuf.Struct
host2Host

Filter

FieldTypeLabelDescription
namestring
labelstringoptional
configstringoptional

FilterChain

FieldTypeLabelDescription
filtersFilterrepeated

Host

FieldTypeLabelDescription
namestring
ipv4fixed32
ipv6Ipv6

Ipv6

FieldTypeLabelDescription
firstfixed64
secondfixed64

Locality

FieldTypeLabelDescription
regionstring
zonestring
sub_zonestring

Top

quilkin/filters/capture/v1alpha1/capture.proto

Capture

FieldTypeLabelDescription
metadata_keygoogle.protobuf.StringValue
prefixCapture.Prefix
suffixCapture.Suffix
regexCapture.Regex

Capture.Prefix

FieldTypeLabelDescription
sizeuint32
removegoogle.protobuf.BoolValue

Capture.Regex

FieldTypeLabelDescription
regexgoogle.protobuf.StringValue

Capture.Suffix

FieldTypeLabelDescription
sizeuint32
removegoogle.protobuf.BoolValue

Top

quilkin/filters/concatenate/v1alpha1/concatenate.proto

Concatenate

FieldTypeLabelDescription
on_writeConcatenate.StrategyValue
on_readConcatenate.StrategyValue
bytesbytes

Concatenate.StrategyValue

FieldTypeLabelDescription
valueConcatenate.Strategy

Concatenate.Strategy

NameNumberDescription
DoNothing0
Append1
Prepend2

Top

quilkin/filters/debug/v1alpha1/debug.proto

Debug

FieldTypeLabelDescription
idgoogle.protobuf.StringValue

Top

quilkin/filters/drop/v1alpha1/drop.proto

Drop

Top

quilkin/filters/firewall/v1alpha1/firewall.proto

Firewall

FieldTypeLabelDescription
on_readFirewall.Rulerepeated
on_writeFirewall.Rulerepeated

Firewall.PortRange

FieldTypeLabelDescription
minuint32
maxuint32

Firewall.Rule

FieldTypeLabelDescription
actionFirewall.Action
sourcesstringrepeated
portsFirewall.PortRangerepeated

Firewall.Action

NameNumberDescription
Allow0
Deny1

Top

quilkin/filters/load_balancer/v1alpha1/load_balancer.proto

LoadBalancer

FieldTypeLabelDescription
policyLoadBalancer.PolicyValue

LoadBalancer.PolicyValue

FieldTypeLabelDescription
valueLoadBalancer.Policy

LoadBalancer.Policy

NameNumberDescription
RoundRobin0
Random1
Hash2

Top

quilkin/filters/local_rate_limit/v1alpha1/local_rate_limit.proto

LocalRateLimit

FieldTypeLabelDescription
max_packetsuint64
periodgoogle.protobuf.UInt32Value

Top

quilkin/filters/match/v1alpha1/match.proto

Match

FieldTypeLabelDescription
on_readMatch.Configoptional
on_writeMatch.Configoptional

Match.Branch

FieldTypeLabelDescription
valuegoogle.protobuf.Value
filterenvoy.config.listener.v3.Filter

Match.Config

FieldTypeLabelDescription
metadata_keygoogle.protobuf.StringValue
branchesMatch.Branchrepeated
fallthroughenvoy.config.listener.v3.Filter

Top

quilkin/filters/pass/v1alpha1/pass.proto

Pass

Top

quilkin/filters/token_router/v1alpha1/token_router.proto

TokenRouter

FieldTypeLabelDescription
metadata_keygoogle.protobuf.StringValue

Top

quilkin/filters/timestamp/v1alpha1/timestamp.proto

Timestamp

FieldTypeLabelDescription
metadata_keygoogle.protobuf.StringValue

Top

quilkin/pprof.proto

Function

FieldTypeLabelDescription
iduint64Unique nonzero id for the function.
nameint64Name of the function, in human-readable form if available.

Index into string table | | system_name | int64 | | Name of the function, as identified by the system. For instance, it can be a C++ mangled name.

Index into string table | | filename | int64 | | Source file containing the function.

Index into string table | | start_line | int64 | | Line number in source file. |

Label

FieldTypeLabelDescription
keyint64Index into string table
strint64At most one of the following must be present

Index into string table | | num | int64 | | | | num_unit | int64 | | Should only be present when num is present. Specifies the units of num. Use arbitrary string (for example, "requests") as a custom count unit. If no unit is specified, consumer may apply heuristic to deduce the unit. Consumers may also interpret units like "bytes" and "kilobytes" as memory units and units like "seconds" and "nanoseconds" as time units, and apply appropriate unit conversions to these.

Index into string table |

Line

FieldTypeLabelDescription
function_iduint64The id of the corresponding profile.Function for this line.
lineint64Line number in source code.

Location

Describes function and line table debug information.

FieldTypeLabelDescription
iduint64Unique nonzero id for the location. A profile could use instruction addresses or any integer sequence as ids.
mapping_iduint64The id of the corresponding profile.Mapping for this location. It can be unset if the mapping is unknown or not applicable for this profile type.
addressuint64The instruction address for this location, if available. It should be within [Mapping.memory_start...Mapping.memory_limit] for the corresponding mapping. A non-leaf address may be in the middle of a call instruction. It is up to display tools to find the beginning of the instruction if necessary.
lineLinerepeatedMultiple line indicates this location has inlined functions, where the last entry represents the caller into which the preceding entries were inlined.

E.g., if memcpy() is inlined into printf: line[0].function_name == "memcpy" line[1].function_name == "printf" | | is_folded | bool | | Provides an indication that multiple symbols map to this location's address, for example due to identical code folding by the linker. In that case the line information above represents one of the multiple symbols. This field must be recomputed when the symbolization state of the profile changes. |

Mapping

FieldTypeLabelDescription
iduint64Unique nonzero id for the mapping.
memory_startuint64Address at which the binary (or DLL) is loaded into memory.
memory_limituint64The limit of the address range occupied by this mapping.
file_offsetuint64Offset in the binary that corresponds to the first mapped address.
filenameint64The object this entry is loaded from. This can be a filename on disk for the main binary and shared libraries, or virtual abstractions like "[vdso]".

Index into string table | | build_id | int64 | | A string that uniquely identifies a particular program version with high probability. E.g., for binaries generated by GNU tools, it could be the contents of the .note.gnu.build-id field.

Index into string table | | has_functions | bool | | The following fields indicate the resolution of symbolic info. | | has_filenames | bool | | | | has_line_numbers | bool | | | | has_inline_frames | bool | | |

Profile

FieldTypeLabelDescription
sample_typeValueTyperepeatedA description of the samples associated with each Sample.value. For a cpu profile this might be: [["cpu","nanoseconds"]] or [["wall","seconds"]] or [["syscall","count"]] For a heap profile, this might be: [["allocations","count"], ["space","bytes"]], If one of the values represents the number of events represented by the sample, by convention it should be at index 0 and use sample_type.unit == "count".
sampleSamplerepeatedThe set of samples recorded in this profile.
mappingMappingrepeatedMapping from address ranges to the image/binary/library mapped into that address range. mapping[0] will be the main binary.
locationLocationrepeatedUseful program location
functionFunctionrepeatedFunctions referenced by locations
string_tablestringrepeatedA common table for strings referenced by various messages. string_table[0] must always be "".
drop_framesint64frames with Function.function_name fully matching the following regexp will be dropped from the samples, along with their successors.

Index into string table. | | keep_frames | int64 | | frames with Function.function_name fully matching the following regexp will be kept, even if it matches drop_functions.

Index into string table. | | time_nanos | int64 | | Time of collection (UTC) represented as nanoseconds past the epoch. | | duration_nanos | int64 | | Duration of the profile, if a duration makes sense. | | period_type | ValueType | | The kind of events between sampled ocurrences. e.g [ "cpu","cycles" ] or [ "heap","bytes" ] | | period | int64 | | The number of events between sampled occurrences. | | comment | int64 | repeated | Freeform text associated to the profile.

Indices into string table. | | default_sample_type | int64 | | Index into the string table of the type of the preferred sample value. If unset, clients should default to the last sample value. |

Sample

Each Sample records values encountered in some program context. The program context is typically a stack trace, perhaps augmented with auxiliary information like the thread-id, some indicator of a higher level request being handled etc.

FieldTypeLabelDescription
location_iduint64repeatedThe ids recorded here correspond to a Profile.location.id. The leaf is at location_id[0].
valueint64repeatedThe type and unit of each value is defined by the corresponding entry in Profile.sample_type. All samples must have the same number of values, the same as the length of Profile.sample_type. When aggregating multiple samples into a single sample, the result has a list of values that is the elemntwise sum of the lists of the originals.
labelLabelrepeatedlabel includes additional context for this sample. It can include things like a thread id, allocation size, etc

ValueType

ValueType describes the semantics and measurement units of a value.

FieldTypeLabelDescription
tyint64Rename it from type to ty to avoid using keyword in Rust.

Index into string table. | | unit | int64 | | Index into string table. |

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)