c:geo, as many apps, does not maintain its own log files but uses Androids build-in logging facilities instead via class android.util.Log. Logs can then be read using logcat. The Android logging system is explained e.g. here: https://developer.android.com/studio/debug/am-logcat

However, c:geo developers should not call methods of the Android Log class directly but use methods of c:geo's own Logging class instead:

cgeo.geocaching.utils.Log

The Log class provides static methods Log.e, Log.w, Log.i, Log.d and Log.v to log messages for the different supported android log levels ERROR, WARN, INFO, DEBUG and VERBOSE. The following functionality is added by cgeo.geocaching.utils.Log:

• the TAG cgeo is added to all log messages
• Thread name is added to all log messages
• Depending on logging configuration (see next sections):
  • Only certain severity levels of logging are forwarded to logcat
  • Caller stack information is added to log messages
  • Exceptions may be thrown (ending c:geo) when an error message is logged

A c:geo log message without exception in c:geo looks somewhat like this (if the necessary log config options are turned on, see next section):

2020-09-12 18:33:17.696 22664-22664/cgeo.geocaching I/cgeo: [main] [DB] Current Database Version: 85 --{DataStore$DbHelper.onOpen:1345/SQLiteOpenHelper.getDatabaseLocked:428/SQLiteOpenHelper.getWritableDatabase:317/DataStore.init:641}
<----- Timestamp -----> <-- PIDs -> <-- AppName --> L <tag> <thrd> <--------- log message ---------> <------- caller info ------------------------------------------->

Depending on the used logcat viewer, the format/order of the message parts might differ but you should always be able to identify them.

The following parts are added by the Android system itself:

• Timestamp: timestamp of the log message
• PIDs: process ids identifying the process from which the log was issued
• AppName: name/identifier of the application which sent the log
• L: Log Level as a single uppercase letter (I=INFO and so on)
• tag: an identifier which can be used by logging system to further cluster messages. Always cgeo for c:geo log messages

The following parts are added by c:geo:

• log message: the string log message which you passed when calling one of the Log methods
• thrd: name of the Thread where the message was issued
• caller info: Caller Stack Trace, allowing you to see from which code part the log message was issued

A note to the caller info: this is kind of a "compressed Java Stack Trace" where for each "level" only the Class Name (without package), Method name, and (Codefile) Line Number is remained and different levels are separated with /. In the example above, this means that log call was issued from Java Class DBHelper (subclass of DataStore) in method onOpen, and that this call can be found in the corresponding code file (most likely DataStore.java) at line 1345. This method was in turn reached by a call to onOpen out of cllass/method SQLiteOpenHelper.getDatabaseLocked from corresponding code line 428, and so on.

A log message WITH exception is handled in the same way as above. Additionally, the exception stack trace is written to logcat.

Logging can be configured in two ways:

• via GUI: in Settings -> System -> Activate debug log the Debug Logging Mode can be enabled or disabled
• via file configuration

To configure logging via file, you have to place a text file named log-properties.txt into you local cgeo/logfiles directory. This file is read on c:geo startup ONLY as a Java Properties file. It lets you configure the following log options:

The following rules apply:

• If there is no log-properties.txt present then
  • If Debug Mode is Off then the values in column Default value apply
  • If Debug Mode is On then the values in column Debug Mode apply
• If log-properties.txt is present then for each of the properties defined in that file:
  • If Debug Mode is Off then setting in the file overwrites the default value
  • If Debug Mode is On then the "Maximum" of the settings is applied. For example if logging.minlevel is set to ERROR but Debug Mode is on then DEBUG will be used. If however logging.minlevel is set to VERBOSE and Debug Mode is on then VERBOSE will be used.

The following example log-properties.txt would produce the same logging as default, but would additionally log INFO messages and add caller info with depth 2 to WARN and ERROR messages:

log-properties.txt

logging.minlevel=INFO
logging.mincallerinfolevel=WARN
logging.callerinfomaxdepth=2

The following example log-properties.txt would produce an extremely fine-grained logging (all info VERBOSE, deep stack trace):

log-properties.txt

logging.minlevel=VERBOSE
logging.mincallerinfolevel=VERBOSE
logging.throwonerror=false
logging.callerinfomaxdepth=10

The following example would produce same fine-grained logging as above. Additionally it will write its own startup log into logfiles directory upon c:geo start. Very useful in support for users with startup problems (e.g. unable to get to Settings directory to extract a logfile):

log-properties.txt

logging.minlevel=VERBOSE
logging.mincallerinfolevel=VERBOSE
logging.throwonerror=false
logging.callerinfomaxdepth=10
logging.logfile=support

If someone reports a problem (via support or github issue) and you want to analyze the problem further using log information you have the following options:

Guide the user to the Settings-> System -> Debug information section:

• To get a local log file: ask the user to click Generate logfile. Advise him to generate either the standard logfile (contains only log messages from c:geo itself) or Extended logfile (contains also log messages from other apps -> often helpful for context analysis). The user will automatically get the option to send such a logfile to support via email.
• If the granularity of the log file is not enough in standard mode: ask the user to Activate debug mode, let him/her rerun the situation producing the problem and let him/her then send the logfile to you.
• If even a Debug Mode log is not fine-grained enough, OR the user cannot even start the system: provide him a prepared log-properties.txt, advise him/her to put it in directory cgeo/logfiles, let him/her restart c:geo and then reproduce the problem.