Add tiered debug logging to NUClearNet

Introduce Log.hpp/Log.cpp with off-through-trace levels and instrument
Discovery and NUClearNet for handshake, wire, and lifecycle events.
Windows WSABUF/sendmsg and socket rebind behaviour are unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TrentHouliston

src/nuclearnet/Discovery.cpp

@@ -29,15 +29,27 @@
 #include <map>
 #include <mutex>
 #include <set>
+#include <sstream>
 #include <string>
 #include <utility>
 #include <vector>
 
+#include "Log.hpp"
 #include "wire_protocol.hpp"
 
     namespace NUClear {
     namespace network {
 
+    namespace {
+
+        std::string connect_flags_str(uint8_t flags) {
+            std::ostringstream msg;
+            msg << "SYN=" << ((flags & SYN) != 0 ? '1' : '0') << " ACK=" << ((flags & CON_ACK) != 0 ? '1' : '0');
+            return msg.str();
+        }
+
+    }  // namespace
+
         Discovery::Discovery(std::chrono::steady_clock::duration peer_timeout) : peer_timeout(peer_timeout) {}
 
         void Discovery::set_join_callback(JoinCallback cb) {
@@ -109,6 +121,10 @@
 
             // Minimum size: header(5) + name_length(2) + num_subscriptions(2) = 9
             if (length < sizeof(PacketHeader) + sizeof(uint16_t) + sizeof(uint16_t)) {
+                if (should_log(LogLevel::Warn)) {
+                    log(LogLevel::Warn, "discovery",
+                        "short ANNOUNCE from " + sock_str(source) + " len=" + std::to_string(length));
+                }
                 return announce_result;
             }
 
@@ -168,6 +184,10 @@
                     // New peer — record with announce_heard = true and initiate handshake
                     announce_result.is_new          = true;
                     announce_result.response_flags  = SYN;
+                    if (should_log(LogLevel::Debug)) {
+                        log(LogLevel::Debug, "discovery",
+                            "new peer from announce name=" + name + " " + sock_str(source));
+                    }
                     PeerInfo info;
                     info.name            = name;
                     info.address         = source;
@@ -190,6 +210,10 @@
                     if (peer.subscriptions != subscriptions) {
                         peer.subscriptions = std::move(subscriptions);
                         subs_changed       = true;
+                        if (should_log(LogLevel::Debug)) {
+                            log(LogLevel::Debug, "discovery",
+                                "subscriptions changed for " + peer.name + " " + sock_str(source));
+                        }
                     }
 
                     // Mark announce as heard (may trigger connection if data was already confirmed)
@@ -221,6 +245,10 @@
 
             // Fire callbacks outside the lock
             if (fire_join && join_callback) {
+                if (should_log(LogLevel::Debug)) {
+                    log(LogLevel::Debug, "discovery",
+                        "join (announce path) name=" + join_info.name + " " + sock_str(join_info.address));
+                }
                 join_callback(join_info);
             }
             if (subs_changed && subscription_change_callback) {
@@ -259,6 +287,10 @@
 
             // Only fire leave callback for peers that completed the handshake
             if (was_connected && leave_callback) {
+                if (should_log(LogLevel::Debug)) {
+                    log(LogLevel::Debug, "discovery",
+                        "leave (packet) name=" + removed.name + " " + sock_str(source));
+                }
                 leave_callback(removed);
             }
         }
@@ -288,6 +320,7 @@
 
                 const bool has_syn = (flags & SYN) != 0;
                 const bool has_ack = (flags & CON_ACK) != 0;
+                const auto old_state = peer.handshake;
 
                 switch (peer.handshake) {
                     case HandshakeState::IDLE:
@@ -350,10 +383,25 @@
                         }
                         break;
                 }
+
+                if (should_log(LogLevel::Debug) && peer.handshake != old_state) {
+                    std::ostringstream msg;
+                    msg << "handshake " << sock_str(source);
+                    if (!peer.name.empty()) {
+                        msg << " name=" << peer.name;
+                    }
+                    msg << ' ' << handshake_str(old_state) << " -> " << handshake_str(peer.handshake) << " ("
+                        << connect_flags_str(flags) << ')';
+                    log(LogLevel::Debug, "discovery", msg.str());
+                }
             }
 
             // Fire join callback outside the lock
             if (fire_join && join_callback) {
+                if (should_log(LogLevel::Debug)) {
+                    log(LogLevel::Debug, "discovery",
+                        "join (connect path) name=" + info.name + " " + sock_str(info.address));
+                }
                 join_callback(info);
             }
 
@@ -365,6 +413,10 @@
             auto it = peers.find(address);
             if (it != peers.end() && it->second.handshake == HandshakeState::IDLE) {
                 it->second.handshake = HandshakeState::SYN_SENT;
+                if (should_log(LogLevel::Debug)) {
+                    log(LogLevel::Debug, "discovery",
+                        "handshake " + sock_str(address) + " IDLE -> SYN_SENT (sent SYN)");
+                }
             }
         }
 
@@ -406,6 +458,10 @@
             // Fire leave callbacks outside the lock
             if (leave_callback) {
                 for (const auto& peer : removed) {
+                    if (should_log(LogLevel::Info)) {
+                        log(LogLevel::Info, "discovery",
+                            "peer timeout name=" + peer.name + " " + sock_str(peer.address));
+                    }
                     leave_callback(peer);
                 }
             }

src/nuclearnet/Log.cpp

@@ -0,0 +1,85 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 NUClear Contributors
+ *
+ * This file is part of the NUClear codebase.
+ * See https://github.com/Fastcode/NUClear for further info.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#include "Log.hpp"
+
+#include <cstdio>
+#include <iostream>
+
+namespace NUClear {
+namespace network {
+
+namespace {
+
+    std::atomic<int> g_log_level{static_cast<int>(LogLevel::Off)};
+
+    const char* level_name(LogLevel level) {
+        switch (level) {
+            case LogLevel::Error: return "error";
+            case LogLevel::Warn: return "warn";
+            case LogLevel::Info: return "info";
+            case LogLevel::Debug: return "debug";
+            case LogLevel::Trace: return "trace";
+            default: return "off";
+        }
+    }
+
+}  // namespace
+
+    void set_log_level(LogLevel level) {
+        g_log_level.store(static_cast<int>(level), std::memory_order_relaxed);
+    }
+
+    LogLevel get_log_level() {
+        return static_cast<LogLevel>(g_log_level.load(std::memory_order_relaxed));
+    }
+
+    void log(LogLevel level, const char* component, const std::string& message) {
+        if (!should_log(level)) {
+            return;
+        }
+        std::cerr << "[NUClearNet:" << component << "] " << level_name(level) << " " << message << std::endl;
+    }
+
+    std::string hash_hex(uint64_t hash) {
+        char buf[19];
+        std::snprintf(buf, sizeof(buf), "0x%016llx", static_cast<unsigned long long>(hash));
+        return buf;
+    }
+
+    std::string sock_str(const util::network::sock_t& address) {
+        const auto addr = address.address();
+        return addr.first + ":" + std::to_string(addr.second);
+    }
+
+    const char* handshake_str(HandshakeState state) {
+        switch (state) {
+            case HandshakeState::IDLE: return "IDLE";
+            case HandshakeState::SYN_SENT: return "SYN_SENT";
+            case HandshakeState::SYN_RECEIVED: return "SYN_RECEIVED";
+            case HandshakeState::CONFIRMED: return "CONFIRMED";
+        }
+        return "UNKNOWN";
+    }
+
+}  // namespace network
+}  // namespace NUClear

src/nuclearnet/Log.hpp

@@ -0,0 +1,61 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2025 NUClear Contributors
+ *
+ * This file is part of the NUClear codebase.
+ * See https://github.com/Fastcode/NUClear for further info.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef NUCLEAR_NETWORK_LOG_HPP
+#define NUCLEAR_NETWORK_LOG_HPP
+
+#include <atomic>
+#include <cstdint>
+#include <string>
+
+#include "../util/network/sock_t.hpp"
+#include "Discovery.hpp"
+
+namespace NUClear {
+namespace network {
+
+    enum class LogLevel : int {
+        Off   = 0,
+        Error = 1,
+        Warn  = 2,
+        Info  = 3,
+        Debug = 4,
+        Trace = 5,
+    };
+
+    void set_log_level(LogLevel level);
+    LogLevel get_log_level();
+
+    inline bool should_log(LogLevel level) {
+        return static_cast<int>(level) <= static_cast<int>(get_log_level());
+    }
+
+    void log(LogLevel level, const char* component, const std::string& message);
+
+    std::string hash_hex(uint64_t hash);
+    std::string sock_str(const util::network::sock_t& address);
+    const char* handshake_str(HandshakeState state);
+
+}  // namespace network
+}  // namespace NUClear
+
+#endif  // NUCLEAR_NETWORK_LOG_HPP