logging.txt

Logging

Levels: E, W, M, 1 2 3 4 5
	Error, Warning, Message (Info)
	plus 5 debugging levels

Output:
	stderr
	curses
	queued
	file

Attrs:
	timestamp
	file
	line
	function
	level
	format
	args...

error(fmt, args...)
	message()
	warning()
	debug()
all #defines to log_dispatcher (a function variable)
log_dispatcher -> dispatcher_curses()

dispatcher_curses()
	error -> file, screen
	message -> file, screen
	debug -> file

dispatcher_file() if enabled
	write to file
	optionally flush after every
		error
		n messages
		n seconds

where does the timestamp originate?
where does the debug level filtering occur?
	probably in dispatcher_file()

multiple dispatchers
	if logging is disabled, then keep a small ring of messages

dispatch_curses -> screen
dispatch_file -> disk
dispatch_queue -> memory
dispatch_stderr -> stderr

all dispatch functions to take all params
flush_queue(dispatch_function)

rename .neomuttdebug -> .neomutt_log?

easier to display backlog if messages are *always* written to disk
neomutt -d0 (or absent) => only write M, W, E to disk

:messages show file verbatim
could colour code according to error/info colours
	need to save in a parsable way, e.g. <E>, <3>

macros pass 0 for time
	disp_queue saves now()
	flushq passes saved time

debug macro passes file, line, func
	others pass NULL

M,W,E and D macros pass level, fmt, args

if no log file, create tmp, populate from ring and display in pager

migrate debugging -> logging
LogLevel 0..5
LogFile  file (template) or % expandos
LogKeep  5?

once started we can't know the log's filename
(could be renamed by other instances)

expandos for template
	%p pid
	%t time (HH:MM) :SS?
	%d date (YYYY-MM-DD)
expand other stuff too?
	$config vars?
	$ENV vars?
variable is only expanded and checked when set
	=> no new logfile at midnight

what's preventing LOTS of logfiles?
	check for locks (actively used)
	check for date (stat) > 1 week?, 1 month?
	means we need a dedicated log *DIR*
	need to scan dir for files

if there are zero expandos (or variables)
	then rotate up to 5 files
otherwise
	!exists - create
	exists - append
accumulate lots of files, up to user to clear them

default to ~/.neomutt/logs/log
default location means we could syntax highlight
	error,warning,message,debug (grey for levels 3,4,5)

variable/config ownership
lib
	DebugFile, set_file()
	DebugLevel, set_level()
	FILE*
	actual filename/level aren't needed
mutt
	Initial file
	Initial level
	for reset

Logging bug
	Leave mutt running, then
	start/close mutt 5 times
	log file of running mutt has been deleted

use file locking on logs to prevent overwriting
	or premature deletion

option in :messages page to save the text

default log level to -1
	level 0 logs msg/error

stderr ignores progress message (or same magic filtering)

abstract progress into separate file

progress - [%d messages omitted]
	need to keep count

mutt_logging:
	start,stop,file,level,rotate,disp_curses
mutt/logging:
	open,close,ver,file,level

states: disabled, enabled, level m, level n

startup
	startup -> queue
	parse command line -> logging
	quick stuff -v, -D, etc flush and exit
	mutt_init -> config -> logging, flush, exit OR
	start_logging(ver, file, level)

options
	{cmdline,config,none} . {-d,-l}
	6 possibilities just to get to start_logging()
	plus test -v, -D routes

while running file,level0, leveln, file2

level-n -> level-n+1 (Now @ level n+1)
level-n -> level0 (keep file open, but not output?)
	no close file
level0 -> level-n (Now @ level n) (for open file)
level0 -> level-n (no file) open file, Now @ level n

setting file, cmdline or config occur before start_logging()
	therefore log is enabled or disabled
disabled -> enabled : rotate, openfile
enabled -> disabled : close (only on exit)
enabled -> enabled (new file) : close, rotate, open

new levels: progress (bar), text (preceded by msg/error?)
	PEWMBT12345, perror, error, warning, message, bar, text, d1, d2, d3, d4, d5

progress rules -> log contains mix of M and B (progress)
	M B0 {B1-21 elided} B22 M B23 {B24-98 elided} B99 M
text rules => M T T T T
	file might <tab> indent lines
indent prevents confusion with other lines

perror, print errno(int) too?

progress: curses: YES, stderr, file: MAGIC filter
text: curses: NO, stderr, file: dependent on previous line

move {read,write,net,time}_inc into curses_message?

Q:
	colours or no colours?
		for curses
		for terminal
	default binding?

problem:
	files are rotated even if logging isn't enabled

on startup main() calls mutt_write_address_list() -> stdout
	separate address from output

use level 0 for info messages -- always logged?

does curses_message() still show up in the logs?

special level for progress messages
	hard when they're interleaved with other debugging messages

turn message log into fake mailbox
	set pager_index_lines = 10
index shows lines (short)
pager shows full text, laid out

log file rotation is happening when logging isn't enabled

mutt_exit -> atexit -> endwin
	ErrorBuf?
	log_file_close
	no sleep
	no "press any key to continue"
	log_close(quiet)

mutt_query_exit() !! from SIGINT

all perror -> mutt_perror()

atexit -> lots of unique retvals
	document current use of retvals
	document all exits from neomutt

can we uses curses keywait without refresh? NO
	e.g. create ~/Mail

mutt_query_exit -> call mutt_exit
mutt_exit -> macro need to know *where* it died
if logq, flush it, dump to screen, backtrace if available

eliminate fprintf for errors
	put everything through the mutt_{debug,message,error}
	mechanism

debug in curses_message() gives misleading function name

define MIN/MAX debug levels and test against these

logging
	print date, then just time for log lines

debug_level > n => fflush every line
	or after every 'n' seconds

mutt_log -> level 1 ==
	mutt_message
	mutt_error
	or == level 0
mutt_debug -> level 2+
need audit
263 mutt_message
728 mutt_error
704 mutt_debug (total ~1700)

enable debug from within mutt
	set debuglevel
	set debugfile
	rotate files?

mutt_exit() -> (retval, msg)
	e.g. function name

all message handlers
	save and restore errno
	doxy doc this

categorise all messages in code
        info, warning, error, question
which imply user to do: nothing, be informed, worry, query user
errors should be clear whose fault
user: e.g. type something invalid
config: file invalid / missing
code: internal error, missing ops
separate what user cannot do vs MAY not do

------------------------------------------------------------

idea for Level 1 debugging: **User actions log**

Every action the user makes, "Compose Email", "Send email", "Open mailbox" should be logged at level 1.
This should include any hooks that they've set up.
If the user was in the pager, we wouldn't log the keypress, <kbd>j</kbd>, but we would log "Open message".

This level should always be saved to the internal message log.

------------------------------------------------------------

main()top
	logq
	getopt
	if 'v'
		flush(stderr)
		exit
	read_config
	if 'D'
		flush(stderr)
		exit

	** DebugFile
	** DebugLevel

	start_debug(file,level)
	flush(curses)
	main_loop()
	stop_debug()
	exit

------------------------------------------------------------

start_debug(file,level)
	expand_file(file)
	rotate_files()
	log_level(level)
	log_open(file0)

------------------------------------------------------------

log_level(level)
	static level = 9
	if (level changes) & (level != 9)
		set level
		debug("logging at level %d")

------------------------------------------------------------

log_open(file)
	static file = ""
	if file changed
	empty -> empty
		do nothing
	empty -> name
		create file / append
		log "starting"
			is this my job?
			don't know the version
	name -> empty
		log "closing"
		close file
	name -> name (same)
		do nothing
	name -> name (diff)
		log "closing"
		close old
		open new
		log "opening"

------------------------------------------------------------

stop_debug()
	log_stderr
	log_close

------------------------------------------------------------

log_close
	log "closing"
	close file
	file=""

------------------------------------------------------------

FILE debug/error()
	if (lev <= dlev) && (file open)
		write to file

------------------------------------------------------------

CURSES debug/error()
	FILE_debug() duplicate
	normal screen stuff

------------------------------------------------------------

STDERR debug/error()
	if (lev <= dlev) && (file open)
		write to stderr

------------------------------------------------------------

QUEUE debug/error()
	save to Q

------------------------------------------------------------

*Were* messages saved to ErrorBuf, before or just errors?
	YES messages were


----

Testing
	set version
	rotate logs
	set filename
	set level

CLI	Config
-	-
-d	-d
-l	-l
-d,-l	-d,-l

log level ∀ config changes?

logging - extend 2 second rule by logging level
	l2 message overwrites a l3 message
	l3 message is blocked a l2 message

mutt_log(Buffer) -> split at \n
	multiple logs
	what level (all at same?)

on segfault, log backtrace to logfile too

logging - take a Buffer param

do we log questions? (and their answers?)

neomutt log add startup timings
	use log's timestamp
	or measure our own millisecond timings

separate logging from libmutt?

register "sensitive" regexes in the logger
	e.g. AUTHENTICATE

could some log levels share level numbers
	NO, can't distinguish them later for labels
	unless 400, 401, 402 are all level 4

log level ∀ file operations
	create/del/link/lock/etc
	caller's id?

log the FD of open/close and other file ops

debug log
	use file locking
	find first missing file, or oldest unlocked

logging file -- does it expand "~" mutt_expand_path
	a) cmdline options
	b) config options

don't log (to file) UI messages like "you are on last message"
	need new log level

logging ideas
	audit the levels
	add sensitive logging option
	remove logging levels completely

debug logging
	use millisecond timestamps?

log before regex ops & other risky functions

promote logging to default -- too useful
	set max level?

- 242 `mutt_message()` - Informational messages
- 38  `mutt_warning()` - Warning messages - Something went wrong, but we can explain to the user what went wrong and why.
- 595 `mutt_error()` - Error messages - Something went wrong, but it's not clear what the user could have done differently.