Protocol Documentation

Table of Contents

Top

observer/observer.proto

ExportEvent

ExportEvent contains an event to be exported. Not to be used outside of the exporter feature.

Field

Type

Label

Description

flow

flow.Flow

node_status

relay.NodeStatusEvent

node_status informs clients about the state of the nodes participating in this particular GetFlows request.

lost_events

flow.LostEvent

lost_events informs clients about events which got dropped due to a Hubble component being unavailable

agent_event

flow.AgentEvent

agent_event informs clients about an event received from the Cilium agent.

debug_event

flow.DebugEvent

debug_event contains Cilium datapath debug events

node_name

string

Name of the node where this event was observed.

time

google.protobuf.Timestamp

Timestamp at which this event was observed.

GetAgentEventsRequest

Field

Type

Label

Description

number

uint64

Number of flows that should be returned. Incompatible with since/until. Defaults to the most recent (last) number events, unless first is true, then it will return the earliest number events.

first

bool

first specifies if we should look at the first number events or the last number of events. Incompatible with follow.

follow

bool

follow sets when the server should continue to stream agent events after printing the last N agent events.

since

google.protobuf.Timestamp

Since this time for returned agent events. Incompatible with number.

until

google.protobuf.Timestamp

Until this time for returned agent events. Incompatible with number.

GetAgentEventsResponse

GetAgentEventsResponse contains an event received from the Cilium agent.

Field

Type

Label

Description

agent_event

flow.AgentEvent

node_name

string

Name of the node where this event was observed.

time

google.protobuf.Timestamp

Timestamp at which this event was observed.

GetDebugEventsRequest

Field

Type

Label

Description

number

uint64

Number of events that should be returned. Incompatible with since/until. Defaults to the most recent (last) number events, unless first is true, then it will return the earliest number events.

first

bool

first specifies if we should look at the first number events or the last number of events. Incompatible with follow.

follow

bool

follow sets when the server should continue to stream debug events after printing the last N debug events.

since

google.protobuf.Timestamp

Since this time for returned debug events. Incompatible with number.

until

google.protobuf.Timestamp

Until this time for returned debug events. Incompatible with number.

GetDebugEventsResponse

GetDebugEventsResponse contains a Cilium datapath debug events.

Field

Type

Label

Description

debug_event

flow.DebugEvent

node_name

string

Name of the node where this event was observed.

time

google.protobuf.Timestamp

Timestamp at which this event was observed.

GetFlowsRequest

Field

Type

Label

Description

number

uint64

Number of flows that should be returned. Incompatible with since/until. Defaults to the most recent (last) number flows, unless first is true, then it will return the earliest number flows.

first

bool

first specifies if we should look at the first number flows or the last number of flows. Incompatible with follow.

follow

bool

follow sets when the server should continue to stream flows after printing the last N flows.

blacklist

flow.FlowFilter

repeated

blacklist defines a list of filters which have to match for a flow to be excluded from the result. If multiple blacklist filters are specified, only one of them has to match for a flow to be excluded.

whitelist

flow.FlowFilter

repeated

whitelist defines a list of filters which have to match for a flow to be included in the result. If multiple whitelist filters are specified, only one of them has to match for a flow to be included. The whitelist and blacklist can both be specified. In such cases, the set of the returned flows is the set difference whitelist - blacklist. In other words, the result will contain all flows matched by the whitelist that are not also simultaneously matched by the blacklist.

since

google.protobuf.Timestamp

Since this time for returned flows. Incompatible with number.

until

google.protobuf.Timestamp

Until this time for returned flows. Incompatible with number.

field_mask

google.protobuf.FieldMask

FieldMask allows clients to limit flow’s fields that will be returned. For example, {paths: [“source.id”, “destination.id”]} will return flows with only these two fields set.

experimental

GetFlowsRequest.Experimental

extensions

google.protobuf.Any

extensions can be used to add arbitrary additional metadata to GetFlowsRequest. This can be used to extend functionality for other Hubble compatible APIs, or experiment with new functionality without needing to change the public API.

GetFlowsRequest.Experimental

Experimental contains fields that are not stable yet. Support for experimental features is always optional and subject to change.

Field

Type

Label

Description

field_mask

google.protobuf.FieldMask

Deprecated. FieldMask allows clients to limit flow’s fields that will be returned. For example, {paths: [“source.id”, “destination.id”]} will return flows with only these two fields set. Deprecated in favor of top-level field_mask. This field will be removed in v1.17.

GetFlowsResponse

GetFlowsResponse contains either a flow or a protocol message.

Field

Type

Label

Description

flow

flow.Flow

node_status

relay.NodeStatusEvent

node_status informs clients about the state of the nodes participating in this particular GetFlows request.

lost_events

flow.LostEvent

lost_events informs clients about events which got dropped due to a Hubble component being unavailable

node_name

string

Name of the node where this event was observed.

time

google.protobuf.Timestamp

Timestamp at which this event was observed.

GetNamespacesRequest

GetNamespacesResponse

GetNamespacesResponse contains the list of namespaces.

Field

Type

Label

Description

namespaces

Namespace

repeated

Namespaces is a list of namespaces with flows

GetNodesRequest

GetNodesResponse

GetNodesResponse contains the list of nodes.

Field

Type

Label

Description

nodes

Node

repeated

Nodes is an exhaustive list of nodes.

Namespace

Field

Type

Label

Description

cluster

string

namespace

string

Node

Node represents a cluster node.

Field

Type

Label

Description

name

string

Name is the name of the node.

version

string

Version is the version of Cilium/Hubble as reported by the node.

address

string

Address is the network address of the API endpoint.

state

relay.NodeState

State represents the known state of the node.

tls

TLS

TLS reports TLS related information.

uptime_ns

uint64

UptimeNS is the uptime of this instance in nanoseconds

num_flows

uint64

number of currently captured flows

max_flows

uint64

maximum capacity of the ring buffer

seen_flows

uint64

total amount of flows observed since the observer was started

ServerStatusRequest

ServerStatusResponse

Field

Type

Label

Description

num_flows

uint64

number of currently captured flows In a multi-node context, this is the cumulative count of all captured flows.

max_flows

uint64

maximum capacity of the ring buffer In a multi-node context, this is the aggregation of all ring buffers capacities.

seen_flows

uint64

total amount of flows observed since the observer was started In a multi-node context, this is the aggregation of all flows that have been seen.

uptime_ns

uint64

uptime of this observer instance in nanoseconds In a multi-node context, this field corresponds to the uptime of the longest living instance.

num_connected_nodes

google.protobuf.UInt32Value

number of nodes for which a connection is established

num_unavailable_nodes

google.protobuf.UInt32Value

number of nodes for which a connection cannot be established

unavailable_nodes

string

repeated

list of nodes that are unavailable This list may not be exhaustive.

version

string

Version is the version of Cilium/Hubble.

flows_rate

double

Approximate rate of flows seen by Hubble per second over the last minute. In a multi-node context, this is the sum of all flows rates.

TLS

TLS represents TLS information.

Field

Type

Label

Description

enabled

bool

Enabled reports whether TLS is enabled or not.

server_name

string

ServerName is the TLS server name that can be used as part of the TLS cert validation process.

Observer

Observer returns a stream of Flows depending on which filter the user want to observe.

Method Name

Request Type

Response Type

Description

GetFlows

GetFlowsRequest

GetFlowsResponse stream

GetFlows returning structured data, meant to eventually obsolete GetLastNFlows.

GetAgentEvents

GetAgentEventsRequest

GetAgentEventsResponse stream

GetAgentEvents returns Cilium agent events.

GetDebugEvents

GetDebugEventsRequest

GetDebugEventsResponse stream

GetDebugEvents returns Cilium datapath debug events.

GetNodes

GetNodesRequest

GetNodesResponse

GetNodes returns information about nodes in a cluster.

GetNamespaces

GetNamespacesRequest

GetNamespacesResponse

GetNamespaces returns information about namespaces in a cluster. The namespaces returned are namespaces which have had network flows in the last hour. The namespaces are returned sorted by cluster name and namespace in ascending order.

ServerStatus

ServerStatusRequest

ServerStatusResponse

ServerStatus returns some details about the running hubble server.

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)