insights

type AppInfo struct {
	Version   string    `json:"insights"`
	Go        string    `json:"go"`
	Env       string    `json:"env"`
	StartedAt time.Time `json:"started_at"`
	UptimeSec int64     `json:"uptime_sec"`
	Now       time.Time `json:"now"`
}

type Config struct {
	// Token is the secret a reader sends as "Authorization: Bearer …".
	// Empty takes NIMBUS_INSIGHTS_TOKEN; with neither, nothing is installed.
	Token string
	// Path is the endpoint. Default /_nimbus/insights.
	Path string
	// SlowQuery and SlowRequest are what counts as slow. Defaults 100ms
	// and 500ms.
	SlowQuery   time.Duration
	SlowRequest time.Duration
	// Sample is how often memory is read. Default 10s. Reading it stops
	// the program for a moment, so it is not done on every request.
	Sample time.Duration
	// History is how many samples are kept. Default 180 (half an hour).
	History int
	// Keep is how many slow requests, slow queries and errors are kept.
	// Default 200 of each.
	Keep int
	// TrafficDir is where each day's visits are written, so they outlive a
	// restart. Default storage/insights. "-" keeps them in memory only.
	TrafficDir string
}

type Count struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

type Day struct {
	Date      string         `json:"date"` // 2026-10-09
	Views     int            `json:"views"`
	Visitors  int            `json:"visitors"`
	Hours     [24]int        `json:"hours"`
	Paths     map[string]int `json:"paths"`
	Referrers map[string]int `json:"referrers"`
	Countries map[string]int `json:"countries"`
	Devices   map[string]int `json:"devices"`
	Browsers  map[string]int `json:"browsers"`
	// Seen is the day's visitors, as the numbers they are told apart by.
	Seen []uint64 `json:"seen,omitempty"`
	// contains filtered or unexported fields
}

type DayCount struct {
	Date     string `json:"date"`
	Views    int    `json:"views"`
	Visitors int    `json:"visitors"`
}

type ErrorEntry struct {
	At      time.Time `json:"at"`
	Method  string    `json:"method"`
	Path    string    `json:"path"`
	Route   string    `json:"route"`
	Status  int       `json:"status"`
	Kind    string    `json:"kind"` // error | panic | status
	Message string    `json:"message"`
	Stack   string    `json:"stack,omitempty"`
}

type Frame struct {
	Func string `json:"func"`
	File string `json:"file"`
	Line int    `json:"line"`
}

type GoroutineGroup struct {
	Count int     `json:"count"`
	At    Frame   `json:"at"`
	Stack []Frame `json:"stack"`
}

type GoroutineReport struct {
	Total  int              `json:"total"`
	Groups []GoroutineGroup `json:"groups"`
}

type HeapReport struct {
	TotalInuseBytes int64      `json:"total_inuse_bytes"`
	Sites           []HeapSite `json:"sites"`
}

type HeapSite struct {
	InuseBytes   int64   `json:"inuse_bytes"`
	InuseObjects int64   `json:"inuse_objects"`
	AllocBytes   int64   `json:"alloc_bytes"` // since the program started
	At           Frame   `json:"at"`          // the first frame that is not the runtime's
	Stack        []Frame `json:"stack"`       // a few frames up from there
}

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

type Overview struct {
	RequestsPerMin float64 `json:"requests_per_min"`
	ErrorRate      float64 `json:"error_rate"` // share of requests answered 5xx, 0 to 1
	P50MS          float64 `json:"p50_ms"`
	P95MS          float64 `json:"p95_ms"`
	P99MS          float64 `json:"p99_ms"`
	HeapInuse      uint64  `json:"heap_inuse"`
	Sys            uint64  `json:"sys"`
	Goroutines     int     `json:"goroutines"`
	GCCPUFraction  float64 `json:"gc_cpu_fraction"`
	SlowQueries    int     `json:"slow_queries"`
	Errors         int     `json:"errors"`
	InFlight       int     `json:"in_flight"`
}

type PoolStat struct {
	Open         int     `json:"open"`
	InUse        int     `json:"in_use"`
	Idle         int     `json:"idle"`
	MaxOpen      int     `json:"max_open"`
	WaitCount    int64   `json:"wait_count"` // times a request had to wait for a connection
	WaitMS       float64 `json:"wait_ms"`
	MaxIdleClose int64   `json:"max_idle_closed"`
}

type QueryReport struct {
	Total  int         `json:"total"`
	Top    []QueryStat `json:"top"`    // most time spent first
	Slow   []SlowQuery `json:"slow"`   // newest first
	Failed []SlowQuery `json:"failed"` // newest first
	Pool   *PoolStat   `json:"pool,omitempty"`
	Driver string      `json:"driver"`
	SlowMS float64     `json:"slow_ms"`
}

type QueryStat struct {
	Shape   string    `json:"shape"` // the query with its values taken out
	Count   int       `json:"count"`
	Errors  int       `json:"errors"`
	AvgMS   float64   `json:"avg_ms"`
	MaxMS   float64   `json:"max_ms"`
	TotalMS float64   `json:"total_ms"`
	Rows    int64     `json:"rows"`   // rows it gave or changed, in all
	Caller  string    `json:"caller"` // where in the app it was last run from
	LastAt  time.Time `json:"last_at"`
}

type Repeated struct {
	Route  string    `json:"route"`
	Shape  string    `json:"shape"`  // the query with its values taken out
	Times  int       `json:"times"`  // the most it ran in one request
	Seen   int       `json:"seen"`   // in how many requests
	Caller string    `json:"caller"` // where in the app it is run from
	LastAt time.Time `json:"last_at"`
}

type Report struct {
	App        AppInfo          `json:"app"`
	Overview   *Overview        `json:"overview,omitempty"`
	Runtime    *RuntimeReport   `json:"runtime,omitempty"`
	Heap       *HeapReport      `json:"heap,omitempty"`
	Goroutines *GoroutineReport `json:"goroutines,omitempty"`
	Requests   *RequestReport   `json:"requests,omitempty"`
	Queries    *QueryReport     `json:"queries,omitempty"`
	Errors     []ErrorEntry     `json:"errors,omitempty"`
	Traffic    *TrafficReport   `json:"traffic,omitempty"`
}

type RequestReport struct {
	Total    int            `json:"total"`
	Routes   []RouteStat    `json:"routes"` // most time spent first
	Slow     []SlowRequest  `json:"slow"`   // newest first
	Status   map[string]int `json:"status"` // "2xx", "3xx", "4xx", "5xx"
	Repeated []Repeated     `json:"repeated"`
	SlowMS   float64        `json:"slow_ms"` // what counts as slow
}

type RouteStat struct {
	Route   string  `json:"route"` // "GET /posts/:id"
	Count   int     `json:"count"`
	Errors  int     `json:"errors"` // answered 5xx
	AvgMS   float64 `json:"avg_ms"`
	P95MS   float64 `json:"p95_ms"`
	MaxMS   float64 `json:"max_ms"`
	TotalMS float64 `json:"total_ms"`
	// what its requests asked of the database, on average
	Queries float64   `json:"queries"`
	QueryMS float64   `json:"query_ms"`
	LastAt  time.Time `json:"last_at"`
}

type RuntimeReport struct {
	Now          Sample   `json:"now"`
	History      []Sample `json:"history"` // oldest first
	RecentPauses []uint64 `json:"recent_pauses_ns"`
	MaxPauseNs   uint64   `json:"max_pause_ns"`
	GOMAXPROCS   int      `json:"gomaxprocs"`
	NumCPU       int      `json:"num_cpu"`
	GOGC         string   `json:"gogc"`
	MemoryLimit  int64    `json:"memory_limit"` // bytes; 0 when none is set
	// ContainerLimit is the memory the container may use (its cgroup), 0 when unknown.
	ContainerLimit uint64 `json:"container_limit"`
}

type Sample struct {
	At            time.Time `json:"at"`
	HeapAlloc     uint64    `json:"heap_alloc"`
	HeapInuse     uint64    `json:"heap_inuse"`
	HeapIdle      uint64    `json:"heap_idle"`
	HeapReleased  uint64    `json:"heap_released"`
	HeapSys       uint64    `json:"heap_sys"`
	HeapObjects   uint64    `json:"heap_objects"`
	StackInuse    uint64    `json:"stack_inuse"`
	Sys           uint64    `json:"sys"`
	NextGC        uint64    `json:"next_gc"`
	NumGC         uint32    `json:"num_gc"`
	PauseTotalNs  uint64    `json:"pause_total_ns"`
	GCCPUFraction float64   `json:"gc_cpu_fraction"`
	Mallocs       uint64    `json:"mallocs"`
	Frees         uint64    `json:"frees"`
	TotalAlloc    uint64    `json:"total_alloc"`
	Goroutines    int       `json:"goroutines"`
	// since the sample before: collections, time paused in them, bytes
	// allocated, requests answered and their slowest
	GCs       uint32  `json:"gcs"`
	PauseNs   uint64  `json:"pause_ns"`
	AllocRate uint64  `json:"alloc_rate"` // bytes a second
	Requests  int     `json:"requests"`
	Errors    int     `json:"errors"`
	P95MS     float64 `json:"p95_ms"`
}

type SlowQuery struct {
	At     time.Time `json:"at"`
	SQL    string    `json:"sql"` // as it was run, values and all
	Shape  string    `json:"shape"`
	MS     float64   `json:"ms"`
	Rows   int64     `json:"rows"`
	Caller string    `json:"caller"`
	Error  string    `json:"error,omitempty"`
}

type SlowRequest struct {
	At      time.Time `json:"at"`
	Method  string    `json:"method"`
	Path    string    `json:"path"`
	Route   string    `json:"route"`
	Status  int       `json:"status"`
	MS      float64   `json:"ms"`
	Queries int       `json:"queries"`
	QueryMS float64   `json:"query_ms"`
}

type TrafficReport struct {
	Days      []DayCount `json:"days"` // oldest first, a day with no visit included
	Views     int        `json:"views"`
	Visitors  int        `json:"visitors"` // the days' visitors added up
	Today     DayCount   `json:"today"`
	Hours     [24]int    `json:"hours"` // today, by hour (UTC)
	Paths     []Count    `json:"paths"`
	Referrers []Count    `json:"referrers"`
	Countries []Count    `json:"countries"`
	Devices   []Count    `json:"devices"`
	Browsers  []Count    `json:"browsers"`
	Kept      bool       `json:"kept"` // written to disk, so it outlives a restart
}