README
¶
Telescope Plugin for Nimbus
Telescope provides insight into your local Nimbus development environment, inspired by Laravel Telescope.
Features
- Request watcher — Records HTTP requests (method, path, status, duration)
- Exceptions — Records panics and handled framework errors
- Queries + model events — Database query log plus create/update/delete model hooks
- Logs — Mirrors Nimbus logger output into Telescope entries
- Views — Render timing from
view.Render/c.View - Queue + schedule + events — Observes global queue lifecycle, scheduler runs, and dispatched events
- Dashboard — View recent activity at
/telescope - In-memory storage — Ring buffer (configurable max entries)
Installation
// bin/server.go
import "github.com/CodeSyncr/nimbus/plugins/telescope"
app.Use(telescope.New())
Add the request watcher middleware in start/kernel.go:
if te := app.Plugin("telescope"); te != nil {
if t, ok := te.(*telescope.Plugin); ok {
app.Router.Use(t.RequestWatcher())
}
}
Configuration
| Variable | Description | Default |
|---|---|---|
TELESCOPE_ENABLED |
Enable in production | false |
TELESCOPE_PATH |
Dashboard URL path | /telescope |
Dashboard
Access the dashboard at http://localhost:3333/telescope (or your app URL + /telescope).
- Requests — HTTP request log with status, method, path, duration
- Exceptions — Panics and app/framework errors
- Queries — Database query log
- Logs — Application log entries
- Views — Template render timings
- Jobs / Schedule / Events — Runtime operational activity
Security
Telescope is disabled in production by default. Set TELESCOPE_ENABLED=true to enable in production, and restrict access via authorization.
Documentation
¶
Index ¶
- func Dump(label string, v any)
- func InstrumentRoundTripper(inner http.RoundTripper) http.RoundTripper
- func NewTelescopeZapCore(enab zapcore.LevelEnabler) zapcore.Core
- func RecordEventFromDispatch(name string, payload any)
- func RecordLog(level, message string, context map[string]any)
- func RecordScheduleRun(name, expression, status string, duration time.Duration, output string)
- func RecordViewRender(name string, duration time.Duration, data any)
- func RegisterQueueObserver()
- type Entry
- type EntryType
- type ExceptionContent
- type LogContent
- type Plugin
- func (p *Plugin) Boot(app *nimbus.App) error
- func (p *Plugin) DefaultConfig() map[string]any
- func (p *Plugin) Middleware() map[string]router.Middleware
- func (p *Plugin) RecordBatch(id, name string, totalJobs, pendingJobs, failedJobs int, progress float64)
- func (p *Plugin) RecordCache(op, key string, hit bool, duration time.Duration)
- func (p *Plugin) RecordCommand(name string, args []string, exitCode int, duration time.Duration)
- func (p *Plugin) RecordEvent(name string, listeners []string, payload map[string]any)
- func (p *Plugin) RecordGate(ability string, result bool, userID string, arguments map[string]any)
- func (p *Plugin) RecordHTTPClient(method, url string, statusCode int, duration time.Duration, ...)
- func (p *Plugin) RecordJob(name, queue, status string, duration time.Duration, payload map[string]any, ...)
- func (p *Plugin) RecordLog(level, message string, context map[string]any)
- func (p *Plugin) RecordMail(to, subject, mailer string, success bool, body string)
- func (p *Plugin) RecordNotification(channel, notifiable, notification string, data map[string]any)
- func (p *Plugin) RecordRedis(command string, duration time.Duration, connection string)
- func (p *Plugin) RecordSchedule(name, expression, status string, duration time.Duration, output string)
- func (p *Plugin) RecordView(name string, duration time.Duration, data map[string]any)
- func (p *Plugin) Register(app *nimbus.App) error
- func (p *Plugin) RegisterQueryWatcher()
- func (p *Plugin) RegisterRoutes(r *router.Router)
- func (p *Plugin) RequestWatcher() router.Middleware
- func (p *Plugin) ViewsFS() fs.FS
- type QueryContent
- type RequestContent
- type Store
- func (s *Store) All(limit int) []*Entry
- func (s *Store) Clear()
- func (s *Store) EnableOnly(types ...EntryType)
- func (s *Store) Entries(typ EntryType, limit int) []*Entry
- func (s *Store) Get(id string) *Entry
- func (s *Store) LoadLatestFromBackend(limit int)
- func (s *Store) PruneBefore(t time.Time)
- func (s *Store) Record(entry *Entry)
- func (s *Store) SetPersistBackend(p persistBackend)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Dump ¶
Dump records a variable dump to Telescope. Call from your handlers or middleware. Example: telescope.Dump("user", user)
func InstrumentRoundTripper ¶
func InstrumentRoundTripper(inner http.RoundTripper) http.RoundTripper
InstrumentRoundTripper wraps an http.RoundTripper and records each outgoing request to Telescope (HTTP Client watcher). Use with a custom client:
client := &http.Client{Transport: telescope.InstrumentRoundTripper(nil)}
Passing nil uses http.DefaultTransport as the inner transport.
func NewTelescopeZapCore ¶
func NewTelescopeZapCore(enab zapcore.LevelEnabler) zapcore.Core
NewTelescopeZapCore returns a zap core that mirrors log lines into Telescope.
func RecordEventFromDispatch ¶
RecordEventFromDispatch records a generic event (call from events.AfterDispatch hook).
func RecordScheduleRun ¶
RecordScheduleRun records a scheduled task execution.
func RecordViewRender ¶
RecordViewRender records template render timing (wired from view.OnRendered).
func RegisterQueueObserver ¶
func RegisterQueueObserver()
RegisterQueueObserver subscribes to global queue events (call from Plugin.Register).
Types ¶
type Entry ¶
type Entry struct {
ID string `json:"id"`
Type EntryType `json:"type"`
Content map[string]any `json:"content"`
Tags []string `json:"tags,omitempty"`
BatchID string `json:"batch_id,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
Entry represents a single telescope record.
type EntryType ¶
type EntryType string
EntryType identifies the kind of telescope entry.
const ( EntryRequest EntryType = "request" EntryCommand EntryType = "command" EntrySchedule EntryType = "schedule" EntryJob EntryType = "job" EntryBatch EntryType = "batch" EntryCache EntryType = "cache" EntryDump EntryType = "dump" EntryEvent EntryType = "event" EntryException EntryType = "exception" EntryGate EntryType = "gate" EntryHTTPClient EntryType = "http_client" EntryLog EntryType = "log" EntryMail EntryType = "mail" EntryModel EntryType = "model" EntryNotification EntryType = "notification" EntryQuery EntryType = "query" EntryRedis EntryType = "redis" EntryView EntryType = "view" )
type ExceptionContent ¶
type ExceptionContent struct {
Class string `json:"class"`
Message string `json:"message"`
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
Trace string `json:"trace,omitempty"`
}
ExceptionContent holds exception/panic data.
type LogContent ¶
type LogContent struct {
Level string `json:"level"`
Message string `json:"message"`
Context map[string]any `json:"context,omitempty"`
}
LogContent holds log entry data.
type Plugin ¶
type Plugin struct {
nimbus.BasePlugin
// contains filtered or unexported fields
}
Plugin integrates Telescope debugging into Nimbus.
func (*Plugin) Boot ¶
Boot performs post-registration setup (e.g. register query watcher with database).
func (*Plugin) DefaultConfig ¶
DefaultConfig returns the default configuration.
func (*Plugin) Middleware ¶
func (p *Plugin) Middleware() map[string]router.Middleware
Middleware returns named middleware provided by this plugin.
func (*Plugin) RecordBatch ¶
func (p *Plugin) RecordBatch(id, name string, totalJobs, pendingJobs, failedJobs int, progress float64)
RecordBatch records a job batch operation.
func (*Plugin) RecordCache ¶
RecordCache records a cache operation (hit, miss, set, delete, flush).
func (*Plugin) RecordCommand ¶
RecordCommand records a CLI command execution.
func (*Plugin) RecordEvent ¶
RecordEvent records an event dispatch.
func (*Plugin) RecordGate ¶
RecordGate records an authorization gate check.
func (*Plugin) RecordHTTPClient ¶
func (p *Plugin) RecordHTTPClient(method, url string, statusCode int, duration time.Duration, requestHeaders, responseHeaders map[string]string)
RecordHTTPClient records an outgoing HTTP request.
func (*Plugin) RecordJob ¶
func (p *Plugin) RecordJob(name, queue, status string, duration time.Duration, payload map[string]any, err error)
RecordJob records a queued job execution.
func (*Plugin) RecordMail ¶
RecordMail records a sent email.
func (*Plugin) RecordNotification ¶
RecordNotification records a notification dispatch.
func (*Plugin) RecordRedis ¶
RecordRedis records a Redis command.
func (*Plugin) RecordSchedule ¶
func (p *Plugin) RecordSchedule(name, expression, status string, duration time.Duration, output string)
RecordSchedule records a scheduled task execution.
func (*Plugin) RecordView ¶
RecordView records a template render.
func (*Plugin) Register ¶
Register binds the Telescope store to the container and registers plugin views.
func (*Plugin) RegisterQueryWatcher ¶
func (p *Plugin) RegisterQueryWatcher()
RegisterQueryWatcher attaches a custom logger and model callbacks to the global database.
func (*Plugin) RegisterRoutes ¶
RegisterRoutes mounts the Telescope dashboard routes.
func (*Plugin) RequestWatcher ¶
func (p *Plugin) RequestWatcher() router.Middleware
RequestWatcher returns middleware that records HTTP requests.
type QueryContent ¶
type QueryContent struct {
SQL string `json:"sql"`
Bindings []any `json:"bindings,omitempty"`
Duration time.Duration `json:"duration_ms"`
Connection string `json:"connection,omitempty"`
}
QueryContent holds database query data.
type RequestContent ¶
type RequestContent struct {
Method string `json:"method"`
Path string `json:"path"`
Query string `json:"query"`
Headers map[string]string `json:"headers,omitempty"`
ResponseStatus int `json:"response_status"`
Duration time.Duration `json:"duration_ms"`
Memory int64 `json:"memory,omitempty"`
}
RequestContent holds request/response data.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds telescope entries in a ring buffer.
func (*Store) EnableOnly ¶
EnableOnly enables recording only for the given entry types. If no types are provided, all entry types are enabled.
func (*Store) LoadLatestFromBackend ¶
func (*Store) PruneBefore ¶
func (*Store) SetPersistBackend ¶
func (s *Store) SetPersistBackend(p persistBackend)
Source Files