Telescope — Debug Assistant

Telescope provides deep insight into your Nimbus application: requests, exceptions, database queries, jobs, cache operations, mail, events, and more — all from a beautiful dashboard. Inspired by Laravel Telescope.

§ Overview

Telescope records everything happening in your application and exposes it through a web dashboard at /telescope. It supports 18 watchers covering every subsystem:

§ Installation

$ nimbus plugin:install telescope

Or add it manually:

import "github.com/CodeSyncr/nimbus/plugins/telescope"

app.Use(telescope.New())

Once registered, visit http://localhost:3000/telescope to access the dashboard.

§ Configuration

Telescope is configured through its default config or environment variables:

§ Request Watcher

The request watcher captures every HTTP request with full details:

• Method, path, query parameters
• Request headers (sensitive headers like Authorization/Cookie are filtered)
• Request body (up to 64KB)
• Response status, size, and body
• Duration in milliseconds
• Automatic tagging (e.g., status:5xx for server errors)

Telescope's own routes (/telescope/*) are automatically excluded to avoid noise.

§ Query Watcher

Telescope hooks into GORM's logger to capture every database query:

// Automatically captured for every query:
// - SQL statement
// - Duration in milliseconds
// - Number of rows affected
// - Connection name

It also registers GORM model callbacks to track Create, Update, and Delete operations with the model name, action, and primary key.

§ Dump

Use telescope.Dump() anywhere in your application to inspect variables through the dashboard:

import "github.com/CodeSyncr/nimbus/plugins/telescope"

func (ctrl *UsersController) Show(c *http.Context) error {
    user, _ := models.FindUser(c.Param("id"))

    // Dump variable to Telescope dashboard
    telescope.Dump("user", user)
    telescope.Dump("request_headers", c.Request.Header)

    return c.View("users/show", map[string]any{"user": user})
}

Dumps are JSON-serialized and available in the Dumps tab of the Telescope dashboard.

§ Watchers Reference

Each watcher records specific data. Core hooks auto-record requests, exceptions, queries, logs, views, queue lifecycle, schedule runs, and event dispatches. The rest can be recorded manually when integrating your subsystem:

// Record a job execution
plugin.RecordJob("SendWelcomeEmail", "default", "completed",
    150*time.Millisecond, map[string]any{"user_id": 42}, nil)

// Record a cache operation
plugin.RecordCache("get", "users:42", true, 2*time.Millisecond)

// Record an outgoing HTTP request
plugin.RecordHTTPClient("POST", "https://api.stripe.com/charges",
    200, 340*time.Millisecond, nil, nil)

// Record a mail send
plugin.RecordMail("user@example.com", "Welcome!", "smtp", true, "")

// Record an event dispatch
plugin.RecordEvent("UserRegistered",
    []string{"SendWelcomeEmail", "CreateProfile"}, nil)

// Record a scheduled task
plugin.RecordSchedule("cleanup:logs", "0 2 * * *", "completed",
    5*time.Second, "Deleted 142 old entries")

// Record an authorization gate check
plugin.RecordGate("edit-post", true, "user-42", nil)

// Record a Redis command
plugin.RecordRedis("GET users:42", 1*time.Millisecond, "default")

// Record a log entry
plugin.RecordLog("error", "Payment failed",
    map[string]any{"order_id": "ORD-123"})

// Record a view render
plugin.RecordView("users/show", 12*time.Millisecond, nil)

// Record a command execution
plugin.RecordCommand("migrate:run", []string{"--force"}, 0,
    2*time.Second)

§ Dashboard Routes

§ In-Memory Storage

Telescope uses a thread-safe ring buffer to store entries in memory. This means:

• Zero external dependencies (no Redis or database needed)
• Entries are lost on application restart
• Memory usage is bounded by max_entries (default: 100)
• Oldest entries are overwritten when the buffer is full

§ Plugin Capabilities

Telescope implements the full set of plugin interfaces:

// Telescope implements:
nimbus.Plugin        // Register + Boot
nimbus.HasMiddleware // Request watcher middleware
nimbus.HasRoutes     // Dashboard routes
nimbus.HasConfig     // Default configuration
nimbus.HasViews      // Embedded dashboard templates