docs: add ignite chain debug documentation and tutorial (#3272)

* docs: add `ignite chain debug` documentation and tutorial

* chore: typos and syntax corrections

Co-authored-by: Alex Johnson <[email protected]>

* chore: documentation improvements

Co-authored-by: Alex Johnson <[email protected]>

docs/docs/kb/13-debug.md

@@ -0,0 +1,204 @@
+---
+sidebar_position: 13
+description: Blockchain Debug
+---
+
+# Blockchain Debug
+
+Ignite chain debug command can help you to find issues during development.
+It uses [Delve](https://github.com/go-delve/delve) debugger which enables you to
+interact with your blockchain app by controlling the execution of the process,
+evaluating variables, and providing information of thread / goroutine state, CPU
+register state and more.
+
+## Debug Command
+
+The debug command requires that the blockchain app binary is build with
+debugging support by removing optimizations and inlining.
+A debug binary is built by default by the `ignite chain serve` command or can
+optionally be created using the `--debug` flag when running `ignite chain init`
+or `ignite chain build` sub-commands.
+
+To start a debugging session in the terminal run:
+
+```bash
+ignite chain debug
+```
+
+The command runs your blockchan app in the background, attaches to it and
+launches a terminal debugger shell:
+
+```
+Type 'help' for list of commands.
+(dlv)
+```
+
+At this point the blockchain app blocks execution so you can set one or more
+breakpoints before continuing execution.
+
+Use the [break](https://github.com/go-delve/delve/blob/master/Documentation/cli/README.md#break)
+(alias `b`) command to set any number of breakpoints using, for example the
+`<filename>:<line>` notation:
+
+```
+(dlv) break x/hello/client/cli/query_say_hello.go:14
+```
+
+This command adds a breakpoint to the `x/hello/client/cli/query_say_hello.go`
+file at line 14.
+
+Once all breakpoints are setted resume blockchain execution using the
+[continue](https://github.com/go-delve/delve/blob/master/Documentation/cli/README.md#continue)
+(alias `c`) command:
+
+```
+(dlv) continue
+```
+
+The debugger will launch the shell and stop blockchain execution again when a
+breakpoint is triggered.
+
+Within the debugger shell use the `quit` (alias `q`) or `exit` commands to stop
+the blockchain app and exit the debugger.
+
+## Debug Server
+
+A debug server can optionally be started in cases where the default terminal
+client is not desirable. When the server starts it first runs the blockchain
+app, attaches to it and finally waits for a client connection. The default
+server address is *tcp://127.0.0.1:30500* and it accepts both JSON-RPC or DAP
+client connections.
+
+To start a debug server use the following flag:
+
+```bash
+ignite chain debug --server
+```
+
+To start a debug server with a custom address use the following flags:
+
+```bash
+ignite chain debug --server --server-address 127.0.0.1:30500
+```
+
+The debug server stops automatically when the client connection is closed.
+
+## Debugging Clients
+
+### Gdlv: Multiplatform Delve UI
+
+[Gdlv](https://github.com/aarzilli/gdlv) is a graphical frontend to Delve for
+Linux, Windows and macOS.
+
+Using it as debugging client is straightforward as it doesn't require any
+configuration. Once the debug server is running and listening for client
+requests connect to it by running:
+
+```bash
+gdlv connect 127.0.0.1:30500
+```
+
+Setting breakpoints and continuing execution is done in the same way as Delve,
+by using the `break` and `continue` commands.
+
+### Visual Studio Code
+
+Using [Visual Studio Code](https://code.visualstudio.com/) as debugging client
+requires an initial configuration to allow it to connect to the debug server.
+
+Make sure that the [Go](https://code.visualstudio.com/docs/languages/go)
+extension is installed.
+
+VS Code debugging is configured using the `launch.json` file which is usually
+located inside the `.vscode` folder in your workspace.
+
+You can use the following launch configuration to set up VS Code as debugging 
+client:
+
+```json title=launch.json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Connect to Debug Server",
+            "type": "go",
+            "request": "attach",
+            "mode": "remote",
+            "remotePath": "${workspaceFolder}",
+            "port": 30500,
+            "host": "127.0.0.1"
+        }
+    ]
+}
+```
+
+Alternatively it's possible to create a custom `launch.json` file from the "Run
+and Debug" panel. When prompted choose the Go debugger option labeled "Go: 
+Connect to Server" and enter the debug host address and then the port number.
+
+## Example: Debugging a Blockchain App
+
+In this short example we will be using Ignite CLI to create a new blockchain and
+a query to be able to trigger a debugging breakpoint when the query is called.
+
+To create a new blockchain and a query run:
+
+```bash
+ignite scaffold chain hello
+ignite scaffold query say-hello name --response name
+```
+
+The next step initializes the blockchain's data directory and compiles a debug
+binary:
+
+```bash
+ignite chain init --debug
+```
+
+Once the initialization finishes launch the debugger shell:
+
+```bash
+ignite chain debug
+```
+
+Within the debugger shell create a breakpoint that will be triggered when the
+`SayHello` function is called and then continue execution:
+
+```
+(dlv) break x/hello/keeper/query_say_hello.go:12
+(dlv) continue
+```
+
+From a different terminal use the `hellod` binary to call the query:
+
+```bash
+hellod query hello say-hello bob
+```
+
+A debugger shell will be launched when the breakpoint is triggered:
+
+```go
+     7:		"google.golang.org/grpc/codes"
+     8:		"google.golang.org/grpc/status"
+     9:		"hello/x/hello/types"
+    10:	)
+    11:
+=>  12:	func (k Keeper) SayHello(goCtx context.Context, req *types.QuerySayHelloRequest) (*types.QuerySayHelloResponse, error) {
+    13:		if req == nil {
+    14:			return nil, status.Error(codes.InvalidArgument, "invalid request")
+    15:		}
+    16:
+    17:		ctx := sdk.UnwrapSDKContext(goCtx)
+```
+
+From then on you can use Delve commands like `next` (alias `n`) or `print`
+(alias `p`) to control execution and print values. For example, to print the
+*name* argument value use the `print` command followed by "req.Name":
+
+```
+(dlv) print req.Name
+"bob"
+```
+
+Finally use `quit` (alias `q`) to stop the blockchain app and finish the
+debugging session.