browser.md

Browser

microscope web serves one debugging or profiling session to one or more browser tabs.

Start a session

microscope web ./program -- ARG...
microscope web --attach PID
microscope web --core core.1234
microscope web profile.usprof

With no target, the page lets you choose what to open. The server listens on 127.0.0.1:7341 by default and chooses another free port when that port is in use.

A launched program waits for the first continue. Pass --run to start it at once. An attached process waits at its attach stop unless --resume is used.

The [follow] setting controls which child processes are debugged. Open the Processes pane to choose among them. Selecting a process changes it in every browser tab; a stop selects and marks the process that stopped. Detach releases a stopped child process while the others remain debugged; it cannot release the original process alone. See Debug the processes a program starts.

Move around

The workspace can show source, disassembly, memory, values, registers, breakpoints, threads, tasks, signals, the console, and drawings. The command palette lists available actions and keyboard shortcuts.

Each view is a pane in a group of tabs. Drag a tab onto another group's strip to join it, onto a side of a group to split it, or along the workspace's edge to dock it across. Hold Shift as you drop to float the pane in a window of its own. Move a window by its title bar or the empty area beside its tabs; drop it onto a strip or edge to dock it again. Press Escape to give up a drag. The Window menu does all of this from the keyboard too: Alt+arrow keys move between groups, Ctrl+\ splits, Alt+Shift+F floats or docks, Alt+W closes a tab, and Alt+Shift+T opens it again.

Tab to a floating window's resize grip and use the arrow keys to resize it. Hold Shift for larger steps. Escape cancels a pointer resize. Opening a pane in another docked group restores the dock so that pane is visible.

The browser keeps your arrangement across reloads. Window > Save layout as… names one to come back to, and Reset layout returns to the Debug layout. Below 720 pixels wide, the workspace shows one group at a time, with a list of every pane.

Ctrl+P lists source files named in debug information. For Python programs launched through the browser or microscope web, it also lists .py files from the script's directory (the working directory for -c or -m). It adds PYTHONPATH directories unless -E or -I ignores the environment. It skips caches, hidden directories, node_modules, site-packages, virtual environments, and symlinks. Large trees may be listed only partly, with a notice in the palette. The script opens before launch; standard-library and installed-package files become available when they appear in a stack.

Stack frames have language labels such as py, c, rs, or go when known. Consecutive runtime frames fold into a row such as "6 frames of the runtime folded". Click to expand it; a group containing the selected frame stays open.

Each tab selects its own thread or task, frame, source location, and panel. All tabs control the same session and receive the same stops.

The URL records the selected stop, frame, source, panel, and memory location. Open it in another tab to restore that view while the state remains available.

Use the console

The Console pane evaluates expressions and runs commands in the frame the tab shows. Run-control commands work like the toolbar buttons: c, n, s, f, si, ni, pause, kill, and run act on the selected thread and frame. After each one, the console says where the program stopped, for example stop #4 · stopped after source next · kvstore.c:102. until LOCATION (or advance) runs the thread to a line or function. step FUNCTION steps into that call on the current line. disassemble (or disas) opens the Disassembly view at the frame's code, a function, or a 0x address; with an instruction count it prints the instructions in the console instead. Press Enter on an empty line to repeat the last step or continue. clear or Ctrl+L empties the console, and help lists every command. Program output stays in the Output pane.

Draw values

Views can attach visualizers to values. The Drawings panel can show a buffer as an image, samples as a chart, or a mesh as an interactive model. See Views and Visualizers.

Renderers run in a sandbox. They receive only the data selected by a view and cannot read arbitrary process memory.

Open profiles

Pass one profile to explore it or several profiles to compare them:

microscope web current.usprof
microscope web current.usprof baseline.usprof

Profile panes show call trees, functions, flame views, timelines, source and disassembly costs, blocked time, task stacks, and instrumentation zones when recorded. The Python stacks switch hides interpreter frames in profiles containing Python stacks.

A recording from microscope syscalls -o FILE.usprof or microscope record --syscalls has a Syscalls view: calls grouped by name, class, process, thread, file, or call site; an event log; a latency heat map; and tabs for files, network connections, and processes. See System calls.

With no target, the page can also start a program and trace its system calls. It uses the ptrace engine, which needs no privilege. The trace updates every two seconds while the program runs, and the Processes tab shows what each thread is blocked in.

Serve through a tunnel or proxy

The default loopback listener is available only on the same machine. Use an SSH tunnel to reach it remotely.

--listen ADDRESS exposes the session directly. Anyone who can reach the address and has a session link can control the debugger, so do not expose it to an untrusted network.

For a reverse proxy, --public-url URL gives microscope the external origin and path. The proxy is responsible for authentication and access control.