From 153ce69c66c488b7aa7e67b91849868ccbdc11ec Mon Sep 17 00:00:00 2001
From: Hannes Probst <hannes@deepnote.com>
Date: Fri, 14 Nov 2025 20:07:32 +0100
Subject: [PATCH] Add opt-in debug logging configuration for Jupyter server

Adds configurable debug logging to help troubleshoot kernel communication
and server issues without impacting production performance.

Changes:
- Add environment variable-based debug logging configuration
- Make Application.log_level conditional (DEBUG or INFO)
- Add enhanced logging_config for tornado, jupyter_server, and jupyter_client
- Add opt-in Session.debug for ZMQ message flow logging
- Add environment variable documentation to README.md

All features are opt-in via environment variables:
- DEEPNOTE_ENABLE_DEBUG_LOGGING: Enables DEBUG-level logs (default: false/INFO)
- DEEPNOTE_ENABLE_ZMQ_DEBUG: Enables ZMQ message debugging (default: false)

This ensures production-safe defaults with no performance impact when disabled.
---
 README.md                                     | 25 +++++++++++++++++++
 .../jupyter/jupyter_server_config.py          | 23 ++++++++++++++---
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5a8cab4..37ca4d8 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,31 @@ deepnote-toolkit config set server.jupyter_port 9000
 
 **Security note**: The CLI will warn if Jupyter runs without authentication. For local development only. Set `DEEPNOTE_JUPYTER_TOKEN` for shared environments.
 
+## Environment Variables
+
+### Debugging and Logging
+
+The following environment variables control debug logging and diagnostic output:
+
+- **`DEEPNOTE_ENABLE_DEBUG_LOGGING`**: Set to `true` to enable verbose DEBUG-level logs for tornado, jupyter_server, and jupyter_client. This increases log verbosity which can help troubleshoot server-related issues. Default: `false` (INFO level)
+
+- **`DEEPNOTE_ENABLE_ZMQ_DEBUG`**: Set to `true` to enable detailed ZMQ message flow logging for kernel communication debugging. This logs all messages exchanged between the Jupyter server and kernel, which is useful for diagnosing stuck execution or kernel communication issues. Default: `false`
+
+**Example Usage**:
+
+```bash
+# Enable debug logging
+DEEPNOTE_ENABLE_DEBUG_LOGGING=true deepnote-toolkit server
+
+# Enable ZMQ message debugging
+DEEPNOTE_ENABLE_ZMQ_DEBUG=true deepnote-toolkit server
+
+# Enable both
+DEEPNOTE_ENABLE_DEBUG_LOGGING=true DEEPNOTE_ENABLE_ZMQ_DEBUG=true deepnote-toolkit server
+```
+
+**Note**: Debug logging can significantly increase log volume and may impact performance. Only enable in development or when troubleshooting specific issues.
+
 ## Need help?
 
 - Join our [Community](https://github.com/deepnote/deepnote/discussions)!
diff --git a/deepnote_core/resources/jupyter/jupyter_server_config.py b/deepnote_core/resources/jupyter/jupyter_server_config.py
index e45db6f..268b882 100644
--- a/deepnote_core/resources/jupyter/jupyter_server_config.py
+++ b/deepnote_core/resources/jupyter/jupyter_server_config.py
@@ -10,6 +10,11 @@
 # do not import explicitly it will break the config loading
 c = get_config()  # pylint: disable=E0602; # noqa: F821
 
+# Environment variable-based debug logging configuration
+# Set DEEPNOTE_ENABLE_DEBUG_LOGGING=true to enable verbose DEBUG logs
+# Set DEEPNOTE_ENABLE_ZMQ_DEBUG=true to enable detailed ZMQ message logging
+debug_logging_enabled = os.getenv("DEEPNOTE_ENABLE_DEBUG_LOGGING", "false").lower() == "true"
+log_level = "DEBUG" if debug_logging_enabled else "INFO"
 
 # ------------------------------------------------------------------------------
 # Application(SingletonConfigurable) configuration
@@ -27,7 +32,8 @@
 ## Set the log level by value or name.
 #  Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
 #  Default: 30
-c.Application.log_level = 10
+# Conditional based on DEEPNOTE_ENABLE_DEBUG_LOGGING environment variable
+c.Application.log_level = 10 if debug_logging_enabled else 20  # DEBUG or INFO
 
 ## Configure additional log handlers.
 #
@@ -414,7 +420,15 @@
 
 ##
 #  See also: Application.logging_config
-# c.ServerApp.logging_config = {}
+# Enhanced logging configuration for debugging
+# Uses debug_logging_enabled and log_level variables defined at the top of this file
+c.ServerApp.logging_config = {
+    "loggers": {
+        "tornado.access": {"level": log_level},
+        "jupyter_server.serverapp": {"level": log_level},
+        "jupyter_client.session": {"level": log_level},
+    }
+}
 
 ## The login handler class to use.
 #  Default: 'notebook.auth.login.LoginHandler'
@@ -820,7 +834,10 @@
 
 ## Debug output in the Session
 #  Default: False
-# c.Session.debug = False
+# Enable ZMQ message flow debugging for troubleshooting kernel communication
+# Set DEEPNOTE_ENABLE_ZMQ_DEBUG=true to enable detailed ZMQ message logging
+if os.getenv("DEEPNOTE_ENABLE_ZMQ_DEBUG", "false").lower() == "true":
+    c.Session.debug = True
 
 ## The maximum number of digests to remember.
 #