[mq] working branch - merge bdcf43c on top of master at 4561479

{"baseBranch":"master","baseCommit":"4561479b65d031be2fbec97acb65224faeb82480","createdAt":"2024-09-11T14:13:47.291261Z","headSha":"bdcf43c5a49aedda96a017a3e84ec1494aef78cc","id":"3730d343-5d81-40f2-92b5-3bffaf2e7a18","priority":"200","pullRequestNumber":"341","queuedAt":"2024-09-11T15:13:38.126799Z","status":"STATUS_QUEUED"}

proto/process/connections.proto

@@ -11,8 +11,12 @@ message CollectorConnections {
   // Please update when adding fields
   // next identifier:  45
 
+  // the detected hostname for the agent that collected these connections
   string hostName = 2;
+
+  // this "ID" of the network. This is generally set to VPC ID in the major clouds.
   string networkId = 12;
+
   repeated Connection connections = 3;
 
   // Message batching metadata
@@ -64,8 +68,13 @@ message CollectorConnections {
   // Prebuilt EBPF assets in use
   repeated string PrebuiltEBPFAssets = 44;
 
+  // the machine-local routes used for all connections in this payload. At the time of writing, this
+  // captures the subnet of the interface used to send traffic out of machine. This is also AWS only at the time
+  // of writing.
+  // see Connection#routeIdx
   repeated Route routes = 31;
 
+  // the next l3 route for all connections in this payload, AWS only.
   repeated RouteMetadata routeMetadata = 34; // backend use only
 
   AgentConfiguration agentConfiguration = 35;
@@ -93,6 +102,7 @@ message CollectorConnections {
   map<string, Host> resolvedHostsByName = 40; // Post-resolution field
 }
 
+// Connections is only used to communicate between the process agent and system-probe.
 message Connections {
   repeated Connection conns = 1;
   map<string, DNSEntry> dns  = 2;
@@ -312,6 +322,9 @@ message AgentConfiguration {
 }
 
 
+// Route refers to a route out of a host (think `ip route get`).
+// this is used primarily in AWS where we discover the subnet a
+// that a connection was associated with
 message Route {
   Subnet subnet = 1;
 }
@@ -320,10 +333,16 @@ message Subnet {
   string alias = 1;
 }
 
+
+// RouteMetadata 
 message RouteMetadata {
   string alias = 1;
+
+  // the tags for the inferred route target (see Connection#routeTargetIdx)
+  // whenever this type is encoded on the wire, use tagsIndex and tagsModified -- not tags.
   int32 tagIndex = 2;
   int64 tagsModified = 3;
+
   repeated string tags = 4; // Used only on the backend
 }
 
@@ -339,7 +358,18 @@ message Addr {
 
   string ip = 2;
   int32  port = 3;
-  string containerId = 5; // post-resolution field
+
+  // the containerID associated with the addr. This value can be used to look up a value in
+  // CollectorConnections#resolvedResources.
+  //
+  // Despite the name, this can be either a containerID or a cloud loadbalancer.
+  //
+  // this will usually be added during resolution, but if the container is on the same host
+  // where the connection was collected this will be set by the agent
+  string containerId = 5;
+
+  // the host associated with the addr. This value can be used to look up a value in
+  // CollectorConnections#resolvedHostsByName.
   string hostName = 7; // post-resolution field
 }