github.com/cilium/cilium@v1.16.2/api/v1/observer/README.md (about) 1 # Protocol Documentation 2 <a name="top"></a> 3 4 ## Table of Contents 5 6 - [observer/observer.proto](#observer_observer-proto) 7 - [ExportEvent](#observer-ExportEvent) 8 - [GetAgentEventsRequest](#observer-GetAgentEventsRequest) 9 - [GetAgentEventsResponse](#observer-GetAgentEventsResponse) 10 - [GetDebugEventsRequest](#observer-GetDebugEventsRequest) 11 - [GetDebugEventsResponse](#observer-GetDebugEventsResponse) 12 - [GetFlowsRequest](#observer-GetFlowsRequest) 13 - [GetFlowsRequest.Experimental](#observer-GetFlowsRequest-Experimental) 14 - [GetFlowsResponse](#observer-GetFlowsResponse) 15 - [GetNamespacesRequest](#observer-GetNamespacesRequest) 16 - [GetNamespacesResponse](#observer-GetNamespacesResponse) 17 - [GetNodesRequest](#observer-GetNodesRequest) 18 - [GetNodesResponse](#observer-GetNodesResponse) 19 - [Namespace](#observer-Namespace) 20 - [Node](#observer-Node) 21 - [ServerStatusRequest](#observer-ServerStatusRequest) 22 - [ServerStatusResponse](#observer-ServerStatusResponse) 23 - [TLS](#observer-TLS) 24 25 - [Observer](#observer-Observer) 26 27 - [Scalar Value Types](#scalar-value-types) 28 29 30 31 <a name="observer_observer-proto"></a> 32 <p align="right"><a href="#top">Top</a></p> 33 34 ## observer/observer.proto 35 36 37 38 <a name="observer-ExportEvent"></a> 39 40 ### ExportEvent 41 ExportEvent contains an event to be exported. Not to be used outside of the 42 exporter feature. 43 44 45 | Field | Type | Label | Description | 46 | ----- | ---- | ----- | ----------- | 47 | flow | [flow.Flow](#flow-Flow) | | | 48 | node_status | [relay.NodeStatusEvent](#relay-NodeStatusEvent) | | node_status informs clients about the state of the nodes participating in this particular GetFlows request. | 49 | lost_events | [flow.LostEvent](#flow-LostEvent) | | lost_events informs clients about events which got dropped due to a Hubble component being unavailable | 50 | agent_event | [flow.AgentEvent](#flow-AgentEvent) | | agent_event informs clients about an event received from the Cilium agent. | 51 | debug_event | [flow.DebugEvent](#flow-DebugEvent) | | debug_event contains Cilium datapath debug events | 52 | node_name | [string](#string) | | Name of the node where this event was observed. | 53 | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Timestamp at which this event was observed. | 54 55 56 57 58 59 60 <a name="observer-GetAgentEventsRequest"></a> 61 62 ### GetAgentEventsRequest 63 64 65 66 | Field | Type | Label | Description | 67 | ----- | ---- | ----- | ----------- | 68 | number | [uint64](#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. | 69 | first | [bool](#bool) | | first specifies if we should look at the first `number` events or the last `number` of events. Incompatible with `follow`. | 70 | follow | [bool](#bool) | | follow sets when the server should continue to stream agent events after printing the last N agent events. | 71 | since | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Since this time for returned agent events. Incompatible with `number`. | 72 | until | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Until this time for returned agent events. Incompatible with `number`. | 73 74 75 76 77 78 79 <a name="observer-GetAgentEventsResponse"></a> 80 81 ### GetAgentEventsResponse 82 GetAgentEventsResponse contains an event received from the Cilium agent. 83 84 85 | Field | Type | Label | Description | 86 | ----- | ---- | ----- | ----------- | 87 | agent_event | [flow.AgentEvent](#flow-AgentEvent) | | | 88 | node_name | [string](#string) | | Name of the node where this event was observed. | 89 | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Timestamp at which this event was observed. | 90 91 92 93 94 95 96 <a name="observer-GetDebugEventsRequest"></a> 97 98 ### GetDebugEventsRequest 99 100 101 102 | Field | Type | Label | Description | 103 | ----- | ---- | ----- | ----------- | 104 | number | [uint64](#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. | 105 | first | [bool](#bool) | | first specifies if we should look at the first `number` events or the last `number` of events. Incompatible with `follow`. | 106 | follow | [bool](#bool) | | follow sets when the server should continue to stream debug events after printing the last N debug events. | 107 | since | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Since this time for returned debug events. Incompatible with `number`. | 108 | until | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Until this time for returned debug events. Incompatible with `number`. | 109 110 111 112 113 114 115 <a name="observer-GetDebugEventsResponse"></a> 116 117 ### GetDebugEventsResponse 118 GetDebugEventsResponse contains a Cilium datapath debug events. 119 120 121 | Field | Type | Label | Description | 122 | ----- | ---- | ----- | ----------- | 123 | debug_event | [flow.DebugEvent](#flow-DebugEvent) | | | 124 | node_name | [string](#string) | | Name of the node where this event was observed. | 125 | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Timestamp at which this event was observed. | 126 127 128 129 130 131 132 <a name="observer-GetFlowsRequest"></a> 133 134 ### GetFlowsRequest 135 136 137 138 | Field | Type | Label | Description | 139 | ----- | ---- | ----- | ----------- | 140 | number | [uint64](#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. | 141 | first | [bool](#bool) | | first specifies if we should look at the first `number` flows or the last `number` of flows. Incompatible with `follow`. | 142 | follow | [bool](#bool) | | follow sets when the server should continue to stream flows after printing the last N flows. | 143 | blacklist | [flow.FlowFilter](#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. | 144 | whitelist | [flow.FlowFilter](#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. | 145 | since | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Since this time for returned flows. Incompatible with `number`. | 146 | until | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Until this time for returned flows. Incompatible with `number`. | 147 | field_mask | [google.protobuf.FieldMask](#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. | 148 | experimental | [GetFlowsRequest.Experimental](#observer-GetFlowsRequest-Experimental) | | | 149 | extensions | [google.protobuf.Any](#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. | 150 151 152 153 154 155 156 <a name="observer-GetFlowsRequest-Experimental"></a> 157 158 ### GetFlowsRequest.Experimental 159 Experimental contains fields that are not stable yet. Support for 160 experimental features is always optional and subject to change. 161 162 163 | Field | Type | Label | Description | 164 | ----- | ---- | ----- | ----------- | 165 | field_mask | [google.protobuf.FieldMask](#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. | 166 167 168 169 170 171 172 <a name="observer-GetFlowsResponse"></a> 173 174 ### GetFlowsResponse 175 GetFlowsResponse contains either a flow or a protocol message. 176 177 178 | Field | Type | Label | Description | 179 | ----- | ---- | ----- | ----------- | 180 | flow | [flow.Flow](#flow-Flow) | | | 181 | node_status | [relay.NodeStatusEvent](#relay-NodeStatusEvent) | | node_status informs clients about the state of the nodes participating in this particular GetFlows request. | 182 | lost_events | [flow.LostEvent](#flow-LostEvent) | | lost_events informs clients about events which got dropped due to a Hubble component being unavailable | 183 | node_name | [string](#string) | | Name of the node where this event was observed. | 184 | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Timestamp at which this event was observed. | 185 186 187 188 189 190 191 <a name="observer-GetNamespacesRequest"></a> 192 193 ### GetNamespacesRequest 194 195 196 197 198 199 200 201 <a name="observer-GetNamespacesResponse"></a> 202 203 ### GetNamespacesResponse 204 GetNamespacesResponse contains the list of namespaces. 205 206 207 | Field | Type | Label | Description | 208 | ----- | ---- | ----- | ----------- | 209 | namespaces | [Namespace](#observer-Namespace) | repeated | Namespaces is a list of namespaces with flows | 210 211 212 213 214 215 216 <a name="observer-GetNodesRequest"></a> 217 218 ### GetNodesRequest 219 220 221 222 223 224 225 226 <a name="observer-GetNodesResponse"></a> 227 228 ### GetNodesResponse 229 GetNodesResponse contains the list of nodes. 230 231 232 | Field | Type | Label | Description | 233 | ----- | ---- | ----- | ----------- | 234 | nodes | [Node](#observer-Node) | repeated | Nodes is an exhaustive list of nodes. | 235 236 237 238 239 240 241 <a name="observer-Namespace"></a> 242 243 ### Namespace 244 245 246 247 | Field | Type | Label | Description | 248 | ----- | ---- | ----- | ----------- | 249 | cluster | [string](#string) | | | 250 | namespace | [string](#string) | | | 251 252 253 254 255 256 257 <a name="observer-Node"></a> 258 259 ### Node 260 Node represents a cluster node. 261 262 263 | Field | Type | Label | Description | 264 | ----- | ---- | ----- | ----------- | 265 | name | [string](#string) | | Name is the name of the node. | 266 | version | [string](#string) | | Version is the version of Cilium/Hubble as reported by the node. | 267 | address | [string](#string) | | Address is the network address of the API endpoint. | 268 | state | [relay.NodeState](#relay-NodeState) | | State represents the known state of the node. | 269 | tls | [TLS](#observer-TLS) | | TLS reports TLS related information. | 270 | uptime_ns | [uint64](#uint64) | | UptimeNS is the uptime of this instance in nanoseconds | 271 | num_flows | [uint64](#uint64) | | number of currently captured flows | 272 | max_flows | [uint64](#uint64) | | maximum capacity of the ring buffer | 273 | seen_flows | [uint64](#uint64) | | total amount of flows observed since the observer was started | 274 275 276 277 278 279 280 <a name="observer-ServerStatusRequest"></a> 281 282 ### ServerStatusRequest 283 284 285 286 287 288 289 290 <a name="observer-ServerStatusResponse"></a> 291 292 ### ServerStatusResponse 293 294 295 296 | Field | Type | Label | Description | 297 | ----- | ---- | ----- | ----------- | 298 | num_flows | [uint64](#uint64) | | number of currently captured flows In a multi-node context, this is the cumulative count of all captured flows. | 299 | max_flows | [uint64](#uint64) | | maximum capacity of the ring buffer In a multi-node context, this is the aggregation of all ring buffers capacities. | 300 | seen_flows | [uint64](#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. | 301 | uptime_ns | [uint64](#uint64) | | uptime of this observer instance in nanoseconds In a multi-node context, this field corresponds to the uptime of the longest living instance. | 302 | num_connected_nodes | [google.protobuf.UInt32Value](#google-protobuf-UInt32Value) | | number of nodes for which a connection is established | 303 | num_unavailable_nodes | [google.protobuf.UInt32Value](#google-protobuf-UInt32Value) | | number of nodes for which a connection cannot be established | 304 | unavailable_nodes | [string](#string) | repeated | list of nodes that are unavailable This list may not be exhaustive. | 305 | version | [string](#string) | | Version is the version of Cilium/Hubble. | 306 | flows_rate | [double](#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. | 307 308 309 310 311 312 313 <a name="observer-TLS"></a> 314 315 ### TLS 316 TLS represents TLS information. 317 318 319 | Field | Type | Label | Description | 320 | ----- | ---- | ----- | ----------- | 321 | enabled | [bool](#bool) | | Enabled reports whether TLS is enabled or not. | 322 | server_name | [string](#string) | | ServerName is the TLS server name that can be used as part of the TLS cert validation process. | 323 324 325 326 327 328 329 330 331 332 333 334 335 <a name="observer-Observer"></a> 336 337 ### Observer 338 Observer returns a stream of Flows depending on which filter the user want 339 to observe. 340 341 | Method Name | Request Type | Response Type | Description | 342 | ----------- | ------------ | ------------- | ------------| 343 | GetFlows | [GetFlowsRequest](#observer-GetFlowsRequest) | [GetFlowsResponse](#observer-GetFlowsResponse) stream | GetFlows returning structured data, meant to eventually obsolete GetLastNFlows. | 344 | GetAgentEvents | [GetAgentEventsRequest](#observer-GetAgentEventsRequest) | [GetAgentEventsResponse](#observer-GetAgentEventsResponse) stream | GetAgentEvents returns Cilium agent events. | 345 | GetDebugEvents | [GetDebugEventsRequest](#observer-GetDebugEventsRequest) | [GetDebugEventsResponse](#observer-GetDebugEventsResponse) stream | GetDebugEvents returns Cilium datapath debug events. | 346 | GetNodes | [GetNodesRequest](#observer-GetNodesRequest) | [GetNodesResponse](#observer-GetNodesResponse) | GetNodes returns information about nodes in a cluster. | 347 | GetNamespaces | [GetNamespacesRequest](#observer-GetNamespacesRequest) | [GetNamespacesResponse](#observer-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. | 348 | ServerStatus | [ServerStatusRequest](#observer-ServerStatusRequest) | [ServerStatusResponse](#observer-ServerStatusResponse) | ServerStatus returns some details about the running hubble server. | 349 350 351 352 353 354 ## Scalar Value Types 355 356 | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | 357 | ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | 358 | <a name="double" /> double | | double | double | float | float64 | double | float | Float | 359 | <a name="float" /> float | | float | float | float | float32 | float | float | Float | 360 | <a name="int32" /> 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) | 361 | <a name="int64" /> 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 | 362 | <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | 363 | <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | 364 | <a name="sint32" /> 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) | 365 | <a name="sint64" /> 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 | 366 | <a name="fixed32" /> 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) | 367 | <a name="fixed64" /> 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 | 368 | <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | 369 | <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | 370 | <a name="bool" /> bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | 371 | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | 372 | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | 373