Pulse — Production Monitoring

Pulse is a lightweight production-grade monitoring plugin for Nimbus. It captures request performance with percentile stats, cache hit rates, queue throughput, exception tracking, and slow query detection — all without external dependencies.

§ Overview

Unlike Telescope (which stores individual entries as a debug tool), Pulse aggregates metrics designed for production use:

§ Installation

$ nimbus plugin:install pulse

Or add manually:

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

app.Use(pulse.NewPlugin())

Access the dashboard at http://localhost:3000/pulse.

§ Configuration

package config

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

var Pulse = pulse.Config{
    // Dashboard path (default: "/pulse")
    Path:  "/pulse",

    // Enable/disable (default: true)
    Enabled: true,

    // Slow query threshold (queries slower than this are flagged)
    SlowQueryThreshold: 100 * time.Millisecond, // default: 100ms

    // Maximum recent exceptions to keep
    MaxExceptions: 50,

    // Maximum slow queries to keep
    MaxSlowQueries: 50,

    // Request stats retention periods
    // Stats are auto-bucketed into 1h, 6h, 24h, and 7d windows
}

§ Request Performance

Pulse's request middleware automatically captures every HTTP request and computes rolling percentile statistics:

Stats are bucketed into four retention periods:

• 1 hour — Granular real-time view
• 6 hours — Short-term trends
• 24 hours — Daily performance overview
• 7 days — Weekly trends

§ Cache Statistics

Track how effectively your application uses the cache layer:

// Automatically tracked by the cache subsystem:
// - Hits  (cache key found)
// - Misses (cache key not found)
// - Writes (cache key set/put)

// The dashboard shows hit rate as a percentage:
// Hit Rate = Hits / (Hits + Misses) × 100

§ Queue Statistics

Monitor job throughput and failure rates:

// Tracked metrics:
pulse.RecordJob(true)   // processed successfully
pulse.RecordJob(false)  // job failed

// Dashboard displays:
// - Jobs Processed (total)
// - Jobs Failed (total)
// - Success Rate percentage

§ Exception Tracking

Pulse captures and groups exceptions with occurrence counts:

// Record an exception
pulse.RecordException(err)

// Each exception record includes:
// - Error type (reflect.TypeOf)
// - Error message
// - Occurrence count (auto-incremented for duplicates)
// - First seen / Last seen timestamps

Duplicate exceptions are grouped by error type + message, keeping the recent list compact and actionable.

§ Slow Query Detection

Database queries exceeding the configured threshold are captured with full SQL:

// Queries slower than SlowQueryThreshold (default: 100ms) are flagged
pulse.RecordSlowQuery("SELECT * FROM users WHERE...", 
    250*time.Millisecond)

// Each slow query record:
// - SQL statement
// - Duration (ms)
// - Timestamp

§ Dashboard API

§ Pulse vs Telescope