How to Configure Logging in Apache Superset Development: Environment Setup Guide

Set SUPERSET_DEBUG=1 to enable global debug output, use localStorage.setItem('SUPERSET_TERMINAL_DEBUG','1') in Chrome DevTools for terminal UI logs, and set SUPERSET_TERMINAL_DEBUG=1 for the Node.js daemon side.

Apache Superset development relies on a layered logging architecture that lets you surface debug information for specific subsystems without overwhelming your terminal. The superset-sh/superset repository implements environment-variable and localStorage-based toggles that control output across the desktop application, terminal sessions, and web components.

Global Debug Logging with SUPERSET_DEBUG

The apps/desktop/src/shared/debug.ts module exports a debugLog utility that checks the SUPERSET_DEBUG environment variable at module load time. When enabled, it prefixes messages with a timestamp and component name; when disabled, calls compile to no-ops for zero runtime overhead.

Enable global debugging in your shell:

export SUPERSET_DEBUG=1
bun run desktop

Or persist it across sessions by adding to .env in the repository root:

SUPERSET_DEBUG=1

Use the utility in your code:

// src/my-feature/awesome.ts
import { debugLog } from "shared/debug";

export function doAwesomeStuff(payload: unknown) {
  debugLog("awesome", "Received payload:", payload);
  // …your logic…
}

Terminal Logging Configuration

Superset’s terminal subsystem splits logging across three scopes: the renderer UI, the Node.js daemon, and the PTY subprocess.

Renderer-Side Terminal UI Logs

To debug the React-based terminal interface, set a localStorage flag in Chrome DevTools:

localStorage.setItem('SUPERSET_TERMINAL_DEBUG','1')

Reload the desktop window to apply. This toggle is read in apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/config.ts.

Node.js Daemon Logs

For the main-process terminal daemon, set the environment variable before launching:

export SUPERSET_TERMINAL_DEBUG=1

This enables the internal log function in apps/desktop/src/main/terminal-host/index.ts, which prefixes lines with timestamps and component identifiers:

[2026-03-08T14:22:31.123Z] [terminal-host] [INFO] Creating new terminal session { sessionId: "abc123" }

PTY Subprocess Debugging

To trace the raw PTY (pseudo-terminal) subprocess communication:

export SUPERSET_PTY_SUBPROCESS_DEBUG=1

This flag is checked in apps/desktop/src/main/terminal-host/pty-subprocess.ts and logs low-level spawn and data events.

Capturing Renderer Console Output via MCP

The desktop application exposes a Model Context Protocol (MCP) tool that captures console.* calls from the renderer process. This is useful when you cannot open DevTools directly.

Retrieve logs via the MCP command:

superset-mcp get-console-logs --level=debug

Valid levels are log, warn, error, and debug. The implementation in packages/desktop-mcp/src/mcp/tools/get-console-logs/get-console-logs.ts maintains an in-memory ring buffer of intercepted console calls, allowing you to filter by severity after the fact.

Emit a capturable message in your React component:

// any renderer component
console.warn("[Superset] Something odd happened!", { detail: foo });

Production Error Reporting

While the above flags are intended for development, Superset uses Sentry for production error tracking. The integration is registered in apps/web/src/instrumentation.ts and activates automatically when NEXT_PUBLIC_SENTRY_DSN is present. During local development, leave this undefined to keep Sentry silent and rely on the debug utilities instead.

Summary

• Set SUPERSET_DEBUG=1 to enable the global debugLog utility across any package.
• Use localStorage.setItem('SUPERSET_TERMINAL_DEBUG','1') in Chrome DevTools for renderer-side terminal UI debugging.
• Export SUPERSET_TERMINAL_DEBUG=1 for Node.js daemon logs and SUPERSET_PTY_SUBPROCESS_DEBUG=1 for PTY subprocess tracing.
• Capture renderer console output via the get-console-logs MCP tool with level filtering.
• Keep Sentry disabled in development by omitting NEXT_PUBLIC_SENTRY_DSN.

Frequently Asked Questions

How do I enable debug logging for all Superset packages?

Set the SUPERSET_DEBUG environment variable to 1 or true before starting the application. This activates the debugLog utility in apps/desktop/src/shared/debug.ts, which adds timestamped, prefixed output to any module that imports it.

What's the difference between SUPERSET_DEBUG and SUPERSET_TERMINAL_DEBUG?

SUPERSET_DEBUG controls the global shared utility used across the entire desktop application, while SUPERSET_TERMINAL_DEBUG specifically governs the terminal subsystem. The terminal flag exists in two scopes: the renderer (controlled via localStorage) and the Node.js daemon (controlled via environment variable).

How can I view renderer-side console logs from the command line?

Use the Model Context Protocol tool get-console-logs provided by the desktop-mcp package. Run superset-mcp get-console-logs --level=debug to retrieve buffered console output from the React renderer without opening Chrome DevTools.

Is Sentry enabled during development?

No. Sentry error reporting is only active when NEXT_PUBLIC_SENTRY_DSN is defined, which typically occurs in production builds. During local development, rely on the SUPERSET_DEBUG flags and MCP console capture tools to diagnose issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}