Logging

Maestral makes extensive use of Python’s logging module to collect debug, status and error information from different parts of the program and distribute it to the appropriate channels.

Broadly speaking, the builtin log levels are used as follows:

Level

Typical messages

DEBUG

Individual sync progress, conflict resolution, daemon startup and environment info

INFO

Cumulative sync progress, sync errors that require user resolution (e.g., insufficient space)

WARNING

Failure to initialise non-critical functionality (e.g., desktop notifications, sytem keyring)

ERROR

Errors that prevent all syncing (revoked access token, deleted folder, etc)

Maestral defines a number of log handlers to process those messages, some of them for internal usage, others for external communication. For instance, cached logging handlers are used to populate the public APIs Maestral.status and Maestral.fatal_errors and therefore use fixed log levels. Logging to stderr, the systemd journal (if applicable) and to our log files uses the user defined log level from Maestral.log_level which defaults to INFO. Finally, the Bugsnag error handler which sends all errors to a server for analytics must be explicitly enabled by the user and has a fixed log level of ERROR.

Target

Log level

Enabled

Log file

User defined (default: INFO)

Alyways

Stderr

User defined (default: INFO)

If verbose flag is passed

Systemd journal

User defined (default: INFO)

If started as systemd service

Systemd notify status

INFO

If started as systemd notify service

Maestral.status API

INFO

Alyways

Desktop notifications

WARNING

Alyways

Maestral.fatal_errors API

ERROR

Alyways

Bugsnag

ERROR

Disabled by default

All custom handlers are defined in the maestral.logging module. Maestral also subclasses the default logging.LogRecord to guarantee that any surrogate escape characters in file paths are replaced before emitting a log and flushing to any streams. Otherwise, incorrectly encoded file paths could prevent logging from working properly when it would be particularly useful.

In addition to those automated logging facilities, desktop notifications are sent manually on file changes and sync issues with appropriate buttons and callbacks for user interaction. Those notifications can be separately enabled, disabled or snoozed though the GUI or the CLI with maestral notify level and maestral notify snooze.