README
¶
Logger
Structured logging with per-subsystem log levels and OpenTelemetry trace context integration.
Features
- Per-subsystem configurable log levels
- Automatic trace_id/span_id injection when OTel is active
- Context-based logger propagation
- JSON output format
- Per-instance log files via
InstanceLogHandler
Configuration
| Variable | Description | Default |
|---|---|---|
LOG_LEVEL |
Default log level | info |
LOG_LEVEL_<SUBSYSTEM> |
Per-subsystem level | inherits default |
Subsystems: API, IMAGES, INSTANCES, NETWORK, VOLUMES, VMM, SYSTEM, EXEC
Example:
LOG_LEVEL=info LOG_LEVEL_NETWORK=debug ./hypeman
Usage
// Create subsystem-specific logger
cfg := logger.NewConfig()
log := logger.NewSubsystemLogger(logger.SubsystemInstances, cfg)
// Add logger to context
ctx = logger.AddToContext(ctx, log)
// Retrieve from context
log = logger.FromContext(ctx)
log.InfoContext(ctx, "instance created", "instance_id", instanceID)
Per-Instance Logging
The InstanceLogHandler automatically writes logs with an "instance_id" attribute to per-instance hypeman.log files. This provides an operations audit trail for each VM.
// Wrap any handler with instance logging
handler := logger.NewInstanceLogHandler(baseHandler, func(id string) string {
return paths.InstanceHypemanLog(id)
})
// Logs with "instance_id" attribute are automatically written to that instance's hypeman.log
log.InfoContext(ctx, "starting VM", "instance_id", instanceID)
// Related operations (e.g., ingress creation) can also include instance_id
// to appear in the instance's audit log
log.InfoContext(ctx, "ingress created", "ingress_id", ingressID, "instance_id", targetInstance)
Output
When OTel tracing is active, logs include trace context:
{
"level": "INFO",
"msg": "instance created",
"subsystem": "INSTANCES",
"trace_id": "abc123...",
"span_id": "def456...",
"instance_id": "instance-123"
}
Documentation
¶
Overview ¶
Package logger provides structured logging with subsystem-specific levels and OpenTelemetry trace context integration.
Package logger provides structured logging with subsystem-specific levels and OpenTelemetry trace context integration.
Index ¶
- Constants
- func AddToContext(ctx context.Context, logger *slog.Logger) context.Context
- func FromContext(ctx context.Context) *slog.Logger
- func NewLogger(cfg Config) *slog.Logger
- func NewSubsystemLogger(subsystem string, cfg Config, otelHandler slog.Handler) *slog.Logger
- func With(logger *slog.Logger, args ...any) *slog.Logger
- type Config
- type InstanceLogHandler
Constants ¶
const ( SubsystemAPI = "API" SubsystemCaddy = "CADDY" SubsystemImages = "IMAGES" SubsystemIngress = "INGRESS" SubsystemInstances = "INSTANCES" SubsystemNetwork = "NETWORK" SubsystemVolumes = "VOLUMES" SubsystemVMM = "VMM" SubsystemSystem = "SYSTEM" SubsystemExec = "EXEC" )
Subsystem names for per-subsystem logging configuration.
Variables ¶
This section is empty.
Functions ¶
func AddToContext ¶
AddToContext adds a logger to the context.
func FromContext ¶
FromContext retrieves the logger from context, or returns default.
func NewSubsystemLogger ¶
NewSubsystemLogger creates a logger for a specific subsystem with its configured level. If otelHandler is provided, logs will be sent both to stdout and to OTel.
Types ¶
type Config ¶
type Config struct {
// DefaultLevel is the default log level for all subsystems.
DefaultLevel slog.Level
// SubsystemLevels maps subsystem names to their specific log levels.
// If a subsystem is not in this map, DefaultLevel is used.
SubsystemLevels map[string]slog.Level
// AddSource adds source file information to log entries.
AddSource bool
}
Config holds logging configuration.
type InstanceLogHandler ¶
InstanceLogHandler wraps an slog.Handler and additionally writes logs that have an "id" attribute to a per-instance hypeman.log file. This provides automatic per-instance logging without manual instrumentation.
Implementation follows the slog handler guide for shared state across WithAttrs/WithGroup: https://pkg.go.dev/golang.org/x/example/slog-handler-guide
func NewInstanceLogHandler ¶
func NewInstanceLogHandler(wrapped slog.Handler, logPathFunc func(id string) string) *InstanceLogHandler
NewInstanceLogHandler creates a new handler that wraps the given handler and writes instance-related logs to per-instance log files. logPathFunc should return the path to hypeman.log for a given instance ID.
func (*InstanceLogHandler) Enabled ¶
Enabled reports whether the handler handles records at the given level.
func (*InstanceLogHandler) Handle ¶
Handle processes a log record, passing it to the wrapped handler and optionally writing to a per-instance log file if "id" attribute is present.
Source Files