@platformatic/watt-admin 0.5.0 → 0.6.0-alpha.10

package/README.md

@@ -1,70 +1,200 @@
-# watt-admin
+# 🔌 Watt Admin
 
-## CLI Tool
+**Real-time monitoring and administration for your Platformatic applications**
 
-The project includes a command-line interface tool to check available Platformatic runtimes.
+Watt Admin is an open-source developer monitoring tool that provides instant visibility into your Node.js services. Monitor performance, analyze logs, and troubleshoot issues—all from a single, intuitive dashboard.
+
+![Watt Admin Dashboard](https://blog.platformatic.dev/content/images/2025/01/CleanShot-2025-01-15-at-15.50.54@2x.png)
+
+## ✨ Features
+
+### 📊 **Performance Metrics**
+- **Memory tracking**: RSS, heap usage, new/old space allocation with interactive charts
+- **CPU monitoring**: Real-time CPU and event loop utilization
+- **Latency analysis**: P90, P95, P99 percentiles at a glance
+- **Request rates**: Monitor requests per second across all services
+
+### 📝 **Centralized Logging**
+- View logs from all services in one place
+- Filter by service or log level
+- Toggle between formatted and raw JSON views
+- Export logs for further analysis
+
+### 🎯 **Service Management**
+- Monitor service status at a glance
+- Drill down into individual service metrics
+- Compare performance across services
+- Restart services directly from the dashboard
+
+### 🔥 **Profiling & Recording** *(New!)*
+- **CPU profiling**: Capture flame graphs to identify performance bottlenecks
+- **Heap profiling**: Analyze memory allocation patterns
+- **Offline analysis**: Generate self-contained HTML bundles for sharing and review
+- **Recording mode**: Capture metrics and profiles over time for post-mortem analysis
+
+## 🚀 Quick Start
+
+### Using npx (Recommended)
+
+Launch Watt Admin with a single command:
+
+```bash
+npx wattpm admin
+```
+
+The dashboard will automatically discover your running Platformatic runtimes and open at `http://localhost:4042`.
 
 ### Installation
 
-After installing the project dependencies, you can run the tool directly:
+Install globally for convenient access:
 
 ```bash
-./cli.js
+npm install -g @platformatic/watt-admin
 ```
 
-To run the CLI on a custom port, you can just pass it as an argument with `./cli.js --port 4321`.
+Then run:
 
-The tool is also available as a binary when installed globally or linked:
+```bash
+watt-admin
+```
+
+## 💡 Usage
+
+### Basic Usage
+
+When you run `watt-admin`, it automatically discovers all available Platformatic runtimes:
 
 ```bash
-npm link  # Link the package locally
-watt-runtime  # Run the command
+$ watt-admin
+Select a runtime: (Use arrow keys)
+❯ my-app (PID: 12345) (Started at 3/10/2025, 10:00:00 AM)
+  api-service (PID: 54321) (Started at 3/10/2025, 9:30:00 AM)
 ```
 
-### Usage
+If only one runtime is running, it will be selected automatically.
 
-The tool automatically discovers all available Platformatic runtimes. If multiple runtimes are found, it will prompt you to select one using an interactive menu.
+### Custom Port
 
+Run Watt Admin on a different port:
+
+```bash
+watt-admin --port 4321
 ```
-$ watt-runtime
-Select a runtime: (Use arrow keys)
-❯ runtime-name (PID: 12345) (Started at 3/10/2025, 10:00:00 AM)
-  another-runtime (PID: 54321) (Started at 3/10/2025, 9:30:00 AM)
+
+### Recording Mode
+
+Capture metrics and profiling data for offline analysis:
+
+```bash
+# Profile CPU usage
+watt-admin --record --profile cpu
+
+# Profile heap allocation
+watt-admin --record --profile heap
 ```
 
-If only one runtime is available, it will be automatically selected.
+When recording, press `Ctrl+C` to stop. Watt Admin will:
+1. Collect all metrics and profiling data
+2. Generate a self-contained HTML bundle
+3. Automatically open the bundle in your browser
+
+The generated HTML file contains everything you need for offline analysis—perfect for sharing with your team or reviewing later.
+
+## 🏗️ Development
 
-## Project setup
+### Prerequisites
 
+- Node.js 18 or higher
+- A running Platformatic runtime to monitor
+
+### Setup
+
+```bash
+git clone https://github.com/platformatic/watt-admin.git
+cd watt-admin
+npm install
+cp .env.sample .env
 ```
-npm install && cp .env.sample .env
+
+### Development Mode
+
+Auto-reload both backend and frontend on changes:
+
+```bash
+npm run dev
 ```
 
 ### Build
 
-```
+```bash
 npm run build
 ```
 
-### Start
+### Run Tests
 
-```
-npm run start
+```bash
+# Run all tests
+npm test
+
+# Run specific test suites
+npm run test:cli        # CLI tests
+npm run test:backend    # Backend tests
+npm run test:frontend   # Frontend tests
+npm run test:e2e        # End-to-end tests
 ```
 
-### Dev Mode
-
-This will auto-reload both the backend and frontend when changes are made.
+### Project Structure
 
 ```
-npm run dev
+watt-admin/
+├── cli.js              # CLI entry point
+├── lib/                # Core CLI functionality
+├── web/
+│   ├── backend/        # Fastify API server
+│   ├── frontend/       # React dashboard
+│   └── composer/       # Platformatic Gateway
+├── watt.json           # Wattpm configuration
+└── test/               # Test suites
 ```
 
-### Navigate the app
+## 🎯 Use Cases
+
+### Development Workflow
+Monitor your application while developing locally. Instantly see the impact of code changes on performance.
+
+### Debugging Performance Issues
+Use CPU and heap profiling to identify bottlenecks and memory leaks before they reach production.
+
+### Team Collaboration
+Generate offline HTML bundles to share performance data and profiling results with your team.
+
+### Learning and Optimization
+Understand how your services behave under load and optimize based on real data.
+
+## 🔗 Related Tools
+
+For production monitoring and observability, check out [Platformatic Console](https://platformatic.dev/console)—the intelligent command center for Platformatic Cloud deployments.
+
+## 📚 Documentation
+
+- [Platformatic Documentation](https://docs.platformatic.dev)
+- [Watt Admin Blog Post](https://blog.platformatic.dev/introducing-watt-admin)
+- [Platformatic Wattpm](https://docs.platformatic.dev/docs/guides/wattpm)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please check out our [contributing guidelines](CONTRIBUTING.md) to get started.
+
+## 📄 License
+
+Apache-2.0 License - see [LICENSE](LICENSE) for details.
+
+## 🙋 Support
+
+- [GitHub Issues](https://github.com/platformatic/watt-admin/issues)
+- [Discord Community](https://discord.gg/platformatic)
+- [Twitter](https://twitter.com/platformatic)
+
+---
 
-0. check you started `watt-admin`
-1. you should now see an info log like `Platformatic is now listening at http://127.0.0.1:{PORT}` (open the local URL)
-2. click on link above to navigate the frontend app
-3. you can call the backend by prefixing the local URL with `/api`
-4. call the `/api/runtimes` endpoint (you should receive the PID)
-5. call the `/api/runtimes/{pid}/metrics` endpoint
+Built with ❤️ by the [Platformatic](https://platformatic.dev) team

package/cli.d.ts

@@ -0,0 +1,3 @@
+import type { Runtime } from '@platformatic/control'
+
+export default function main (): Promise<Runtime | null>

package/cli.js

@@ -2,9 +2,10 @@
 
 'use strict'
 
-const { RuntimeApiClient } = require('@platformatic/control')
-const { select } = require('@inquirer/prompts')
-const { start } = require('./lib/start')
+import esmain from 'es-main'
+import { RuntimeApiClient } from '@platformatic/control'
+import { select } from '@inquirer/prompts'
+import { start } from './lib/start.js'
 
 async function getLocationDetails (client, runtime) {
   try {
@@ -39,99 +40,95 @@ async function getLocationDetails (client, runtime) {
   }
 }
 
-async function main () {
+let client
+export default async function main () {
   try {
     // Get available runtimes
-    const client = new RuntimeApiClient()
-
-    try {
-      const runtimes = await client.getRuntimes()
-
-      if (runtimes.length === 0) {
-        console.log('No runtimes available. Please start a Platformatic runtime first.')
-        return null
-      } else if (runtimes.length === 1) {
-        // Only one runtime, no need to prompt
-        const runtime = runtimes[0]
-        const locationDetails = await getLocationDetails(client, runtime)
-        // Display information about the runtime
-        console.log(`Name: ${runtime.packageName || 'unnamed'}`)
-        console.log(`PID: ${runtime.pid}`)
-        console.log(`Working directory: ${locationDetails.cwd}`)
-
-        if (locationDetails.configPath !== 'Unknown' &&
-            locationDetails.configPath !== 'Unknown (config not available)') {
-          console.log(`Configuration path: ${locationDetails.configPath}`)
-        }
+    client = new RuntimeApiClient()
+
+    const runtimes = await client.getRuntimes()
+
+    if (runtimes.length === 0) {
+      console.log('No runtimes available. Please start a Platformatic runtime first.')
+      return null
+    } else if (runtimes.length === 1) {
+      // Only one runtime, no need to prompt
+      const runtime = runtimes[0]
+      const locationDetails = await getLocationDetails(client, runtime)
+      // Display information about the runtime
+      console.log(`Name: ${runtime.packageName || 'unnamed'}`)
+      console.log(`PID: ${runtime.pid}`)
+      console.log(`Working directory: ${locationDetails.cwd}`)
+
+      if (locationDetails.configPath !== 'Unknown' &&
+          locationDetails.configPath !== 'Unknown (config not available)') {
+        console.log(`Configuration path: ${locationDetails.configPath}`)
+      }
 
-        // If we have any command line arguments, display them
-        if (runtime.argv && runtime.argv.length > 0) {
-          console.log(`Command: ${runtime.argv.join(' ')}`)
-        }
+      // If we have any command line arguments, display them
+      if (runtime.argv && runtime.argv.length > 0) {
+        console.log(`Command: ${runtime.argv.join(' ')}`)
+      }
+
+      // If we have a start time, display it
+      if (runtime.startTime) {
+        console.log(`Started at: ${new Date(runtime.startTime).toLocaleString()}`)
+      }
+      return runtime
+    } else {
+      // Multiple runtimes, prompt user to select one
+
+      // Prepare the runtime choices with async map
+      const choicesPromises = runtimes.map(async (runtime) => {
+        // Create a concise description that helps identify this runtime
+        const description = []
 
-        // If we have a start time, display it
+        // Show working directory as it's usually the most useful identifier
+        description.push(`Dir: ${runtime.cwd || 'Unknown'}`)
+
+        // Add the start time if available
         if (runtime.startTime) {
-          console.log(`Started at: ${new Date(runtime.startTime).toLocaleString()}`)
-        }
-        return runtime
-      } else {
-        // Multiple runtimes, prompt user to select one
-
-        // Prepare the runtime choices with async map
-        const choicesPromises = runtimes.map(async runtime => {
-          // Create a concise description that helps identify this runtime
-          const description = []
-
-          // Show working directory as it's usually the most useful identifier
-          description.push(`Dir: ${runtime.cwd || 'Unknown'}`)
-
-          // Add the start time if available
-          if (runtime.startTime) {
-            description.push(`Started: ${new Date(runtime.startTime).toLocaleString()}`)
-          }
-
-          return {
-            name: `${runtime.packageName || 'unnamed'} (PID: ${runtime.pid})`,
-            value: runtime,
-            description: description.join(', ')
-          }
-        })
-
-        // Wait for all async operations to complete
-        const choices = await Promise.all(choicesPromises)
-
-        // Prompt the user to select a runtime
-        const selectedRuntime = await select({
-          message: 'Select a runtime:',
-          choices
-        })
-
-        const locationDetails = await getLocationDetails(client, selectedRuntime)
-        // Display information about the selected runtime
-        console.log('\nRuntime Details:')
-        console.log(`Name: ${selectedRuntime.packageName || 'unnamed'}`)
-        console.log(`PID: ${selectedRuntime.pid}`)
-        console.log(`Working directory: ${locationDetails.cwd}`)
-
-        if (locationDetails.configPath !== 'Unknown' &&
-            locationDetails.configPath !== 'Unknown (config not available)') {
-          console.log(`Configuration path: ${locationDetails.configPath}`)
+          description.push(`Started: ${new Date(runtime.startTime).toLocaleString()}`)
         }
 
-        // If we have any command line arguments, display them
-        if (selectedRuntime.argv && selectedRuntime.argv.length > 0) {
-          console.log(`Command: ${selectedRuntime.argv.join(' ')}`)
+        return {
+          name: `${runtime.packageName || 'unnamed'} (PID: ${runtime.pid})`,
+          value: runtime,
+          description: description.join(', ')
         }
+      })
+
+      // Wait for all async operations to complete
+      const choices = await Promise.all(choicesPromises)
+
+      // Prompt the user to select a runtime
+      const selectedRuntime = await select({
+        message: 'Select a runtime:',
+        choices
+      })
+
+      const locationDetails = await getLocationDetails(client, selectedRuntime)
+      // Display information about the selected runtime
+      console.log('\nRuntime Details:')
+      console.log(`Name: ${selectedRuntime.packageName || 'unnamed'}`)
+      console.log(`PID: ${selectedRuntime.pid}`)
+      console.log(`Working directory: ${locationDetails.cwd}`)
+
+      if (locationDetails.configPath !== 'Unknown' &&
+          locationDetails.configPath !== 'Unknown (config not available)') {
+        console.log(`Configuration path: ${locationDetails.configPath}`)
+      }
 
-        // If we have a start time, display it
-        if (selectedRuntime.startTime) {
-          console.log(`Started at: ${new Date(selectedRuntime.startTime).toLocaleString()}`)
-        }
-        return selectedRuntime
+      // If we have any command line arguments, display them
+      if (selectedRuntime.argv && selectedRuntime.argv.length > 0) {
+        console.log(`Command: ${selectedRuntime.argv.join(' ')}`)
+      }
+
+      // If we have a start time, display it
+      if (selectedRuntime.startTime) {
+        console.log(`Started at: ${new Date(selectedRuntime.startTime).toLocaleString()}`)
       }
-    } finally {
-      // Always clean up the client
-      await client.close()
+      return selectedRuntime
     }
   } catch (error) {
     console.error('Error:', error.message)
@@ -140,19 +137,16 @@ async function main () {
 }
 
 // Execute the main function if this script is run directly
-if (require.main === module) {
+if (esmain(import.meta)) {
   main().then((selectedRuntime) => {
     if (!selectedRuntime) {
       return
     }
     console.log('Starting Watt admin...')
     console.log('--------')
-    return start(selectedRuntime.pid)
+    return start(client, selectedRuntime.pid)
   }).catch(error => {
     console.error('Fatal error:', error)
     process.exit(1)
   })
-} else {
-  // Export for use as a module
-  module.exports = main
 }

package/lib/start.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeApiClient } from '@platformatic/control'
+
+export declare function start (client: RuntimeApiClient, selectedRuntime: string): Promise<void>

package/lib/start.js

@@ -1,20 +1,95 @@
 'use strict'
 
-const { buildRuntime, loadConfig } = require('@platformatic/runtime')
-const { join } = require('path')
-const { parseArgs } = require('util')
+import { create } from '@platformatic/runtime'
+import { join } from 'path'
+import { parseArgs, promisify } from 'util'
+import { request } from 'undici'
+import { exec } from 'child_process'
+import closeWithGrace from 'close-with-grace'
 
-async function start (selectedRuntime) {
+const __dirname = import.meta.dirname
+
+const execAsync = promisify(exec)
+
+const msOneMinute = 1000 * 60
+let recordTimeout
+let entrypointUrl
+
+export async function start (client, selectedRuntime) {
   process.env.SELECTED_RUNTIME = selectedRuntime
-  const { values: { port } } = parseArgs({ options: { port: { type: 'string' } } })
+  const { values: { port, record, profile } } = parseArgs({
+    options: {
+      port: { type: 'string' },
+      profile: { type: 'string' },
+      record: { type: 'boolean' },
+    }
+  })
+
   process.env.PORT = port || 4042
 
+  const requestRecord = async (mode) => {
+    return await request(`${entrypointUrl}/api/record/${selectedRuntime}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ mode, profile: profile ?? 'cpu' })
+    })
+  }
+
+  const recordMetrics = async () => {
+    try {
+      const { statusCode, body } = await requestRecord('stop')
+      if (statusCode === 200) {
+        await body.dump()
+        const bundlePath = join(__dirname, '..', 'web', 'frontend', 'dist', 'index.html')
+        await execAsync(`${process.platform === 'win32' ? 'start' : 'open'} ${bundlePath}`)
+      } else {
+        console.error(`Failure triggering the stop command: ${await body.text()}`)
+      }
+    } catch (error) {
+      console.error('Error on record metrics', { error, entrypointUrl })
+      clearTimeout(recordTimeout)
+    }
+  }
+
   const configFile = join(__dirname, '..', 'watt.json')
-  const { configManager, args } = await loadConfig({
-  }, ['--production', '--config', configFile], { production: true, disableEnvLoad: true })
-  configManager.args = args
-  const server = await buildRuntime(configManager)
-  await server.start()
-}
+  const server = await create(configFile, undefined, {
+    setupSignals: false
+  })
+  entrypointUrl = await server.start()
 
-module.exports.start = start
+  if (record) {
+    async function shutdown () {
+      // Always clean up the client
+      await client.close()
+
+      // Then stop the server
+      await server.close()
+    }
+
+    async function recordAndShutdown () {
+      console.log('SIGINT received, recording metrics and shutting down...')
+      clearTimeout(recordTimeout)
+      await recordMetrics(entrypointUrl)
+      await shutdown()
+      process.removeAllListeners('SIGINT')
+    }
+
+    process.once('SIGINT', () => {
+      process.on('SIGINT', () => {
+        // we ignore future signals to avoid double shutdown
+      })
+      recordAndShutdown()
+    })
+
+    const { statusCode, body } = await requestRecord('start')
+    if (statusCode === 200) {
+      await body.dump()
+
+      recordTimeout = setTimeout(async () => {
+        await recordMetrics(entrypointUrl)
+      }, msOneMinute * 10)
+    } else {
+      console.log(`Failure triggering the start command: ${await body.text()}`)
+    }
+  }
+}