Documentation
¶
Overview ¶
Package panics provides a process-wide panic handler that converts uncaught panics into a friendly, actionable crash message while preserving the full stack trace for bug reports.
Typical usage at a goroutine entry point (most importantly, main.run):
func run() int {
defer panics.Recover(&exitCode)
...
}
The handler:
- prints a short headline + body via pkg/ui (never raw fmt.Fprintf),
- gates the full stack trace behind ATMOS_LOGS_LEVEL=Debug/Trace (always writes the stack to a temp crash-report file so the user can attach it to a GitHub issue),
- routes the panic through errUtils.CaptureError so Sentry receives it,
- returns exit code 1 (mirroring the existing error-exit convention).
Note: recover() only catches panics on the calling goroutine. Spawned goroutines (signal handler, background telemetry, etc.) still need their own deferred Recover() at their entry point.
Index ¶
Constants ¶
const ( // IssueTrackerURL is where users are directed to report crashes. // Exported so other packages can reference the same canonical URL. IssueTrackerURL = "https://github.com/cloudposse/atmos/issues" // PanicExitCode is the exit code returned after a handled panic. // Kept at 1 to match the existing error-exit convention so CI // behavior is unchanged. Callers wanting a distinct code for panics // can wrap HandlePanic directly. PanicExitCode = 1 // CrashReportFileMode locks the crash report down to the invoking // user because it can contain argv / path values that leak // sensitive data. CrashReportFileMode os.FileMode = 0o600 )
const LogLevelEnvVar = "ATMOS_LOGS_LEVEL"
LogLevelEnvVar is the Atmos log-level environment variable. Callers can reference this constant instead of hard-coding the string.
Variables ¶
This section is empty.
Functions ¶
func HandlePanic ¶
HandlePanic is the core panic-to-friendly-message pipeline, exposed for testing. Production code should call Recover(). It does NOT call os.Exit — the caller owns process termination.
Returns the exit code the caller should propagate.
func Recover ¶
func Recover(exitCode *int)
Recover is the standard deferred panic handler. Call it as the very first deferred statement in any goroutine whose crash should be intercepted. If the caller wants the resulting exit code (typically main.run), pass a non-nil pointer to be populated on recovery.
Usage:
func run() int {
exitCode := 0
defer panics.Recover(&exitCode)
...
return exitCode
}
If no panic occurred, *exitCode is left untouched and Recover returns silently.
Source Files