How the DEBUGLOG Feature in Apollo Uses UDP Multicast for PS4 Debugging

The DEBUGLOG feature in Apollo streams real-time debug messages via UDP multicast to 239.255.0.100:30000 using the external dbglogger library, activated at compile-time with make DEBUGLOG=1.

The DEBUGLOG feature in the Apollo PS4 save-game tool provides developers with real-time debugging capabilities without requiring physical access to the console. By leveraging UDP multicast networking, the bucanero/apollo-ps4 repository streams diagnostic messages over the local network to a specific multicast group address. This implementation relies on compile-time flags and the external dbglogger submodule to handle socket creation and packet transmission.

Activating DEBUGLOG at Compile Time

The DEBUGLOG feature is controlled entirely at build time through the Makefile. When you compile Apollo with the DEBUGLOG=1 flag, the build system adds the APOLLO_ENABLE_LOGGING macro to the compiler flags.

In Makefile at lines 16-18:

ifeq ($(DEBUGLOG),1)
    EXTRAFLAGS += -DAPOLLO_ENABLE_LOGGING
endif

This macro acts as a gatekeeper. All debug logging code is wrapped in #ifdef APOLLO_ENABLE_LOGGING preprocessor blocks, ensuring that production builds contain zero logging overhead.

Initializing the UDP Multicast Logger

When APOLLO_ENABLE_LOGGING is defined, Apollo initializes the debug logger immediately at program startup in source/main.c. The initialization occurs at lines 64-71:

#ifdef APOLLO_ENABLE_LOGGING
    // Frame tracking info for debugging
    uint32_t lastFrameTicks  = 0;
    uint32_t startFrameTicks = 0;
    uint32_t deltaFrameTicks = 0;

    dbglogger_init();               // ← opens UDP multicast socket
#endif

The dbglogger_init() function is provided by the external dbglogger library, which Apollo includes as a Git submodule. When compiled for the PS4 target, this library automatically creates a UDP socket and configures it to send packets to the multicast group address 239.255.0.100 on port 30000. The Apollo codebase never directly references socket APIs or network addresses; the dbglogger library abstracts all transport details.

Capturing Debug Messages on Your PC

To receive the debug stream on your development machine, you must join the multicast group that Apollo publishes to. The repository documentation specifies the address and port in the README.

Use the following command with socat to capture the UDP multicast stream:

socat udp4-recv:30000,ip-add-membership=239.255.0.100:0.0.0.0 -

This command instructs socat to:

• Create a UDP receiver on port 30000
• Join the multicast group 239.255.0.100 on all available interfaces (0.0.0.0)
• Print each received packet (each debug line) to stdout in real-time

Optional File Logging Mode

In addition to UDP multicast, Apollo supports logging to a local file when the user enables the debug-log option in the settings UI. This functionality is also guarded by the APOLLO_ENABLE_LOGGING macro and appears in source/main.c at lines 662-669:

if (apollo_config.dbglog)
{
    dbglogger_init_mode(FILE_LOGGER, APOLLO_PATH "apollo.log", 0);
    notify_popup(NOTIFICATION_ICON_DEFAULT,
                 "%s\n%s", _("Debug Logging Enabled"),
                 APOLLO_PATH "apollo.log");
}

The dbglogger_init_mode() function switches the backend to file-based logging, writing all subsequent LOG() calls to the specified path on the PS4's filesystem instead of sending UDP packets.

Key Implementation Files

The DEBUGLOG feature spans several files in the repository:

• Makefile (lines 16-18): Defines the APOLLO_ENABLE_LOGGING macro when DEBUGLOG=1 is passed to make.
• source/main.c (lines 64-71, 662-669): Contains the conditional initialization of dbglogger_init() at startup and the optional file logger initialization based on user settings.
• README.md: Documents the multicast address (239.255.0.100:30000) and provides the socat command for receiving logs.
• dbglogger submodule: External library that implements the actual UDP socket creation and multicast transmission.

Summary

• Compile-time activation: Use make DEBUGLOG=1 to inject the APOLLO_ENABLE_LOGGING macro into the build.
• Automatic initialization: The dbglogger_init() function in source/main.c opens a UDP multicast socket when the macro is defined.
• Multicast transport: The external dbglogger library sends all debug messages to 239.255.0.100:30000 via UDP multicast.
• Local capture: Developers receive the stream using socat or any UDP multicast listener on the same network segment.
• Dual modes: The system supports both network multicast and local file logging via dbglogger_init_mode().

Frequently Asked Questions

How do I enable DEBUGLOG when building Apollo?

Pass the DEBUGLOG=1 flag to make when compiling the project. The Makefile will automatically add -DAPOLLO_ENABLE_LOGGING to the compiler flags, enabling all debug logging code blocks. Without this flag, the logging code is completely excluded from the binary.

What multicast address and port does Apollo use for debug logging?

Apollo transmits debug messages to the multicast group 239.255.0.100 on port 30000. This address is reserved for local multicast traffic and allows multiple development PCs on the same network segment to receive the debug stream simultaneously without unicast overhead.

Can I log to a file instead of UDP multicast?

Yes. When APOLLO_ENABLE_LOGGING is active, users can enable file logging through the Apollo settings UI. When activated, the code calls dbglogger_init_mode(FILE_LOGGER, APOLLO_PATH "apollo.log", 0), which redirects all LOG() output to the specified local file path on the PS4 filesystem instead of the network socket.

How do I view the debug stream on my computer?

Use the socat utility to join the multicast group and print packets to your terminal. Run the following command on your development machine:

socat udp4-recv:30000,ip-add-membership=239.255.0.100:0.0.0.0 -

This command binds to port 30000, joins the 239.255.0.100 multicast group on all available interfaces, and outputs each received UDP packet (representing one debug line) to stdout in real-time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}