Documentation
¶
Index ¶
- Constants
- func Aggregate(component, key string, fields ...slog.Attr)
- func DumpRingBuffer(path string) error
- func ForComponent(name string) *slog.Logger
- func Init(cfg Config)
- func IsDebugEnabled() bool
- func Logger() *slog.Logger
- func Shutdown()
- func TraceOp(logger *slog.Logger, op string, warnThreshold time.Duration, ...) func()
- type Aggregator
- type BridgeWriter
- type Config
- type RingBuffer
- type SlowOpDetector
Constants ¶
const ( CompStatus = "status" CompMCP = "mcp" CompNotif = "notif" CompPerf = "perf" CompUI = "ui" CompSession = "session" CompStorage = "storage" CompPool = "pool" CompHTTP = "http" CompWeb = "web" CompWatcher = "watcher" )
Component constants for structured logging.
Variables ¶
This section is empty.
Functions ¶
func DumpRingBuffer ¶
DumpRingBuffer writes the ring buffer contents to a file.
func ForComponent ¶
ForComponent returns a sub-logger with the component field set. Uses a dynamicHandler so that loggers created before Init() (e.g., as package-level vars) will correctly use the real handler once Init() runs.
func Init ¶
func Init(cfg Config)
Init initializes the global logging system. When debug is false and no log dir is provided, logs are discarded.
func IsDebugEnabled ¶ added in v0.26.1
func IsDebugEnabled() bool
IsDebugEnabled returns true if debug mode was enabled during Init. Lock-free atomic read, safe for hot paths.
func TraceOp ¶ added in v0.26.1
func TraceOp(logger *slog.Logger, op string, warnThreshold time.Duration, attrs ...slog.Attr) func()
TraceOp starts a timed span for a named operation. Call the returned function to finish the span. If elapsed exceeds warnThreshold, logs at Warn level; otherwise logs at Debug level. Returns a zero-cost no-op when debug is off.
Usage:
finish := logging.TraceOp(myLog, "capture_pane", 200*time.Millisecond,
slog.String("session", name))
defer finish()
Types ¶
type Aggregator ¶
type Aggregator struct {
// contains filtered or unexported fields
}
Aggregator batches high-frequency events and emits summaries periodically.
func NewAggregator ¶
func NewAggregator(logger *slog.Logger, intervalSecs int) *Aggregator
NewAggregator creates an aggregator that flushes every intervalSecs seconds. If logger is nil, recorded events are silently dropped.
func (*Aggregator) Record ¶
func (a *Aggregator) Record(component, event string, fields ...slog.Attr)
Record increments the counter for an event type. fields are kept from the most recent call (last-writer-wins for context).
func (*Aggregator) Start ¶
func (a *Aggregator) Start()
Start begins the background flush goroutine.
func (*Aggregator) Stop ¶
func (a *Aggregator) Stop()
Stop flushes remaining entries and stops the background goroutine.
type BridgeWriter ¶
type BridgeWriter struct {
// contains filtered or unexported fields
}
BridgeWriter wraps slog as an io.Writer so that legacy log.Printf calls flow through the structured logging system. It parses the common "[CATEGORY] message" prefix pattern used throughout agent-deck and extracts the category into a structured "component" field.
func NewBridgeWriter ¶
func NewBridgeWriter(defaultComponent string) *BridgeWriter
NewBridgeWriter creates a writer that forwards writes to slog. The defaultComponent is used when no [CATEGORY] prefix is found.
type Config ¶
type Config struct {
// LogDir is the directory for log files (e.g. ~/.agent-deck)
LogDir string
// Level is the minimum log level: "debug", "info", "warn", "error"
Level string
// Format is "json" (default) or "text"
Format string
// MaxSizeMB is the max size in MB before rotation (default: 10)
MaxSizeMB int
// MaxBackups is rotated files to keep (default: 5)
MaxBackups int
// MaxAgeDays is days to keep rotated files (default: 10)
MaxAgeDays int
// Compress rotated files (default: true)
Compress bool
// RingBufferSize is the in-memory ring buffer size in bytes (default: 10MB)
RingBufferSize int
// AggregateIntervalSecs is the aggregation flush interval (default: 30)
AggregateIntervalSecs int
// PprofEnabled starts pprof server on localhost:6060
PprofEnabled bool
// Debug indicates whether debug mode is active
Debug bool
}
Config holds logging configuration.
type RingBuffer ¶
type RingBuffer struct {
// contains filtered or unexported fields
}
RingBuffer is a thread-safe circular byte buffer. It implements io.Writer and silently overwrites old data when full.
func NewRingBuffer ¶
func NewRingBuffer(size int) *RingBuffer
NewRingBuffer creates a ring buffer with the given capacity in bytes.
func (*RingBuffer) Bytes ¶
func (rb *RingBuffer) Bytes() []byte
Bytes returns the buffer contents in chronological order.
func (*RingBuffer) DumpToFile ¶
func (rb *RingBuffer) DumpToFile(path string) error
DumpToFile writes the ring buffer contents to a file in chronological order.
type SlowOpDetector ¶ added in v0.26.1
type SlowOpDetector struct {
// contains filtered or unexported fields
}
SlowOpDetector tracks in-flight operations and logs warnings when any operation exceeds a configured threshold. The detector runs a background goroutine that periodically scans for stuck operations. Zero cost when debug mode is off.
func NewSlowOpDetector ¶ added in v0.26.1
func NewSlowOpDetector(threshold, checkInterval time.Duration) *SlowOpDetector
NewSlowOpDetector creates a detector that checks for stuck operations every checkInterval. Operations exceeding threshold trigger a Warn log. Returns nil if debug mode is off.
func SlowOps ¶ added in v0.26.1
func SlowOps() *SlowOpDetector
SlowOps returns the global slow-operation detector. Returns nil when debug is off.
func (*SlowOpDetector) Finish ¶ added in v0.26.1
func (d *SlowOpDetector) Finish(id uint64)
Finish marks an operation as complete and removes it from tracking.
func (*SlowOpDetector) Start ¶ added in v0.26.1
func (d *SlowOpDetector) Start(name string, attrs ...slog.Attr) uint64
Start begins tracking a named operation. Returns an ID to pass to Finish.
func (*SlowOpDetector) Stop ¶ added in v0.26.1
func (d *SlowOpDetector) Stop()
Stop shuts down the background goroutine.
Source Files