feat(admin): Add terminal-style SQL Shell for ClickHouse tracing

snuba/admin/package.json

@@ -7,6 +7,7 @@
     "test": "jest"
   },
   "dependencies": {
+    "@tanstack/react-virtual": "^3.0.0",
     "@codemirror/commands": "^6.6.0",
     "@codemirror/lang-sql": "^6.7.0",
     "@codemirror/language": "^6.0.0",

snuba/admin/static/body.tsx

@@ -14,16 +14,15 @@ function Body(props: Props) {
 
   return (
     <div style={bodyStyle}>
-      <div style={{ marginBottom: 20 }}>{activeItem.display}</div>
       <activeItem.component {...rest} />
     </div>
   );
 }
 
 const bodyStyle = {
   width: "100%",
-  maxWidth: "calc(100% - 290px)",
-  margin: 20,
+  maxWidth: "calc(100% - 260px)",
+  margin: 10,
   fontSize: 20,
 };
 

snuba/admin/static/data.tsx

@@ -4,6 +4,7 @@ import AuditLog from "SnubaAdmin/runtime_config/auditlog";
 import ClickhouseMigrations from "SnubaAdmin/clickhouse_migrations";
 import ClickhouseQueries from "SnubaAdmin/clickhouse_queries";
 import TracingQueries from "SnubaAdmin/tracing";
+import SQLShellPage, { SystemShellPage } from "SnubaAdmin/sql_shell";
 import SnQLToSQL from "SnubaAdmin/snql_to_sql";
 import Kafka from "SnubaAdmin/kafka";
 import QuerylogQueries from "SnubaAdmin/querylog";
@@ -53,6 +54,11 @@ const NAV_ITEMS = [
     display: "🏚️ System Queries",
     component: ClickhouseQueries,
   },
+  {
+    id: "system-shell",
+    display: "💻 System Shell",
+    component: SystemShellPage,
+  },
   {
     id: "clickhouse-migrations",
     display: "🚧 ClickHouse Migrations",
@@ -63,6 +69,11 @@ const NAV_ITEMS = [
     display: "🔎 ClickHouse Tracing",
     component: TracingQueries,
   },
+  {
+    id: "tracing-shell",
+    display: "💻 Tracing Shell",
+    component: SQLShellPage,
+  },
   {
     id: "rpc-endpoints",
     display: "🔌 RPC Endpoints",

snuba/admin/static/index.tsx

@@ -20,6 +20,8 @@ const containerStyle = {
 const bodyStyle = {
   flexGrow: 1,
   display: "flex",
+  minHeight: 0,
+  overflow: "hidden",
 };
 
 let client = Client();

snuba/admin/static/nav.tsx

@@ -28,11 +28,15 @@ function Nav(props: NavProps) {
   return (
     <nav style={navStyle}>
       <ul style={ulStyle}>
-        {NAV_ITEMS.map((item) =>
-          allowedTools?.includes(item.id) || allowedTools?.includes("all") ? (
+        {NAV_ITEMS.map((item) => {
+          // Shell pages inherit permissions from their parent pages
+          const permissionId = item.id === "tracing-shell" ? "tracing"
+            : item.id === "system-shell" ? "system-queries"
+            : item.id;
+          return allowedTools?.includes(permissionId) || allowedTools?.includes("all") ? (
             item.id === active ? (
               <li key={item.id} >
-                <a style={{ color: COLORS.TEXT_DEFAULT, ...linkStyle }} className="nav-link-active">
+                <a style={{ ...linkStyle, ...activeLinkStyle }} className="nav-link-active">
                   {item.display}
                 </a>
               </li>
@@ -49,16 +53,18 @@ function Nav(props: NavProps) {
             )
           ) : (
             <div key={item.id} />
-          )
-        )}
+          );
+        })}
       </ul>
     </nav>
   );
 }
 
-const navStyle = {
+const navStyle: React.CSSProperties = {
   borderRight: `1px solid ${COLORS.NAV_BORDER}`,
   width: 250,
+  overflowY: "auto",
+  flexShrink: 0,
 };
 
 const ulStyle = {
@@ -74,4 +80,11 @@ const linkStyle = {
   padding: 20,
 };
 
+const activeLinkStyle = {
+  color: COLORS.TEXT_DEFAULT,
+  backgroundColor: "rgba(59, 130, 246, 0.15)",
+  borderLeft: "3px solid #3b82f6",
+  fontWeight: "bold" as const,
+};
+
 export default Nav;

snuba/admin/static/sql_shell/command_parser.ts

@@ -0,0 +1,145 @@
+import { ParsedCommand, ShellMode } from "./types";
+
+/**
+ * Command definition for the shell parser.
+ * Each command specifies a pattern to match and how to parse it.
+ */
+interface CommandDefinition {
+  /** Regex pattern to match the command (case-insensitive) */
+  pattern: RegExp;
+  /** Parse the matched input and return a ParsedCommand */
+  parse: (match: RegExpMatchArray, input: string) => ParsedCommand;
+  /** Which modes this command is available in (default: both) */
+  modes?: ShellMode[];
+}
+
+/**
+ * Registry of all shell commands.
+ * Commands are matched in order, so more specific patterns should come first.
+ * Add new commands here to extend the shell.
+ */
+const COMMANDS: CommandDefinition[] = [
+  // USE <storage> - Select a storage
+  {
+    pattern: /^USE\s+(.+)$/i,
+    parse: (match) => ({
+      type: "use",
+      storage: match[1].trim(),
+    }),
+  },
+
+  // HOST <host:port> - Select target host (system mode only)
+  {
+    pattern: /^HOST\s+(.+)$/i,
+    parse: (match) => {
+      const hostStr = match[1].trim();
+      const hostMatch = hostStr.match(/^([^:]+):(\d+)$/);
+      if (hostMatch) {
+        return {
+          type: "host",
+          host: hostMatch[1],
+          port: parseInt(hostMatch[2], 10),
+        };
+      }
+      // Default port if not specified
+      return { type: "host", host: hostStr, port: 9000 };
+    },
+    modes: ["system"],
+  },
+
+  // SHOW STORAGES - List available storages
+  {
+    pattern: /^SHOW\s+STORAGES$/i,
+    parse: () => ({ type: "show_storages" }),
+  },
+
+  // SHOW HOSTS - List available hosts (system mode only)
+  {
+    pattern: /^SHOW\s+HOSTS$/i,
+    parse: () => ({ type: "show_hosts" }),
+    modes: ["system"],
+  },
+
+  // PROFILE ON/OFF - Toggle profile event collection (tracing mode only)
+  {
+    pattern: /^PROFILE\s+(ON|OFF)$/i,
+    parse: (match) => ({
+      type: "profile",
+      enabled: match[1].toUpperCase() === "ON",
+    }),
+    modes: ["tracing"],
+  },
+
+  // TRACE RAW/FORMATTED - Toggle trace output format (tracing mode only)
+  {
+    pattern: /^TRACE\s+(RAW|FORMATTED)$/i,
+    parse: (match) => ({
+      type: "trace_mode",
+      formatted: match[1].toUpperCase() === "FORMATTED",
+    }),
+    modes: ["tracing"],
+  },
+
+  // SUDO ON/OFF - Toggle sudo mode (system mode only)
+  {
+    pattern: /^SUDO\s+(ON|OFF)$/i,
+    parse: (match) => ({
+      type: "sudo",
+      enabled: match[1].toUpperCase() === "ON",
+    }),
+    modes: ["system"],
+  },
+
+  // HELP - Show help message
+  {
+    pattern: /^HELP$/i,
+    parse: () => ({ type: "help" }),
+  },
+
+  // CLEAR - Clear terminal output
+  {
+    pattern: /^CLEAR$/i,
+    parse: () => ({ type: "clear" }),
+  },
+];
+
+/**
+ * Parse user input into a structured command.
+ * Commands are matched against the registry in order.
+ * If no command matches, the input is treated as a SQL query.
+ *
+ * @param input - The raw user input
+ * @param mode - The current shell mode (tracing or system)
+ * @returns The parsed command
+ */
+export function parseCommand(input: string, mode: ShellMode): ParsedCommand {
+  const trimmed = input.trim();
+
+  for (const cmd of COMMANDS) {
+    // Skip commands not available in current mode
+    if (cmd.modes && !cmd.modes.includes(mode)) {
+      continue;
+    }
+
+    const match = trimmed.match(cmd.pattern);
+    if (match) {
+      return cmd.parse(match, trimmed);
+    }
+  }
+
+  // Default: treat as SQL query
+  return { type: "sql", query: trimmed };
+}
+
+/**
+ * Get list of commands available in a given mode.
+ * Useful for generating help text or autocomplete suggestions.
+ *
+ * @param mode - The shell mode
+ * @returns Array of pattern strings for available commands
+ */
+export function getAvailableCommands(mode: ShellMode): string[] {
+  return COMMANDS
+    .filter((cmd) => !cmd.modes || cmd.modes.includes(mode))
+    .map((cmd) => cmd.pattern.source.replace(/\^|\$|\\/g, "").replace(/\(\.\+\)/g, "<arg>"));
+}

snuba/admin/static/sql_shell/index.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import Client from "SnubaAdmin/api_client";
+import SQLShell from "SnubaAdmin/sql_shell/shell";
+
+interface ShellPageProps {
+  api: Client;
+}
+
+const shellWrapperStyle = {
+  height: "calc(100vh - 75px)",
+};
+
+function SQLShellPage({ api }: ShellPageProps) {
+  return (
+    <div style={shellWrapperStyle}>
+      <SQLShell api={api} mode="tracing" />
+    </div>
+  );
+}
+
+function SystemShellPage({ api }: ShellPageProps) {
+  return (
+    <div style={shellWrapperStyle}>
+      <SQLShell api={api} mode="system" />
+    </div>
+  );
+}
+
+export default SQLShellPage;
+export { SystemShellPage };