[Scummvm-devel] Log file support

[Max Horn]

Hi Johannes, all!

Am 24.11.2010 um 01:41 schrieb Johannes Schickel:

> Hi,
> 
> as you might have noticed I implemented a simple class which aids backends in supporting logging to a file.

Thanks a lot, very much appreciated :).

[...]

> 
> There are some unresolved questions about how we properly hook it up in our backends though. This is a usually highly backend specific question. I think for most backends its maintainer can decide this freely. The main problem is the SDL backend here, since it is used by many more people on different platforms. Thus all the below mentioned points are mainly targeted at the SDL backend.

Agreed. Indeed, I understand you as talking primarily about "the" SDL backend, for desktop systems like Windows, Linux, Mac, and other desktops systems (BeOS? AmigaOS? etc). I consider it fair game to solve the problem for these first, and then talk about handhelds later (if at all; each may require a different approach, after all).

> 1) Log strategy
> 
> We can basically have two different logging strategies:
> 
> a) only have one log file, which is overwritten on every run.
> b) have a fixed maximum of log files and always reuse the oldest one on startup (i.e. log rotation).
> c) have an unlimited number of log files.

I am all for (a) at this point, and will quote myself from a tracker comment:

Right now I would prefer to go with the "single log file" approach. A single log file is very easy to understand for the user, and there is little risk of the user picking "the wrong one". It is also easiest to implement for us. E.g. no need to rotate log files to prevent the disk from filling up with lots of "-d9" log files.

Potential drawback is that the user must remember to copy it right away, before re-starting ScummVM, else it is lost. This is mostly a problem for "rare" hard-to-reproduce issues. If the user can easily reproduce it, then they are just fine either way. Moreover, if we crash into the debugger console, we could display a text there like "If you want to file a bug report on this, you can find a log file with relevant info in location XYZ. Please copy it NOW, before restarting ScummVM, otherwise it will get overwritten." Well, something like that, at least.

Also, for MD5 reports (where we'd ask the user via a GUI dialog to email use the log file), this is no problem.


Since it is also the easiest to implement, I would suggest that we add single-file logging *now* -- we can still switch to multi-file logging later on, with no harm done. Why hold this back needlessly?

If we *do* go with multiple (rotating?) log files on the long run, the name scheme Michael suggested make sense to me. Also, putting the log files into a common directory makes sense.




> 2) Name scheme.
> 
Use scummvm.log if we use a single log file. Else I am for something like Michael suggested, though I prefer inserting some dashes for readability:
  scummvm-YYYY-MM-DD_HH-SS_NNN.log
where NNN is milliseconds, or just some random string.




> 3) Placement of the log files
> 
> We need to decide where to place the log file(s) on Windows, Mac OS X and UNIX-like systems.
> 
> Max already made a proposal where to store them on Mac OS X:
> 
> a) Store them in ~/Library/Logs/
> b) Store them in a sub-directory thereof, i.e. ~/Library/Logs/ScummVM
> 
> a) sounds fine for me when we agree on only having a single log file. I would prefer b) in case we want to have log file rotation though. since that should make finding the logs easier for users. If you are a developer using Mac OS X and you have some opinion about this, please tell us about it.

Well, this is the location Apple suggests, there is little to discuss there, I think :). Except maybe for the syslog alternative, see below.

> 
> For UNIX-like systems I would like to propose ~/.scummvm. That is the default directory for our save files already. While this is not that ideal, since it would mix save files with the logs, I think we can either make two sub-directories there (i.e. save/ and logs/) or just mix them, since most users will change their default save path anyway (I think...).

Since saves are already in ~/.scummvm, we shouldn't change that for backwards compatibility, i.e. ~/.scummvm/saves is out IMO. We could still store logs in ~/.scummvm/logs, of course. 

Or we use syslog(), as suggested above. Easy to do by writing a SyslogWriteStream subclass wrapping openlog, syslog, closelog. This would take a lot of work away for us, esp. when it comes to log rotation and stuff.

Yet it might not be perfect either. For example, locating the right log file might be harder for the user. Not even sure on that, as I am not too familiar with syslog.

By the way, it would also be trivial to log both to our own custom log file, and to syslog simultaneously (e.g. by adding a tiny TeeWriteStream class which wraps around two or more other WriteStreams and passes all write requests through to them).


> 
> We also need to come up with a place where to store logs on Windows. Since I am not familiar with how programs handle that nowadays I can not make any proposal here. Kirben do you have any idea here? Or anyone else (who is using Windows on a regularly base)?

Michael's suggestion of using %APPDATA%\ScummVM or a subfolder of that, e.g. %APPDATA%\ScummVM\logs, seems sensible to me, and is the natural analog of using ~/.scummvm/logs elsewhere.

Alternatively, one could use the Windows event log, though I am not sure whether that is appropriate for our purposes or not; same concerns as for sylog hold here.

Maybe looking at some existing logging libs (there are *tons* of them) might give some extra ideas and insights. E.g.  <http://pantheios.sourceforge.net/> supports logging to "file, stderr/stdout, SysLog (including a custom implementation of the SysLog protocol for Windows), Windows debugger, Windows event log, COM Error Object, speech, [...]"


Cheers,
Max