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

> Configure Apache Superset development logging effectively. Enable global debug, terminal UI logs, and Node.js daemon logs for seamless debugging in your superset repository.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/superset-sh/superset/blob/main/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:

```bash
export SUPERSET_DEBUG=1
bun run desktop

```

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

```bash
SUPERSET_DEBUG=1

```

Use the utility in your code:

```typescript
// 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:

```javascript
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`](https://github.com/superset-sh/superset/blob/main/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:

```bash
export SUPERSET_TERMINAL_DEBUG=1

```

This enables the internal `log` function in [`apps/desktop/src/main/terminal-host/index.ts`](https://github.com/superset-sh/superset/blob/main/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:

```bash
export SUPERSET_PTY_SUBPROCESS_DEBUG=1

```

This flag is checked in [`apps/desktop/src/main/terminal-host/pty-subprocess.ts`](https://github.com/superset-sh/superset/blob/main/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:

```bash
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`](https://github.com/superset-sh/superset/blob/main/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:

```typescript
// 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`](https://github.com/superset-sh/superset/blob/main/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`](https://github.com/superset-sh/superset/blob/main/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.