Skip to content

Add opt-in debug logging configuration for Jupyter server #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −3
Open

Add opt-in debug logging configuration for Jupyter server #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)!
Expand Down
23 changes: 20 additions & 3 deletions deepnote_core/resources/jupyter/jupyter_server_config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Comment on lines +35 to +36
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Inconsistency: log_level variable defined as string but integers used here.

Line 17 defines log_level = "DEBUG" if debug_logging_enabled else "INFO" (string), but this line uses integers directly. Either use the string variable consistently or define an integer variable.

Apply this diff for consistency:

-c.Application.log_level = 10 if debug_logging_enabled else 20  # DEBUG or INFO
+c.Application.log_level = log_level
🤖 Prompt for AI Agents 
In deepnote_core/resources/jupyter/jupyter_server_config.py around lines 35-36,
the code sets c.Application.log_level using integer literals while earlier (line
17) a string variable log_level = "DEBUG" if debug_logging_enabled else "INFO"
is defined; update this line to use the existing log_level variable consistently
by mapping the string to the corresponding integer (e.g., DEBUG->10, INFO->20)
or change the earlier variable to an integer value and use that variable here so
both places use the same type and value source.


## Configure additional log handlers.
#
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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
Comment on lines +837 to +840
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Optional: Extract to variable for consistency.

This works correctly, but for consistency with lines 16-17, consider extracting the environment check to a variable.

 # Debug output in the Session
 #  Default: 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
+# Enable ZMQ message flow debugging for troubleshooting kernel communication
+# Set DEEPNOTE_ENABLE_ZMQ_DEBUG=true to enable detailed ZMQ message logging
+zmq_debug_enabled = os.getenv("DEEPNOTE_ENABLE_ZMQ_DEBUG", "false").lower() == "true"
+if zmq_debug_enabled:
+    c.Session.debug = True

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In deepnote_core/resources/jupyter/jupyter_server_config.py around lines 837 to
840, extract the environment check into a named variable (e.g.,
enable_zmq_debug) for consistency with the earlier pattern (lines 16-17),
assigning it from os.getenv("DEEPNOTE_ENABLE_ZMQ_DEBUG", "false").lower() ==
"true", then use that variable in the if statement to set c.Session.debug =
True; keep the existing behavior and value comparison but centralize the env
read into the variable.


## The maximum number of digests to remember.
#
Expand Down
Loading