Documentation
¶
Overview ¶
- **Workflow**: Workflow execution and management
- **Agent**: MCP agent and client operations
- **TUI**: Terminal user interface operations
- **API**: API layer operations and handler management
Integration with slog ¶
The logging system integrates with Go's standard slog package:
- Uses slog.Handler implementations for output formatting
- Converts custom LogLevel to slog.Level for compatibility
- Supports slog.Attr for structured logging attributes
- Provides fallback to global slog logger when needed
Error Handling and Reliability ¶
The logging system handles various failure scenarios:
## Channel Overflow (TUI Mode)
- Non-blocking channel sends with fallback to stderr
- Buffer size configuration to prevent overflow
- Critical error messages when log delivery fails
## Initialization Failures
- Graceful fallback to stderr for uninitialized logger
- Clear error messages when logging system is not ready
- Safe operation even with nil handlers or channels
## Mode Switching
- Clean shutdown of TUI channel with CloseTUIChannel()
- Prevention of further use after channel closure
- Safe concurrent access to logging state
Performance Characteristics ¶
## CLI Mode
- Direct write to output with minimal overhead
- Level filtering at handler level for efficiency
- No memory allocation for filtered-out messages
## TUI Mode
- Buffered channel prevents UI blocking
- Configurable buffer size (default 2048 entries)
- Non-blocking sends with overflow handling
- Memory-efficient message passing
Thread Safety ¶
The logging system is fully thread-safe:
- Safe concurrent logging from multiple goroutines
- Protected access to shared logging state
- Channel operations designed for concurrent use
- No data races in mode switching or configuration
Cleanup and Shutdown ¶
Proper cleanup is essential for TUI mode:
// Clean shutdown in TUI mode defer logging.CloseTUIChannel()
This ensures:
- TUI log channel is properly closed
- No goroutine leaks from channel readers
- Clean application termination
The logging package provides a robust foundation for muster's diagnostic and monitoring capabilities across both interactive and non-interactive execution modes.
Index ¶
- func Audit(event AuditEvent)
- func Debug(subsystem string, messageFmt string, args ...interface{})
- func Error(subsystem string, err error, messageFmt string, args ...interface{})
- func Info(subsystem string, messageFmt string, args ...interface{})
- func InitForCLI(filterLevel LogLevel, output io.Writer)
- func Initcommon(mode string, level LogLevel, output io.Writer, channelBufferSize int) <-chan LogEntry
- func TruncateSessionID(sessionID string) string
- func Warn(subsystem string, messageFmt string, args ...interface{})
- type AuditEvent
- type LogEntry
- type LogLevel
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Audit ¶
func Audit(event AuditEvent)
Audit logs a structured audit event for security-sensitive operations. Audit events are always logged at INFO level and include a special [AUDIT] prefix to make them easily filterable by log aggregation systems.
Example output: [AUDIT] action=token_exchange outcome=success session=abc12345... user=xyz789... target=mcp-kubernetes
func InitForCLI ¶
InitForCLI initializes the logging system for CLI mode.
func Initcommon ¶
func Initcommon(mode string, level LogLevel, output io.Writer, channelBufferSize int) <-chan LogEntry
Initcommon initializes the logger for either TUI or CLI mode. This should be called once at application startup.
func TruncateSessionID ¶
TruncateSessionID returns a truncated session ID for secure logging. This prevents full session IDs from appearing in logs while still providing enough context for debugging correlation. Format: first 8 chars + "..." (e.g., "abc12345...")
Types ¶
type AuditEvent ¶
type AuditEvent struct {
// Action is the type of action being audited (e.g., "token_exchange", "auth_login")
Action string
// Outcome indicates whether the action succeeded or failed
Outcome string // "success" or "failure"
// SessionID is the truncated session identifier
SessionID string
// UserID is the truncated user identifier (from JWT sub claim)
UserID string
// Target is the target of the action (e.g., server name, endpoint)
Target string
// Details provides additional context-specific information
Details string
// Error contains the error message if Outcome is "failure"
Error string
}
AuditEvent represents a structured audit log event for security-sensitive operations. These events can be collected by external audit systems for compliance monitoring.
type LogEntry ¶
type LogEntry struct {
Timestamp time.Time
Level LogLevel
Subsystem string
Message string
Err error
Attributes []slog.Attr // Using slog.Attr for flexibility
}
LogEntry is the structured log entry passed to the TUI.
Source Files