pulse

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 10 Imported by: 0

README

Pulse Plugin for Nimbus

Pulse is a lightweight production-friendly monitoring plugin for Nimbus. It tracks aggregated request, query, queue, cache, and exception metrics.

Install

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

app.Use(pulse.NewPlugin())

Routes

  • GET /pulse — dashboard page
  • GET /pulse/metrics — JSON metrics snapshot
  • GET /pulse/entries — recent ring-buffer entries

Middleware

Use the named middleware pulse (registered by the plugin) to record request timing:

app.Router.Use(app.NamedMiddleware("pulse"))

Or wire directly if needed:

p := pulse.NewPlugin()
app.Router.Use(p.Pulse.Middleware())

Configuration

Defaults from DefaultConfig():

  • max_entries: 10000
  • slow_query_threshold: 100ms
  • slow_request_threshold: 500ms

Use pulse.NewPlugin(pulse.Config{...}) for custom thresholds.

Documentation

Overview

Package pulse provides lightweight application monitoring for Nimbus applications. It collects metrics on requests, slow queries, exceptions, queue throughput, and cache hit rates with minimal overhead.

Unlike Telescope which records every request, Pulse uses aggregated metrics and ring buffers suitable for production use. 

p := pulse.New(pulse.Config{MaxEntries: 10000})
app.Use(p.Middleware())
app.GET("/pulse", p.DashboardHandler())

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CacheStats 

type CacheStats struct {
	Hits    int64   `json:"hits"`
	Misses  int64   `json:"misses"`
	Writes  int64   `json:"writes"`
	Deletes int64   `json:"deletes"`
	HitRate float64 `json:"hit_rate"`
}

CacheStats holds cache hit/miss statistics.

type Config 

type Config struct {
	// MaxEntries is the maximum number of entries to keep in each ring buffer.
	MaxEntries int
	// SlowQueryThreshold marks queries slower than this as "slow" (default: 100ms).
	SlowQueryThreshold time.Duration
	// SlowRequestThreshold marks requests slower than this as "slow" (default: 500ms).
	SlowRequestThreshold time.Duration
}

Config holds Pulse configuration options.

type Entry 

type Entry struct {
	Type      EntryType      `json:"type"`
	Timestamp time.Time      `json:"timestamp"`
	Duration  time.Duration  `json:"duration_ms"`
	Data      map[string]any `json:"data"`
}

Entry is a single monitoring record.

type EntryType 

type EntryType string

EntryType identifies the kind of monitoring entry. 

const (
	EntryRequest   EntryType = "request"
	EntrySlowQuery EntryType = "slow_query"
	EntryException EntryType = "exception"
	EntryJob       EntryType = "job"
	EntryCache     EntryType = "cache"
	EntryMail      EntryType = "mail"
)

type MySQLTimestampCol 

type MySQLTimestampCol struct {
	Table      string  `json:"table"`
	Column     string  `json:"column"`
	ColumnType string  `json:"column_type"`
	IsNullable bool    `json:"is_nullable"`
	Default    *string `json:"default,omitempty"`
	Extra      string  `json:"extra,omitempty"`
}

type PathStat 

type PathStat struct {
	Path        string  `json:"path"`
	Count       int64   `json:"count"`
	AvgDuration float64 `json:"avg_duration_ms"`
	ErrorCount  int64   `json:"error_count"`
}

PathStat holds per-path request stats.

type Pulse 

type Pulse struct {
	// contains filtered or unexported fields
}

Pulse is the main monitoring instance.

func New 

func New(cfg Config) *Pulse

New creates a new Pulse monitoring instance.

func (*Pulse) AuditY2038 

func (p *Pulse) AuditY2038()

AuditY2038 inspects the connected MySQL schema and records any TIMESTAMP columns. Best-effort; it never panics.

func (*Pulse) DashboardHandler 

func (p *Pulse) DashboardHandler() router.HandlerFunc

DashboardHandler returns a handler that serves the Pulse monitoring dashboard as JSON (default) or a small HTML page when Accept prefers text/html.

func (*Pulse) GetCacheStats 

func (p *Pulse) GetCacheStats() CacheStats

GetCacheStats returns cache hit/miss statistics.

func (*Pulse) GetQueueStats 

func (p *Pulse) GetQueueStats() QueueStats

GetQueueStats returns queue job statistics.

func (*Pulse) GetRequestStats 

func (p *Pulse) GetRequestStats() RequestStats

GetRequestStats returns aggregated request statistics.

func (*Pulse) Middleware 

func (p *Pulse) Middleware() router.Middleware

Middleware returns a router middleware that automatically records request metrics.

func (*Pulse) RecentExceptions 

func (p *Pulse) RecentExceptions(n int) []Entry

RecentExceptions returns the most recent exceptions.

func (*Pulse) RecentRequests 

func (p *Pulse) RecentRequests(n int) []Entry

RecentRequests returns the most recent requests.

func (*Pulse) RecentSlowQueries 

func (p *Pulse) RecentSlowQueries(n int) []Entry

RecentSlowQueries returns the most recent slow queries.

func (*Pulse) RecordCacheDelete 

func (p *Pulse) RecordCacheDelete(key string)

RecordCacheDelete records a cache deletion.

func (*Pulse) RecordCacheHit 

func (p *Pulse) RecordCacheHit(key string)

RecordCacheHit records a cache hit.

func (*Pulse) RecordCacheMiss 

func (p *Pulse) RecordCacheMiss(key string)

RecordCacheMiss records a cache miss.

func (*Pulse) RecordCacheWrite 

func (p *Pulse) RecordCacheWrite(key string)

RecordCacheWrite records a cache write.

func (*Pulse) RecordException 

func (p *Pulse) RecordException(err error, context map[string]any)

RecordException records an application error.

func (*Pulse) RecordJob 

func (p *Pulse) RecordJob(name string, duration time.Duration, err error)

RecordJob records a queued job execution.

func (*Pulse) RecordMail 

func (p *Pulse) RecordMail(to, subject string, success bool)

RecordMail records a sent email.

func (*Pulse) RecordRequest 

func (p *Pulse) RecordRequest(method, path string, status int, duration time.Duration, err error)

RecordRequest records an HTTP request.

func (*Pulse) RecordSlowQuery 

func (p *Pulse) RecordSlowQuery(query string, duration time.Duration, args ...any)

RecordSlowQuery records a slow database query.

type PulsePlugin 

type PulsePlugin struct {
	nimbus.BasePlugin
	Pulse *Pulse
}

PulsePlugin wraps Pulse as a Nimbus plugin, making it installable via `nimbus plugin install pulse` and selectable during `nimbus new`.

func NewPlugin 

func NewPlugin(cfg ...Config) *PulsePlugin

NewPlugin creates a new Pulse plugin with default config.

func (*PulsePlugin) Boot 

func (p *PulsePlugin) Boot(app *nimbus.App) error

Boot is a no-op for Pulse.

func (*PulsePlugin) DefaultConfig 

func (p *PulsePlugin) DefaultConfig() map[string]any

DefaultConfig returns default Pulse configuration.

func (*PulsePlugin) Middleware 

func (p *PulsePlugin) Middleware() map[string]router.Middleware

Middleware returns named middleware for Pulse request recording.

func (*PulsePlugin) Register 

func (p *PulsePlugin) Register(app *nimbus.App) error

Register binds the Pulse instance into the container.

func (*PulsePlugin) RegisterRoutes 

func (p *PulsePlugin) RegisterRoutes(r *router.Router)

RegisterRoutes mounts the Pulse dashboard at /pulse.

type QueueStats 

type QueueStats struct {
	Processed int64   `json:"processed"`
	Failed    int64   `json:"failed"`
	Pending   int64   `json:"pending"`
	AvgTime   float64 `json:"avg_time_ms"`
}

QueueStats holds queue job statistics.

type RequestStats 

type RequestStats struct {
	TotalRequests  int64         `json:"total_requests"`
	TotalErrors    int64         `json:"total_errors"`
	AvgDuration    float64       `json:"avg_duration_ms"`
	P50Duration    float64       `json:"p50_duration_ms"`
	P95Duration    float64       `json:"p95_duration_ms"`
	P99Duration    float64       `json:"p99_duration_ms"`
	RequestsPerMin float64       `json:"requests_per_min"`
	StatusCounts   map[int]int64 `json:"status_counts"`
	SlowRequests   int64         `json:"slow_requests"`
	TopPaths       []PathStat    `json:"top_paths"`
}

RequestStats holds aggregated request statistics.

type Y2038Audit 

type Y2038Audit struct {
	Driver           string              `json:"driver"`
	TimestampColumns []MySQLTimestampCol `json:"timestamp_columns"`
	OK               bool                `json:"ok"`
	// Error is set when the audit query failed (e.g. permissions) or DB was unavailable.
	Error string `json:"error,omitempty"`
	// Skipped explains non-MySQL drivers or missing DB (informational).
	Skipped string `json:"skipped,omitempty"`
}

Y2038Audit summarizes schema timestamp risk for MySQL.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.