github.com/cilium/cilium@v1.16.2/api/v1/recorder/README.md (about)

     1  # Protocol Documentation
     2  <a name="top"></a>
     3  
     4  ## Table of Contents
     5  
     6  - [recorder/recorder.proto](#recorder_recorder-proto)
     7      - [FileSinkConfiguration](#recorder-FileSinkConfiguration)
     8      - [FileSinkResult](#recorder-FileSinkResult)
     9      - [Filter](#recorder-Filter)
    10      - [RecordRequest](#recorder-RecordRequest)
    11      - [RecordResponse](#recorder-RecordResponse)
    12      - [RecordingRunningResponse](#recorder-RecordingRunningResponse)
    13      - [RecordingStatistics](#recorder-RecordingStatistics)
    14      - [RecordingStoppedResponse](#recorder-RecordingStoppedResponse)
    15      - [StartRecording](#recorder-StartRecording)
    16      - [StopCondition](#recorder-StopCondition)
    17      - [StopRecording](#recorder-StopRecording)
    18    
    19      - [Protocol](#recorder-Protocol)
    20    
    21      - [Recorder](#recorder-Recorder)
    22    
    23  - [Scalar Value Types](#scalar-value-types)
    24  
    25  
    26  
    27  <a name="recorder_recorder-proto"></a>
    28  <p align="right"><a href="#top">Top</a></p>
    29  
    30  ## recorder/recorder.proto
    31  
    32  
    33  
    34  <a name="recorder-FileSinkConfiguration"></a>
    35  
    36  ### FileSinkConfiguration
    37  FileSinkConfiguration configures the file output. Possible future additions
    38  might be the selection of the output volume. The initial implementation will
    39  only support a single volume which is configured as a cilium-agent CLI flag.
    40  
    41  
    42  | Field | Type | Label | Description |
    43  | ----- | ---- | ----- | ----------- |
    44  | file_prefix | [string](#string) |  | file_prefix is an optional prefix for the file name. Defaults to `hubble` if empty. Must match the following regex if not empty: ^[a-z][a-z0-9]{0,19}$ The generated filename will be of format &lt;file_prefix&gt;_&lt;unixtime&gt;_&lt;unique_random&gt;_&lt;node_name&gt;.pcap |
    45  
    46  
    47  
    48  
    49  
    50  
    51  <a name="recorder-FileSinkResult"></a>
    52  
    53  ### FileSinkResult
    54  
    55  
    56  
    57  | Field | Type | Label | Description |
    58  | ----- | ---- | ----- | ----------- |
    59  | file_path | [string](#string) |  | file_path is the absolute path to the captured pcap file |
    60  
    61  
    62  
    63  
    64  
    65  
    66  <a name="recorder-Filter"></a>
    67  
    68  ### Filter
    69  
    70  
    71  
    72  | Field | Type | Label | Description |
    73  | ----- | ---- | ----- | ----------- |
    74  | source_cidr | [string](#string) |  | source_cidr. Must not be empty. Set to 0.0.0.0/0 to match any IPv4 source address (::/0 for IPv6). |
    75  | source_port | [uint32](#uint32) |  | source_port. Matches any source port if empty. |
    76  | destination_cidr | [string](#string) |  | destination_cidr. Must not be empty. Set to 0.0.0.0/0 to match any IPv4 destination address (::/0 for IPv6). |
    77  | destination_port | [uint32](#uint32) |  | destination_port. Matches any destination port if empty. |
    78  | protocol | [Protocol](#recorder-Protocol) |  | protocol. Matches any protocol if empty. |
    79  
    80  
    81  
    82  
    83  
    84  
    85  <a name="recorder-RecordRequest"></a>
    86  
    87  ### RecordRequest
    88  
    89  
    90  
    91  | Field | Type | Label | Description |
    92  | ----- | ---- | ----- | ----------- |
    93  | start | [StartRecording](#recorder-StartRecording) |  | start starts a new recording with the given parameters. |
    94  | stop | [StopRecording](#recorder-StopRecording) |  | stop stops the running recording. |
    95  
    96  
    97  
    98  
    99  
   100  
   101  <a name="recorder-RecordResponse"></a>
   102  
   103  ### RecordResponse
   104  
   105  
   106  
   107  | Field | Type | Label | Description |
   108  | ----- | ---- | ----- | ----------- |
   109  | node_name | [string](#string) |  | name of the node where this recording is happening |
   110  | time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) |  | time at which this event was observed on the above node |
   111  | running | [RecordingRunningResponse](#recorder-RecordingRunningResponse) |  | running means that the recording is capturing packets. This is emitted in regular intervals |
   112  | stopped | [RecordingStoppedResponse](#recorder-RecordingStoppedResponse) |  | stopped means the recording has stopped |
   113  
   114  
   115  
   116  
   117  
   118  
   119  <a name="recorder-RecordingRunningResponse"></a>
   120  
   121  ### RecordingRunningResponse
   122  
   123  
   124  
   125  | Field | Type | Label | Description |
   126  | ----- | ---- | ----- | ----------- |
   127  | stats | [RecordingStatistics](#recorder-RecordingStatistics) |  | stats for the running recording |
   128  
   129  
   130  
   131  
   132  
   133  
   134  <a name="recorder-RecordingStatistics"></a>
   135  
   136  ### RecordingStatistics
   137  
   138  
   139  
   140  | Field | Type | Label | Description |
   141  | ----- | ---- | ----- | ----------- |
   142  | bytes_captured | [uint64](#uint64) |  | bytes_captured is the total amount of bytes captured in the recording |
   143  | packets_captured | [uint64](#uint64) |  | packets_captured is the total amount of packets captured the recording |
   144  | packets_lost | [uint64](#uint64) |  | packets_lost is the total amount of packets matching the filter during the recording, but never written to the sink because it was overloaded. |
   145  | bytes_lost | [uint64](#uint64) |  | bytes_lost is the total amount of bytes matching the filter during the recording, but never written to the sink because it was overloaded. |
   146  
   147  
   148  
   149  
   150  
   151  
   152  <a name="recorder-RecordingStoppedResponse"></a>
   153  
   154  ### RecordingStoppedResponse
   155  
   156  
   157  
   158  | Field | Type | Label | Description |
   159  | ----- | ---- | ----- | ----------- |
   160  | stats | [RecordingStatistics](#recorder-RecordingStatistics) |  | stats for the recording |
   161  | filesink | [FileSinkResult](#recorder-FileSinkResult) |  | filesink contains the path to the captured file |
   162  
   163  
   164  
   165  
   166  
   167  
   168  <a name="recorder-StartRecording"></a>
   169  
   170  ### StartRecording
   171  
   172  
   173  
   174  | Field | Type | Label | Description |
   175  | ----- | ---- | ----- | ----------- |
   176  | filesink | [FileSinkConfiguration](#recorder-FileSinkConfiguration) |  | filesink configures the outfile of this recording Future alternative sink configurations may be added as a backwards-compatible change by moving this field into a oneof. |
   177  | include | [Filter](#recorder-Filter) | repeated | include list for this recording. Packets matching any of the provided filters will be recorded. |
   178  | max_capture_length | [uint32](#uint32) |  | max_capture_length specifies the maximum packet length. Full packet length will be captured if absent/zero. |
   179  | stop_condition | [StopCondition](#recorder-StopCondition) |  | stop_condition defines conditions which will cause the recording to stop early after any of the stop conditions has been hit |
   180  
   181  
   182  
   183  
   184  
   185  
   186  <a name="recorder-StopCondition"></a>
   187  
   188  ### StopCondition
   189  StopCondition defines one or more conditions which cause the recording to
   190  stop after they have been hit. Stop conditions are ignored if they are
   191  absent or zero-valued. If multiple conditions are defined, the recording
   192  stops after the first one is hit.
   193  
   194  
   195  | Field | Type | Label | Description |
   196  | ----- | ---- | ----- | ----------- |
   197  | bytes_captured_count | [uint64](#uint64) |  | bytes_captured_count stops the recording after at least this many bytes have been captured. Note: The resulting file might be slightly larger due to added pcap headers. |
   198  | packets_captured_count | [uint64](#uint64) |  | packets_captured_count stops the recording after at least this many packets have been captured. |
   199  | time_elapsed | [google.protobuf.Duration](#google-protobuf-Duration) |  | time_elapsed stops the recording after this duration has elapsed. |
   200  
   201  
   202  
   203  
   204  
   205  
   206  <a name="recorder-StopRecording"></a>
   207  
   208  ### StopRecording
   209  
   210  
   211  
   212  
   213  
   214  
   215   
   216  
   217  
   218  <a name="recorder-Protocol"></a>
   219  
   220  ### Protocol
   221  Protocol is a one of the supported protocols for packet capture
   222  
   223  | Name | Number | Description |
   224  | ---- | ------ | ----------- |
   225  | PROTOCOL_ANY | 0 |  |
   226  | PROTOCOL_TCP | 6 |  |
   227  | PROTOCOL_UDP | 17 |  |
   228  | PROTOCOL_SCTP | 132 |  |
   229  
   230  
   231   
   232  
   233   
   234  
   235  
   236  <a name="recorder-Recorder"></a>
   237  
   238  ### Recorder
   239  Recorder implements the Hubble module for capturing network packets
   240  
   241  | Method Name | Request Type | Response Type | Description |
   242  | ----------- | ------------ | ------------- | ------------|
   243  | Record | [RecordRequest](#recorder-RecordRequest) stream | [RecordResponse](#recorder-RecordResponse) stream | Record can start and stop a single recording. The recording is automatically stopped if the client aborts this rpc call. |
   244  
   245   
   246  
   247  
   248  
   249  ## Scalar Value Types
   250  
   251  | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
   252  | ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
   253  | <a name="double" /> double |  | double | double | float | float64 | double | float | Float |
   254  | <a name="float" /> float |  | float | float | float | float32 | float | float | Float |
   255  | <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) |
   256  | <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 |
   257  | <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
   258  | <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
   259  | <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) |
   260  | <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 |
   261  | <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) |
   262  | <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 |
   263  | <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
   264  | <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
   265  | <a name="bool" /> bool |  | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
   266  | <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) |
   267  | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |
   268