Documentation
¶
Overview ¶
Package godevtool is a comprehensive developer debugging toolkit for Go applications.
It provides structured logging, variable inspection, performance profiling, HTTP request/response monitoring, goroutine tracking, memory analysis, database query logging, event timelines, configuration viewing, error tracking, and a real-time web dashboard -- all with zero external dependencies.
Quick Start ¶
dt := godevtool.New(
godevtool.WithAppName("myapp"),
godevtool.WithLogLevel(godevtool.LevelDebug),
)
defer dt.Shutdown()
// Structured logging
dt.Log.Info("server starting", "port", 8080)
// Variable inspection
dt.Inspect(myStruct)
// Execution timing
defer dt.Timer("db-query").Stop()
// Web dashboard
dt.StartDashboard(":9999")
Architecture ¶
The DevTool struct is the central facade that wires together 26 specialized packages. Each package can be used independently, but the facade provides a unified API and connects everything to the web dashboard for real-time visualization.
All features are designed to be zero-overhead when disabled via DevTool.Disable.
Packages ¶
Core debugging:
- log - Structured, colorized logging with key-value pairs
- inspect - Pretty-print any Go value with type information
- timer - Execution timing with aggregate statistics
- stack - Stack trace capture and formatting
Runtime monitoring:
- middleware - HTTP request/response capture
- goroutine - Goroutine count tracking and leak detection
- memstats - Memory and GC statistics collection
Advanced tracing:
- dblog - Database query logging with sql.DB wrapping
- timeline - Event timeline with point-in-time events and spans
- config - Configuration viewer with field redaction
Environment awareness:
- environ - Go version, OS, build info, hostname detection
- deps - Module dependency scanning
- errtrack - Error tracking, grouping, and panic recovery
- profiler - On-demand pprof profile capture
Performance intelligence:
- httptrace - Outgoing HTTP request tracing with timing breakdown
- cachemon - Cache hit/miss/eviction monitoring
- ratelimit - Rate limiter decision tracking
- bench - Micro-benchmarking with percentile statistics
Developer experience:
Index ¶
- Constants
- type DevTool
- func (d *DevTool) AddAlertRule(rule alerts.Rule)
- func (d *DevTool) AlertEngine() *alerts.Engine
- func (d *DevTool) AlertOnGoroutineCount(threshold int)
- func (d *DevTool) AlertOnHeapAlloc(thresholdBytes uint64)
- func (d *DevTool) BenchRunner() *bench.Runner
- func (d *DevTool) Benchmark(label string, n int, fn func()) bench.Result
- func (d *DevTool) CacheMonitor() *cachemon.Monitor
- func (d *DevTool) CaptureCPUProfile(duration time.Duration) (*profiler.Profile, error)
- func (d *DevTool) CaptureHeapProfile() (*profiler.Profile, error)
- func (d *DevTool) Config() *config.Viewer
- func (d *DevTool) DBLogger() *dblog.Logger
- func (d *DevTool) Dependencies() deps.ScanResult
- func (d *DevTool) Disable()
- func (d *DevTool) Enable()
- func (d *DevTool) Environ() environ.Info
- func (d *DevTool) ErrorTracker() *errtrack.Tracker
- func (d *DevTool) ExportHTML() ([]byte, error)
- func (d *DevTool) ExportJSON() ([]byte, error)
- func (d *DevTool) ExportToFile(path, format string) error
- func (d *DevTool) GRPCMonitor() *grpcmon.Monitor
- func (d *DevTool) GoroutineLeakCheck() []goroutine.GoroutineInfo
- func (d *DevTool) GoroutineSnapshot() goroutine.Snapshot
- func (d *DevTool) HTTPTracer() *httptrace.Tracer
- func (d *DevTool) HotReloadState() hotreload.State
- func (d *DevTool) Inspect(v any) string
- func (d *DevTool) InspectTo(w io.Writer, v any) string
- func (d *DevTool) MemSnapshot() memstats.Snapshot
- func (d *DevTool) Middleware() *middleware.Inspector
- func (d *DevTool) PrintConfig()
- func (d *DevTool) PrintDependencies()
- func (d *DevTool) PrintEnviron()
- func (d *DevTool) PrintErrorStats()
- func (d *DevTool) PrintGoroutines()
- func (d *DevTool) PrintMemStats()
- func (d *DevTool) PrintStack()
- func (d *DevTool) PrintTimeline(n int)
- func (d *DevTool) PrintTimerReport()
- func (d *DevTool) Profiler() *profiler.Profiler
- func (d *DevTool) RateLimitMonitor() *ratelimit.Monitor
- func (d *DevTool) RecoverMiddleware(next http.Handler) http.Handler
- func (d *DevTool) RegisterCache(name string) *cachemon.Recorder
- func (d *DevTool) RegisterConfig(name string, cfg any, sources ...map[string]string)
- func (d *DevTool) RegisterRateLimiter(name string) *ratelimit.Recorder
- func (d *DevTool) Shutdown()
- func (d *DevTool) Stack(skip int) string
- func (d *DevTool) StartAlerts(interval time.Duration)
- func (d *DevTool) StartDashboard(addr string) error
- func (d *DevTool) StartGoroutineMonitor(interval time.Duration)
- func (d *DevTool) StartHotReload(opts ...hotreload.Option) error
- func (d *DevTool) StartMemStats(interval time.Duration)
- func (d *DevTool) StopAlerts()
- func (d *DevTool) StopDashboard() error
- func (d *DevTool) StopGoroutineMonitor()
- func (d *DevTool) StopHotReload()
- func (d *DevTool) StopMemStats()
- func (d *DevTool) Timeline() *timeline.Timeline
- func (d *DevTool) TimelineRecord(category, label string, data map[string]any) string
- func (d *DevTool) TimelineStart(category, label string, data map[string]any) *timeline.Span
- func (d *DevTool) Timer(label string) *timer.Timer
- func (d *DevTool) TimerReport() *timer.Report
- func (d *DevTool) TrackError(err error, data ...map[string]any)
- func (d *DevTool) WrapHTTPClient(client *http.Client) *http.Client
- type Option
Constants ¶
const ( LevelDebug = log.LevelDebug LevelInfo = log.LevelInfo LevelWarn = log.LevelWarn LevelError = log.LevelError )
Re-export log levels for convenience.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DevTool ¶
DevTool is the central handle for all debugging facilities. It is safe for concurrent use.
func (*DevTool) AddAlertRule ¶
AddAlertRule registers an alert rule.
func (*DevTool) AlertEngine ¶
AlertEngine returns the alert rules engine.
func (*DevTool) AlertOnGoroutineCount ¶
AlertOnGoroutineCount adds a rule that fires when goroutine count exceeds threshold.
func (*DevTool) AlertOnHeapAlloc ¶
AlertOnHeapAlloc adds a rule that fires when heap allocation exceeds threshold bytes.
func (*DevTool) BenchRunner ¶
BenchRunner returns the benchmark runner.
func (*DevTool) CacheMonitor ¶
CacheMonitor returns the cache monitor.
func (*DevTool) CaptureCPUProfile ¶
CaptureCPUProfile captures a CPU profile for the given duration.
func (*DevTool) CaptureHeapProfile ¶
CaptureHeapProfile captures a heap profile snapshot.
func (*DevTool) DBLogger ¶
DBLogger returns the database query logger. Use dblog.WrapDB(db, dt.DBLogger()) to wrap a *sql.DB.
func (*DevTool) Dependencies ¶
func (d *DevTool) Dependencies() deps.ScanResult
Dependencies returns the module dependency scan result.
func (*DevTool) Disable ¶
func (d *DevTool) Disable()
Disable turns off all output. All methods become no-ops.
func (*DevTool) ErrorTracker ¶
ErrorTracker returns the error tracker.
func (*DevTool) ExportHTML ¶
ExportHTML captures a full debug snapshot as a self-contained HTML report.
func (*DevTool) ExportJSON ¶
ExportJSON captures a full debug snapshot as JSON.
func (*DevTool) ExportToFile ¶
ExportToFile writes a debug snapshot to a file.
func (*DevTool) GRPCMonitor ¶
GRPCMonitor returns the gRPC call monitor.
func (*DevTool) GoroutineLeakCheck ¶
func (d *DevTool) GoroutineLeakCheck() []goroutine.GoroutineInfo
GoroutineLeakCheck returns suspected goroutine leaks.
func (*DevTool) GoroutineSnapshot ¶
GoroutineSnapshot returns the current goroutine snapshot.
func (*DevTool) HTTPTracer ¶
HTTPTracer returns the HTTP client tracer.
func (*DevTool) HotReloadState ¶
HotReloadState returns the current hot reload state.
func (*DevTool) Inspect ¶
Inspect pretty-prints any Go value to the configured output. Returns the formatted string.
func (*DevTool) MemSnapshot ¶
MemSnapshot returns the current memory snapshot.
func (*DevTool) Middleware ¶
func (d *DevTool) Middleware() *middleware.Inspector
Middleware returns the HTTP request/response inspector.
func (*DevTool) PrintConfig ¶
func (d *DevTool) PrintConfig()
PrintConfig prints all registered configurations to the configured output.
func (*DevTool) PrintDependencies ¶
func (d *DevTool) PrintDependencies()
PrintDependencies prints dependencies to the configured output.
func (*DevTool) PrintEnviron ¶
func (d *DevTool) PrintEnviron()
PrintEnviron prints environment info to the configured output.
func (*DevTool) PrintErrorStats ¶
func (d *DevTool) PrintErrorStats()
PrintErrorStats prints error statistics to the configured output.
func (*DevTool) PrintGoroutines ¶
func (d *DevTool) PrintGoroutines()
PrintGoroutines prints the current goroutine state to output.
func (*DevTool) PrintMemStats ¶
func (d *DevTool) PrintMemStats()
PrintMemStats prints the current memory statistics to output.
func (*DevTool) PrintStack ¶
func (d *DevTool) PrintStack()
PrintStack prints a prettified stack trace to the configured output.
func (*DevTool) PrintTimeline ¶
PrintTimeline prints recent timeline events to the configured output.
func (*DevTool) PrintTimerReport ¶
func (d *DevTool) PrintTimerReport()
PrintTimerReport writes the timing report table to the configured output.
func (*DevTool) RateLimitMonitor ¶
RateLimitMonitor returns the rate limiter monitor.
func (*DevTool) RecoverMiddleware ¶
RecoverMiddleware returns an HTTP handler that recovers panics and tracks them.
func (*DevTool) RegisterCache ¶
RegisterCache creates a named cache tracker.
func (*DevTool) RegisterConfig ¶
RegisterConfig adds a named configuration struct for display on the dashboard. Fields tagged `devtool:"redact"` will have their values masked.
func (*DevTool) RegisterRateLimiter ¶
RegisterRateLimiter creates a named rate limiter tracker.
func (*DevTool) Shutdown ¶
func (d *DevTool) Shutdown()
Shutdown stops all background monitors and the dashboard gracefully.
func (*DevTool) StartAlerts ¶
StartAlerts begins periodic alert rule evaluation.
func (*DevTool) StartDashboard ¶
StartDashboard starts the web dashboard on the given address (e.g. ":9999"). It wires all subsystems into the dashboard for real-time visualization.
func (*DevTool) StartGoroutineMonitor ¶
StartGoroutineMonitor begins tracking goroutines at the given interval.
func (*DevTool) StartHotReload ¶
StartHotReload begins file watching and auto-rebuild.
func (*DevTool) StartMemStats ¶
StartMemStats begins collecting memory/GC statistics at the given interval.
func (*DevTool) StopDashboard ¶
StopDashboard stops the web dashboard server.
func (*DevTool) StopGoroutineMonitor ¶
func (d *DevTool) StopGoroutineMonitor()
StopGoroutineMonitor stops goroutine tracking.
func (*DevTool) StopHotReload ¶
func (d *DevTool) StopHotReload()
StopHotReload stops the file watcher.
func (*DevTool) StopMemStats ¶
func (d *DevTool) StopMemStats()
StopMemStats stops memory statistics collection.
func (*DevTool) TimelineRecord ¶
TimelineRecord adds a point-in-time event to the timeline.
func (*DevTool) TimelineStart ¶
TimelineStart begins a span on the timeline. Call span.End() to complete it.
func (*DevTool) Timer ¶
Timer returns a started Timer. Call Stop() (typically via defer) to record elapsed time.
defer d.Timer("db-query").Stop()
func (*DevTool) TimerReport ¶
TimerReport returns the aggregate timing report.
func (*DevTool) TrackError ¶
TrackError records an error occurrence.
type Option ¶
type Option func(*options)
Option configures a DevTool instance.
func WithAppName ¶
WithAppName sets an application name prefix for log lines.
func WithLogLevel ¶
WithLogLevel sets the minimum log level.
func WithMaxDepth ¶
WithMaxDepth sets the maximum recursion depth for Inspect.
func WithOutput ¶
WithOutput sets the writer for all devtool output.
func WithTimeFormat ¶
WithTimeFormat sets the timestamp format (Go reference time layout).
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
basic
command
|
|
|
full-dashboard
command
|
|
|
http-server
command
|
|
|
internal
|
|