[NETPATH-1182] Add Network Path metadata to the CNM connection payload

[tonytran-dd]

Draft for the CNM ⇒ Network Path Pivot RFC. Not for merge yet.

What

Nested NetworkPath message on Connection at field 65 (was free; next identifier bumped 65 → 66).

message NetworkPath {
  bool testEligible = 1;     // policy approved a dynamic test
  string correlationKey = 2; // identity of that test
}

First step of NETPATH-949.

Why nested

Generated as a pointer, so three states survive the wire:

State	Meaning
nil	never evaluated (Network Path off, or older Agent)
set, empty	evaluated, no test
set, populated	evaluated, test scheduled

A flat bool collapses the first two.

Verification

Built #57114 against this branch and ran the Agent locally, via the QA steps below. 20 real connections carried the field: 10 with testEligible: true plus a 32-hex key, 10 with networkPath: {}.

Three destinations produced byte-identical keys in a run a day earlier against a different system-probe, which is what the empty-nested-message and populated-message cases above look like in practice.

A locally built Agent also posts the payload for real and its flows appear in the CNM UI, so field 65 survives a live intake round trip, not only the decoder test above.

Regenerated with inv codegen.all under Go 1.24.0 to match go.mod.

QA

Follows the team's Agent Development Setup. Three terminals, all in datadog-agent.

# 1. Both branches. #527 defines the field, #57114 fills it in; neither works alone.
cd ~/go/src/github.com/DataDog/agent-payload && git checkout tony/netpath-1182-correlation-key
cd ~/go/src/github.com/DataDog/datadog-agent  && git checkout tony/netpath-1185-stamp-connections

# 2. go.mod pins agent-payload v5.0.212, which has no NetworkPath field. Point the
#    build at the local checkout so #527 compiles in without being merged.
go mod edit -replace github.com/DataDog/agent-payload/v5=$HOME/go/src/github.com/DataDog/agent-payload

# 3. Turn on the collector. Both default to false in Go and neither key is in
#    dev/dist/datadog.yaml, so append. Without the first the collector never
#    evaluates and no networkPath object appears at all; without the second every
#    connection declines, since connfilter.go excludes destinations with no DNS
#    name. The grep guard makes a rerun a no-op; appending twice breaks yaml.
grep -q '^network_path:' dev/dist/datadog.yaml || cat >> dev/dist/datadog.yaml <<'YAML'
network_path:
  connections_monitoring:
    enabled: true
  collector:
    monitor_ip_without_domain: true
YAML

#    The dev setup doc configures Network Path (traceroute), not CNM. The CNM
#    connection tracking lives in a separate system-probe module gated on this
#    key; without it `check connections` returns 404, because the endpoint it
#    calls does not exist.
grep -q '^network_config:' dev/dist/system-probe.yaml || cat >> dev/dist/system-probe.yaml <<'YAML'
network_config:
  enabled: true
YAML

# 4. Build. This copies dev/dist into bin/agent/dist, so rerun it after any config edit.
dda inv -e agent.build --build-exclude=systemd
dda inv -e system-probe.build
dda inv -e process-agent.build

Leave the socket paths in dev/dist alone. They point inside the checkout on purpose, so your build does not pick up the IT-installed Agent's config.

# 5. Terminal 1 — the agent first, or system-probe floods with connection errors.
sudo ./bin/agent/agent run -c ./bin/agent/dist

# 6. Terminal 2 — system-probe.
sudo ./bin/system-probe/system-probe run --config ./bin/agent/dist \
  --datadogcfgpath ./bin/agent/dist

# 7. Terminal 3 — traffic, then the check. It runs the CNM check once and prints the
#    payload instead of shipping it. sudo because auth_token is mode 600.
curl -s -o /dev/null https://www.datadoghq.com
sudo ./bin/process-agent/process-agent --cfgpath ./bin/agent/dist/datadog.yaml \
  --sysprobe-config ./bin/agent/dist/system-probe.yaml check connections --json > /tmp/conns.json

jq '[.connections[] | {dst: "\(.raddr.ip):\(.raddr.port)", np: .networkPath}]' /tmp/conns.json

# 8. Revert the replace. It must never ship; `git add -u` would otherwise commit
#    it. dev/dist is gitignored, so the config edits above are not reverted by
#    git and can be left in place or removed by hand.
git checkout go.mod go.sum

Expect testEligible: true plus a 32-hex key on outbound TCP, np: {} on incoming and multicast, the same key for every connection to the same destination. Rerun step 7; keys must not change.

Order

logs-backend → dd-go CNM → dd-go NPP → datadog-agent → web-ui

[Copilot]

Copilot review overview

🔵 Needs a closer look

The PR remains a draft pending human validation of the implementation plan and coordinated downstream rollout.

Review effort: Balanced
Findings: None

What changed in this PR

Adds Network Path metadata to CNM connections, enabling downstream consumers to distinguish evaluation states and correlate flows with Network Path events.

Changes:

• Adds field 65 with test eligibility and a correlation key.
• Preserves absent versus present-empty metadata.
• Regenerates Go message bindings and streaming builders.

File	Description
proto/​process/​connections.proto	Defines Network Path metadata and advances the field marker.
process/​connections.proto_builder.go	Adds builders for the new metadata.
process/​connections.pb.go	Adds generated types, descriptors, and serialization support.

Files not reviewed (1)

• process/connections.pb.go: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The PR explicitly remains a not-for-merge draft pending human sign-off on the cross-service contract and coordinated rollout.

Review effort: Balanced
Findings: None

Files not reviewed (1)

• process/connections.pb.go: Generated file