agent/.core/reference/docs/pkg/log.md

Logging Reference

Logging lives in the root core package in this repository. There is no separate pkg/log import path here.

Create a Logger

logger := core.NewLog(core.LogOptions{
	Level: core.LevelInfo,
})

Levels

Level	Meaning
LevelQuiet	no output
LevelError	errors and security events
LevelWarn	warnings, errors, security events
LevelInfo	informational, warnings, errors, security events
LevelDebug	everything

Log Methods

logger.Debug("workspace discovered", "path", "/srv/workspaces")
logger.Info("service started", "service", "audit")
logger.Warn("retrying fetch", "attempt", 2)
logger.Error("fetch failed", "err", err)
logger.Security("sandbox escape detected", "path", attemptedPath)

Default Logger

The package owns a default logger.

core.SetLevel(core.LevelDebug)
core.SetRedactKeys("token", "password")

core.Info("service started", "service", "audit")

Redaction

Values for keys listed in RedactKeys are replaced with [REDACTED].

logger.SetRedactKeys("token")
logger.Info("login", "user", "cladius", "token", "secret-value")

Output and Rotation

logger := core.NewLog(core.LogOptions{
	Level:  core.LevelInfo,
	Output: os.Stderr,
})

If you provide Rotation and set RotationWriterFactory, the logger writes to the rotating writer instead of the plain output stream.

Error-Aware Logging

LogErr extracts structured error context before logging:

le := core.NewLogErr(logger)
le.Log(err)

ErrorLog is the log-and-return wrapper exposed through c.Log().

Panic-Aware Logging

LogPanic is the lightweight panic logger:

defer core.NewLogPanic(logger).Recover()

It logs the recovered panic but does not manage crash files. For crash reports, use c.Error().Recover().