log

package
v1.23.1 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

README

Stapler Squad Logging System

This package implements a configurable logging system for Stapler Squad with the following features:

Key Features

  • Configurable Log Location: Logs are stored in ~/.stapler-squad/logs/ by default, but this can be changed in the config.
  • Global and Session-Specific Logs: Separate log files are created for each session.
  • Log Rotation: Logs are automatically rotated based on size and age.
  • Configuration Options: Several options can be configured in ~/.stapler-squad/config.json

Configuration

The following logging options can be configured in config.json:

{
  "logs_enabled": true,
  "logs_dir": "",  // Empty for default location (~/.stapler-squad/logs/)
  "log_max_size": 10,  // Max log file size in MB before rotation
  "log_max_files": 5,  // Max number of rotated files to keep
  "log_max_age": 30,  // Max age in days for rotated files
  "log_compress": true,  // Whether to compress rotated files
  "use_session_logs": true  // Whether to create separate log files for each session
}

Usage

Global Logging

The global loggers (InfoLog, WarningLog, and ErrorLog) can be used directly:

log.InfoLog.Printf("This is an info message")
log.WarningLog.Printf("This is a warning message")
log.ErrorLog.Printf("This is an error message")
Session-Specific Logging

For session-specific logging, use the LogForSession function:

// Log to session-specific file and global log
log.LogForSession("session-id", "info", "This is an info message for session %s", "session-id")
log.LogForSession("session-id", "warning", "This is a warning message for session %s", "session-id")
log.LogForSession("session-id", "error", "This is an error message for session %s", "session-id")

Implementation Details

  • Log files are stored in ~/.stapler-squad/logs/ by default
  • Global log file is named claudesquad.log
  • Session log files are named session_<session-id>.log
  • Log rotation is implemented using the lumberjack package
  • Logs are rotated when they reach the configured size
  • Old log files are compressed if the log_compress option is enabled

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	WarningLog *log.Logger
	InfoLog    *log.Logger
	ErrorLog   *log.Logger
	DebugLog   *log.Logger
)
View Source 
var (
	// ErrSessionLogsDisabled is returned when session logs are disabled in config
	ErrSessionLogsDisabled = fmt.Errorf("session logs disabled in config")
)

Functions

func Close 

func Close()

func DebugS 

func DebugS(message string, fields ...map[string]interface{})

DebugS logs a structured debug message

func ErrorS 

func ErrorS(message string, fields ...map[string]interface{})

ErrorS logs a structured error message

func FatalS 

func FatalS(message string, fields ...map[string]interface{})

FatalS logs a structured fatal message

func GetActiveSessionLogPaths 

func GetActiveSessionLogPaths() map[string]string

GetActiveSessionLogPaths returns the paths to all active session log files

func GetConfigDir 

func GetConfigDir() (string, error)

GetConfigDir returns the path to the application's configuration directory

func GetGlobalLogPath 

func GetGlobalLogPath() string

GetGlobalLogPath returns the path to the global log file

func GetLogDir 

func GetLogDir(cfg *LogConfig) (string, error)

GetLogDir returns the directory where logs should be stored

func GetLogFilePath 

func GetLogFilePath(cfg *LogConfig) (string, error)

GetLogFilePath returns the full path to the log file

func GetSessionLogFilePath 

func GetSessionLogFilePath(cfg *LogConfig, sessionID string) (string, error)

GetSessionLogFilePath returns the full path to a session-specific log file

func GetTestLogDir 

func GetTestLogDir() (string, error)

GetTestLogDir returns the directory where test logs should be stored Test logs are isolated in a dedicated subdirectory for easy cleanup

func InfoS 

func InfoS(message string, fields ...map[string]interface{})

InfoS logs a structured info message

func Initialize 

func Initialize(daemon bool)

func InitializeForTests 

func InitializeForTests(fileLevel LogLevel, consoleLevel LogLevel)

InitializeForTests sets up logging specifically for test environments with dual-stream configuration. This allows DEBUG logs to go to file while ERROR logs appear in console for immediate visibility.

Parameters:

  • fileLevel: Minimum level for file logging (typically DEBUG to capture everything)
  • consoleLevel: Minimum level for console logging (typically ERROR to avoid noise)

Example: 

log.InitializeForTests(log.DEBUG, log.ERROR)  // DEBUG→file, ERROR→console

func InitializeWithConfig 

func InitializeWithConfig(daemon bool, externalConfig interface{})

InitializeWithConfig sets up logging with the provided configuration.

func LogForSession 

func LogForSession(sessionID, level, format string, v ...interface{})

LogForSession logs a message to the session-specific log file

func LogSessionPathsToStderr 

func LogSessionPathsToStderr()

LogSessionPathsToStderr outputs session log file paths to stderr on exit

func WarningS 

func WarningS(message string, fields ...map[string]interface{})

WarningS logs a structured warning message

Types

type Every 

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

Every is used to log at most once every timeout duration.

func NewEvery 

func NewEvery(timeout time.Duration) *Every

func (*Every) ShouldLog 

func (e *Every) ShouldLog() bool

ShouldLog returns true if the timeout has passed since the last log.

type LogConfig 

type LogConfig struct {
	LogsEnabled    bool
	LogsDir        string
	LogMaxSize     int
	LogMaxFiles    int
	LogMaxAge      int
	LogCompress    bool
	UseSessionLogs bool
	LogLevel       LogLevel // Deprecated: Use FileLevel and ConsoleLevel instead
	StructuredLogs bool
	PrettyLogs     bool // For development - formats JSON logs for readability

	// Dual-stream logging configuration (file + console)
	ConsoleEnabled bool     // Enable/disable console output (default: true)
	ConsoleLevel   LogLevel // Minimum level for console (default: ERROR for tests, INFO for production)
	FileEnabled    bool     // Enable/disable file output (default: true)
	FileLevel      LogLevel // Minimum level for file (default: DEBUG)
}

LogConfig holds logging configuration

func ConfigToLogConfig 

func ConfigToLogConfig(externalConfig interface{}) *LogConfig

ConfigToLogConfig converts an external config to our internal LogConfig

func DefaultLogConfig 

func DefaultLogConfig() *LogConfig

DefaultLogConfig returns the default logging configuration

type LogLevel 

type LogLevel int

LogLevel represents the severity of a log entry 

const (
	DEBUG LogLevel = iota
	INFO
	WARNING
	ERROR
	FATAL
)

func ParseLogLevel 

func ParseLogLevel(level string) LogLevel

ParseLogLevel parses a string into a LogLevel

func (LogLevel) String 

func (l LogLevel) String() string

String returns the string representation of a log level

type SessionLogger added in v1.15.0 

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

SessionLogger is a session-scoped logger that automatically injects the session ID into every log call, eliminating the need to pass the session ID manually.

Usage: 

logger := log.ForSession(i.Title)
logger.Error("Failed to setup git worktree: %v", err)

func ForSession added in v1.15.0 

func ForSession(sessionID string) *SessionLogger

ForSession returns a SessionLogger bound to the given session ID.

func (*SessionLogger) Debug added in v1.15.0 

func (sl *SessionLogger) Debug(format string, v ...interface{})

func (*SessionLogger) Error added in v1.15.0 

func (sl *SessionLogger) Error(format string, v ...interface{})

func (*SessionLogger) Info added in v1.15.0 

func (sl *SessionLogger) Info(format string, v ...interface{})

func (*SessionLogger) Warning added in v1.15.0 

func (sl *SessionLogger) Warning(format string, v ...interface{})

type SessionLoggers 

type SessionLoggers struct {
	WarningLog *log.Logger
	InfoLog    *log.Logger
	ErrorLog   *log.Logger
	DebugLog   *log.Logger
	LogFile    io.Closer
}

SessionLoggers holds the loggers for a specific session

func GetSessionLoggers 

func GetSessionLoggers(sessionID string) (*SessionLoggers, error)

GetSessionLoggers creates or retrieves loggers for a specific session

type StructuredLogEntry 

type StructuredLogEntry struct {
	Timestamp time.Time              `json:"timestamp"`
	Level     string                 `json:"level"`
	Message   string                 `json:"message"`
	SessionID string                 `json:"session_id,omitempty"`
	Component string                 `json:"component,omitempty"`
	Function  string                 `json:"function,omitempty"`
	File      string                 `json:"file,omitempty"`
	Line      int                    `json:"line,omitempty"`
	Fields    map[string]interface{} `json:"fields,omitempty"`
	Error     string                 `json:"error,omitempty"`
}

StructuredLogEntry represents a structured log entry

type StructuredLogger 

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

StructuredLogger provides structured logging functionality

func NewStructuredLogger 

func NewStructuredLogger(writer io.Writer, level LogLevel, prettyLog bool) *StructuredLogger

NewStructuredLogger creates a new structured logger

func (*StructuredLogger) Debug 

func (sl *StructuredLogger) Debug(message string, fields ...map[string]interface{})

Debug logs a debug message

func (*StructuredLogger) Error 

func (sl *StructuredLogger) Error(message string, fields ...map[string]interface{})

Error logs an error message

func (*StructuredLogger) Fatal 

func (sl *StructuredLogger) Fatal(message string, fields ...map[string]interface{})

Fatal logs a fatal message

func (*StructuredLogger) Info 

func (sl *StructuredLogger) Info(message string, fields ...map[string]interface{})

Info logs an info message

func (*StructuredLogger) Log 

func (sl *StructuredLogger) Log(level LogLevel, message string, fields map[string]interface{})

Log writes a structured log entry

func (*StructuredLogger) LogWithFields 

func (sl *StructuredLogger) LogWithFields(level LogLevel, message string, fields map[string]interface{})

LogWithFields logs a message with additional fields

func (*StructuredLogger) Warning 

func (sl *StructuredLogger) Warning(message string, fields ...map[string]interface{})

Warning logs a warning message

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.