From f0d8d97f2bed7b314eb541167050cdc7fd6f4fb4 Mon Sep 17 00:00:00 2001 From: cccs-jc <56140112+cccs-jc@users.noreply.github.com> Date: Wed, 31 Mar 2021 14:12:11 -0400 Subject: [PATCH] docs: Documenting how to debug Flask app (#13813) Co-authored-by: cccs-jc --- CONTRIBUTING.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c80b7ae1f6e8..ff5d5b31ab9f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -802,6 +802,130 @@ npm install npm run cypress open ``` +### Debugging Server App + +Follow these instructions to debug the Flask app running inside a docker container. + +First add the following to the ./docker-compose.yaml file + +```diff +superset: + env_file: docker/.env + image: *superset-image + container_name: superset_app + command: ["/app/docker/docker-bootstrap.sh", "app"] + restart: unless-stopped ++ cap_add: ++ - SYS_PTRACE + ports: + - 8088:8088 ++ - 5678:5678 + user: "root" + depends_on: *superset-depends-on + volumes: *superset-volumes + environment: + CYPRESS_CONFIG: "${CYPRESS_CONFIG}" +``` + +Start Superset as usual +```bash +docker-compose up +``` + +Install the required libraries and packages to the docker container + +Enter the superset_app container +```bash +docker exec -it superset_app /bin/bash +root@39ce8cf9d6ab:/app# +``` + +Run the following commands inside the container +```bash +apt update +apt install -y gdb +apt install -y net-tools +pip install debugpy +``` + +Find the PID for the Flask process. Make sure to use the first PID. The Flask app will re-spawn a sub-process everytime you change any of the python code. So it's important to use the first PID. + +```bash +ps -ef + +UID PID PPID C STIME TTY TIME CMD +root 1 0 0 14:09 ? 00:00:00 bash /app/docker/docker-bootstrap.sh app +root 6 1 4 14:09 ? 00:00:04 /usr/local/bin/python /usr/bin/flask run -p 8088 --with-threads --reload --debugger --host=0.0.0.0 +root 10 6 7 14:09 ? 00:00:07 /usr/local/bin/python /usr/bin/flask run -p 8088 --with-threads --reload --debugger --host=0.0.0.0 +``` + +Inject debugpy into the running Flask process. In this case PID 6. +```bash +python3 -m debugpy --listen 0.0.0.0:5678 --pid 6 +``` + +Verify that debugpy is listening on port 5678 +```bash +netstat -tunap + +Active Internet connections (servers and established) +Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name +tcp 0 0 0.0.0.0:5678 0.0.0.0:* LISTEN 462/python +tcp 0 0 0.0.0.0:8088 0.0.0.0:* LISTEN 6/python +``` + +You are now ready to attach a debugger to the process. Using VSCode you can configure a launch configuration file .vscode/launch.json like so. +``` +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Attach to Superset App in Docker Container", + "type": "python", + "request": "attach", + "connect": { + "host": "127.0.0.1", + "port": 5678 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder}", + "remoteRoot": "/app" + } + ] + }, + ] +} +``` + +VSCode will not stop on breakpoints right away. We've attached to PID 6 however it does not yet know of any sub-processes. In order to "wakeup" the debugger you need to modify a python file. This will trigger Flask to reload the code and create a new sub-process. This new sub-process will be detected by VSCode and breakpoints will be activated. + + +### Debugging Server App in Kubernetes Environment + +To debug Flask running in POD inside kubernetes cluster. You'll need to make sure the pod runs as root and is granted the SYS_TRACE capability.These settings should not be used in production environments. + +``` + securityContext: + capabilities: + add: ["SYS_PTRACE"] +``` + +See (set capabilities for a container)[https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-capabilities-for-a-container] for more details. + +Once the pod is running as root and has the SYS_PTRACE capability it will be able to debug the Flask app. + +You can follow the same instructions as in the docker-compose. Enter the pod and install the required library and packages; gdb, netstat and debugpy. + +Often in a kuernetes environment nodes are not addressable from ouside the cluster. VSCode will thus be unable to remotely connect to port 5678 on a kubernetes node. In order to do this you need to create a tunnel that port forwards 5678 to your local machine. + +``` +kubectl port-forward pod/superset- 5678:5678 +``` + +You can now launch your VSCode debugger with the same config as above. VSCode will connect to to 127.0.0.1:5678 which is forwarded by kubectl to your remote kubernetes POD. + + ### Storybook Superset includes a [Storybook](https://storybook.js.org/) to preview the layout/styling of various Superset components, and variations thereof. To open and view the Storybook: