Project: Consul (Orchestration & Management / Service Mesh)
File: debugging.md

- - - Remote debugging integration tests allows you to attach your debugger to the consul container and debug go code running on that container. The `dev-docker-dbg` Make target will build consul docker container that has the following: installed. a port exposed on the container that allows a debugger from your development environment to connect and attach to the consul process and debug it remotely. logs out the host and port information so that you have the information needed to connect to the port. The integration tests have been modified to expose the `--debug` flag that will switch the test from using a `consul:local` image that can be built using `make dev-docker` to using the `consul-dbg:local` image that was built from `make dev-docker-dbg`. The test is run in debug mode with a breakpoint set to just after the cluster is created and you can retrieve the port information. From there, you can set up a remote debugging session that connects to this port. To run/debug integration tests locally, the following tools are required on your machine: Install (the version should match that of our CI config's Go image). Install . Install required to run tests locally. Build a consul image with dlv installed and a port exposed that the debugger can attach to. ``` make dev-docker-dbg ``` Build a consul-envoy container image from the consul root directory that is required for testing but not for debugging. ``` docker build -t consul-envoy:target-version --build-arg CONSULIMAGE=consul:local --build-arg ENVOYVERSION=1.24.6 -f ./test/integration/consul-container/assets/Dockerfile-consul-envoy ./test/integration/consul-container/assets ``` (For additional information, see .) Create the configuration for debugging the test. (You may have to debug the test once so GoLand creates the configuration for you.) Go to `Run > Edit Configurations` and select the appropriate configuration. Add `--debug` to `Program arguments` and click OK. <img src="./util/testdebugconfiguration.png" alt="isolated" width="550"/> (This is required every time a test is debugged.) Put a breakpoint in the test that you are running right after the cluster has been created. This should be on the line after the call to `topology.NewCluster()`. Debug the test and wait for the debug session to stop on the breakpoint in the test. In the Debug window, search for `debug info` on the Console tab and note the host and port. <img src="./util/testdebuginfo.png" alt="isolated" width="550"/> Go to `Run > Edit Configurations` and add a `Go Remote` configuration with the host and port that your test has exposed. Click OK. <img src="./util/testdebugremote_configuration.png" alt="isolated" width="550"/> Debug the configuration that you just created. Verify that it shows as connected in the `Debugger` of this configuration in the `Debug` window. <img src="./util/testdebugremote_connected.png" alt="isolated" width="550"/> Set an appropriate breakpoint in the backend code of the endpoint that your test will call and that you wish to debug. Go to the test debugging tab for the integration test in the `Debug` window and `Resume Program`. <img src="./util/testdebugresume_program.png" alt="isolated" width="350"/> The remote debugging session should stop on the breakpoint, and you can freely debug the code path. <img src="./util/testdebugbreakpoint_hit.png" alt="isolated" width="550"/> (For additional information, see .)