Attach to running Go processes with the debugger

Last modified: 19 March 2022

In GoLand, you can attach the debugger to a running Go process on a local machine, on a remote machine, or in the Docker container.

Attach to a process on a local machine

You can debug an application that you launched from the command line. In this case, the application runs outside the IDE but on the same local machine. To debug the application, you need to open the project in the IDE and attach the debugger to the running process.

For example purposes, you can use the following Go code at github.com.

Step 1. Install the gops package

  • Open the Terminal tool window (View | Tool Windows | Terminal) and run the following command: 

    go get -t github.com/google/gops/

  • Click Run | Attach to Process (Ctrl+Alt+F5). In the notification window, click the Invoke 'go get gops' link.

    Install the gops package

Step 2. Build and run the application

  1. Open the Terminal tool window (View | Tool Windows | Terminal) and run the following command depending on your Go version:

    • Go 1.10 and later: 

      go build -gcflags="all=-N -l" -o myApp

    • Go 1.9 and earlier: 

      go build -gcflags="-N -l" -o myApp

    This command compiles the myApp executable and disables compiler optimizations and inlining.

  2. Run the compiled executable (for example, ./myApp).

    Build the application with gcflags flags

note

Do not use -ldflags="all=-w" or -ldflags="-w" flags. These flags are incompatible with debugging the application because they strip out the necessary DWARF information that is required by Delve.

note

Symbolic links or symlinks are incompatible with debugging because of incompatibility between the Go toolchain, Delve, and GoLand.

Step 3. Attach to and debug the running process

  1. Click the gutter near the line of code to place the breakpoint. For example, in the provided code example, put the breakpoint on the line 23 (message := fmt.Sprintf("Hello %s!", r.UserAgent())). Read more about breakpoints in Breakpoints.

  2. Click Run | Attach to ProcessCtrl+Alt+F5.

  3. In the Attach with Debugger To window, select your application process and press Enter.

  4. Trigger the event at the breakpoint in your application. If you used the provided code example, open the http://localhost:8080/ link in a browser.

    https://resources.jetbrains.com/help/img/idea/2021.3/go_attach_to_the_running_process.png
    Gif

Attach to a process on a remote machine

You can connect to a remote computer (a host) and attach the debugger to the Go process that runs on the host. The remote debugger (Delve) must be running on the remote computer.

note

Compile Delve with the same Go version, host and target as your application because there might be slight differences between the various operating systems, which could cause the debugging session not to work as expected.

Step 1. Build the application on the host machine

  1. If you use the $GOPATH approach, ensure that the project is compiled with the same relative path to $GOPATH on host and client machines. For example, if code of your application on the host is in $GOPATH/src/debuggingTutorial/. Code on the client must be in the same directory ($GOPATH/src/debuggingTutorial/).

  2. Open the Terminal tool window (View | Tool Windows | Terminal) and run the following command depending on your Go version:

    • Go 1.10 and later: 

      go build -gcflags="all=-N -l" -o myApp

    • Go 1.9 and earlier: 

      go build -gcflags="-N -l" -o myApp

    This command compiles the myApp executable and disables compiler optimizations and inlining.

    Build the application with gcflags flags for remote debugging

Step 2. Run Delve on the host machine

  • You have two options to launch the debugger on the host machine:

    • The debugger runs the process for you. If you use a firewall, expose the port that is used in the configuration (for example, 2345). You can use any port number that is not occupied. myApp is the name of the executable that was built on Step 1.

      dlv --listen=:2345 --headless=true --api-version=2 exec ./myApp

      If you need to pass arguments to the binary as-is, add the double dash sign (--) to the previous command and then necessary options (for example, -- --config=/path/to/config/file).

    • You run the process, and the debugger attaches to the running process. <PID> is the process identifier of your application. You can get the process identifier by using the Attach to Process command.

      run dlv --listen=:2345 --headless=true --api-version=2 attach <PID>
    Run Delve on the host machine

Step 3. Create the Go Remote run/debug configuration on the client computer

  1. Click Edit | Run Configurations. Alternatively, click the list of run/debug configurations on the toolbar and select Edit Configurations.

  2. In the Run/Debug Configurations dialog, click the Add button (the Add button) and select Go Remote.

  3. In the Host field, type the host IP address (for example, 192.168.1.33).

  4. In the Port field, type the debugger port that you configured on Step 2 (for example, 2345).

  5. Click OK.

    https://resources.jetbrains.com/help/img/idea/2021.3/go_create_the_remote_run_debug_configuration.png
    Gif

Step 4. Start the debugging process on the client computer

  1. Click the gutter near the line of code to place the breakpoint. For example, in the provided code example, put the breakpoint on the line 23 (message := fmt.Sprintf("Hello %s!", r.UserAgent())). Read more about breakpoints in Breakpoints.

  2. From the list of run/debug configurations on the toolbar, select the created Go Remote configuration and click the Debug <configuration_name> button (the Debug button). Alternatively, press Alt+Shift+F9 and select the created Go Remote configuration.

  3. Trigger the event at the breakpoint in your application. If you used the provided code example, open the http://<host_address>:8080/ link in a browser.

    https://resources.jetbrains.com/help/img/idea/2021.3/go_start_the_debugging_process_on_the_client_computer.png
    Gif

Attach to a process in the Docker container

You can attach the debugger to a Go process that runs in a Docker container. For more information about Docker, see Docker.

For example purposes, you can use the following Dockerfile for this Go application. Save Dockerfile and main.go in $GOPATH/src/debuggingTutorial. Note that Dockerfile uses the debuggingTutorial directory. If you use a different directory for the project, change the directory name in the Dockerfile.

Step 1. Create a Dockerfile configuration

  1. Click Edit | Run Configurations. Alternatively, click the list of run/debug configurations on the toolbar and select Edit Configurations.

  2. In the Run/Debug Configurations dialog, click the Add button (the Add button) and select Docker | Dockerfile.

  3. In the Dockerfile field, click the Browse icon (the Browse icon) and navigate to Dockerfile in the file browser. If you use the example from this section, navigate to this Dockerfile.

  4. In the Container name field, type the container name (for example, debugging-tutorial)

  5. In the Bind ports field, click the Browse icon (the Browse icon). Click the Add button (the Add button). In the Host port column, type 8080. Click the Container port column, type 8080. Also, add the same binding for the port 40000.

    Bind ports

  6. In the Run options field, specify command-line options for Docker. For the provided example in Dockerfile, disable the security profile and add the SYS_PTRACE Linux capability.

    --security-opt="apparmor=unconfined" --cap-add=SYS_PTRACE

  7. Click OK.

    Create a Dockerfile configuration

Step 2. Run the Dockerfile configuration

Step 3. Create the Go Remote run/debug configuration

  1. Click Edit | Run Configurations. Alternatively, click the list of run/debug configurations on the toolbar and select Edit Configurations.

  2. In the Run/Debug Configurations dialog, click the Add button (the Add button) and select Go Remote.

  3. In the Host field, type the host IP address (for example, localhost).

  4. In the Port field, type the debugger port that you configured. In the provided example, it is 40000.

  5. Click OK.

    https://resources.jetbrains.com/help/img/idea/2021.3/go_create_the_remote_run_debug_configuration_for_docker.png
    Gif

Step 4. Start the debugging process

  1. In the Services tool window (View | Tool Windows | Services), expand Docker | Containers. Ensure that the created container is running and listens to the preconfigured debugger port.

  2. Click the gutter near the line of code to place the breakpoint. For example, in the provided code example, put the breakpoint on the line 23 (message := fmt.Sprintf("Hello %s!", r.UserAgent())). Read more about breakpoints in Breakpoints.

  3. From the list of run/debug configurations on the toolbar, select the created Go Remote configuration and click the Debug <configuration_name> button (the Debug button). Alternatively, press Alt+Shift+F9, select the created Go Remote configuration.

  4. Trigger the event at the breakpoint in your application. If you used the provided code example, open the http://localhost:8080/ link in a browser.

    https://resources.jetbrains.com/help/img/idea/2021.3/go_start_the_debugging_process_for_docker.png
    Gif

Productivity tips

Terminate the remote process

  • You can press Ctrl+F2 to terminate the remote process during the remote debugging session. Note that you cannot reattach to the process when you terminated it.

    https://resources.jetbrains.com/help/img/idea/2021.3/go_terminate_the_remote_process.png
    Gif