Debugging - WunderGraph

Design Philosophy

When designing the router plugin system, we prioritized providing an excellent developer experience (DX). One of the key reasons we chose a native plugin approach over a scripting solution was the superior debugging capabilities and IDE support. Plugins allow developers to:

• Use full-featured debugging tools
• Benefit from IDE features like code completion and type checking
• Leverage existing Go tooling and workflows
• Get immediate feedback during development

These advantages significantly improve the development process compared to scripting approaches, which often lack comprehensive debugging support and IDE integration.

Required Tools

The cli command will automatically check for and install the necessary toolchain (like protoc, protoc-gen-go, etc.) when required tools can’t be found in the right version on your system. However, for the best experience, we recommend installing the tools manually. The following table shows the current versions and download links for the required tools:

Building for Debug

To build your plugin with debug information, use the --debug flag with the build command:

wgc router plugin build --debug ./my-plugin

Based on the language you select the process for debugging is a bit different.

• Go
• TypeScript

This will compile the plugin with debug symbols and without optimizations, making it suitable for debugging.

Debugging with Delve

Delve is a debugger for Go programs. To debug your plugin with Delve:

1. First, find the process ID (PID) of your router that’s running the plugin:

# The process name follows the pattern: <os>_<arch>
# For example: darwin_arm64, linux_amd64, etc.
ps aux | grep "$(go env GOOS)_$(go env GOARCH)"

2. Attach Delve to the process:

dlv attach <PID>

3. Set breakpoints in your plugin code:

(dlv) break src/main.go:42

4. Use Delve commands to debug:

• continue (or c): Continue execution
• next (or n): Step over
• step (or s): Step into
• print (or p): Print variable values
• vars: List local variables

Debugging with GoLand

To debug your plugin in GoLand:

1. Build the plugin with debug mode enabled
2. In GoLand, go to Run → Attach to Process
3. Find and select the router process running your plugin
4. Set breakpoints in your plugin code by clicking the gutter
5. Use the debug toolbar to:
   • Step Over (F8)
   • Step Into (F7)
   • Resume Program (F9)
   • View variables in the Debug tool window

Debugging with VS Code

To debug your plugin in VS Code:

1. Install the Go extension for VS Code
2. Create a .vscode/launch.json file with this configuration:

{
    "version": "0.2.0",
    "configurations": [\
        {\
            "name": "Attach to Router Process",\
            "type": "go",\
            "request": "attach",\
            "mode": "local",\
            "processId": "${command:pickProcess}"\
        }\
    ]
}

3. Start debugging:
   • Press F5 or click Run → Start Debugging
   • Select the router process when prompted (the process name follows the pattern: os_arch)
   • Set breakpoints by clicking the gutter
   • Use the debug toolbar or keyboard shortcuts:
     • F5: Continue
     • F10: Step Over
     • F11: Step Into

Debugging with debug.bun.sh

When the plugin is started in debug mode, it will create a link that can be accessed to debug your plugin, all in your browser. In order to find the generated URL, you should access plugin_stderr.log, which should be inside the plugin/bin folder after startup. What you are looking for is text similar to

Inspect in browser:
  https://debug.bun.sh/#localhost:6499/ai8omlnz82t

All you need to do now is simply go to the above URL and you can start debugging. You can find more info on the Bun web debugger here.

Tips for Effective Debugging

1. Log Points: Consider adding log points instead of breakpoints for less intrusive debugging
2. Conditional Breakpoints: Use conditional breakpoints to break only when specific conditions are met
3. Watch Expressions: Set watch expressions to monitor variable values during execution

Debugging in production environments is not recommended as it can impact performance. Always use debug builds in development environments only.