Note: Some basic design decisions here are derived from logsna Python library created by Ruslan Spivak.


Get Started

To use the debug library source it into your script or shell. Sourcing in the library, a few ways.

# Only works if file is in current ${PATH} or "." is in current ${PATH}.

# Only works if file is in current directory.
# . ./

# Full path can present issues porting to other hosts if paths are not the same.
# . /home/arcshell/core/

Let’s make some debug calls.

# Setting a variable up for the example call below.
$ RESUME_NAME="John Doe" 

# Set the _g_debug_level to 3 so all of our statements are actually captured.
$ export _g_debug_level=3

# My preference for debug1 calls is to try to limit them to plain english.
$ debug1 "Processing resumes for external applicants."

# My preference for debug2 calls is to provide function names and input parms.
$ debug2 "process_external_applicant_resumes: "

# My preference for debug3 is to provide more detail. These are usually only
# created when I am troubleshooting and often removed later.

# We can show the last 3 lines from the debug log with this command.
$ debug_get 3
DEBUG1   [2017-02-27 08:35:08] 24037: Processing resumes for external applicants.
DEBUG2   [2017-02-27 08:35:11] 24037: process_external_applicant_resumes: 
DEBUG3   [2017-02-27 08:35:14] 24037: RESUME_NAME=John Doe

Sometimes it is helpful to see our debug output more immediatly. In addition to logging our debug statements we can redirect them to standard out or standard error using the variable shown here.

# 0 log file only, 1 +standard out, 2 +standard error.
$ export _g_debug_output=2
$ debug1 "This line will be returned to the screen via standard error."
DEBUG1   [2017-02-27 08:42:39] 24037: This line will be returned to the screen via standard error.

Let’s look at the debugd* calls which are meant for supplementary details.

$ (echo "Hello World";date;echo "Goodbye") | debugd1
! Hello World
! Mon Feb 27 08:45:01 CST 2017
! Goodbye

All detailed calls read standard input and log it to the log file (or screen in this case) with a “!” beginning each line. This allows you to capture larger quantities of debug details, like file or directory contents, or the output from the “set” command.

Debug can be enabled at the session level using the debug_start call. Below we will reset our global debug settings and then enable a debug session.

# Make sure debug calls are not returned to standard out or error in the future.
$ export _g_debug_output=0

# Turn off global debug, although it could be left on.
$ export _g_debug_level=0   

# Start a debug session at level 3.
$ debug_start 3

# Make some debug calls.
$ debug1 "temp=73"
$ debug1 "temp=74"

# Dump the debug buffer to standard out.
$ debug_dump
DEBUG1   [2017-02-27 09:10:43] 24037: temp=73
DEBUG1   [2017-02-27 09:10:52] 24037: temp=74

# Try to dump the buffer again and we can see it is empty until we make more calls.
$ debug_dump



Return status details about current debug settings.

> debug_show


Tail the debug log as a background process. ‘fg’ to bring to foreground.

> debug_follow


Set the debug level, 0 to 3.

> debug_set_level X


Set the debug log file.

> debug_set_log "file"


Set the debug output location. 0 - File, 1 - STDOUT, 2 - STDERR.

> debug_set_output X


Truncates the debug log file, primarily used during unit testing and development.

> debug_truncate


Begin a new debug session for the current process.

> debug_start [debug_level]
# debug_level: Set the session debug level, 1-3. Default is 3.


Dump stored debug calls to standard output as reset the storage file.

> debug_dump [-x]
# -x: Prevents log file from being truncated/removed subsequent to this call.


End the current debug session and remove buffered lines from the session debug file.

> debug_stop


Level 0 debug call. These are logged even if debug is not enabled.

> debug0 "str"


Level 1 debug call.

> debug1 "X"


Level 2 debug call.

> debug2 "X"


Level 3 debug call.

> debug3 "X"


Level 0 “detail” debug call. Reads from standard input.

> debugd0 ["X"]


Level 1 “detail” debug call. Reads from standard input.

> debugd1 ["X"]


Level 2 “detail” debug call. Reads from standard input.

> debugd2 ["X"]


Level 3 “detail” debug call. Reads from standard input.

> debugd3 ["X"]


Return last X lines from the _g_debug_file.

> debug_get [X]
# X: Number of lines to return. Defaults to 100.