jamesabel / balsa

object-oriented python logging

balsa (logging utility)

Simple to use package that sets up Python logging. With just a few lines of code get well formatted logging to the console, log file, popup windows and exception services.

Here is a short Presentation on Balsa.

Installation

pip install balsa

Major Features

• Simple to use. Add full-featured Python logging in just a few lines of code.
• Sane default log levels. Single verbose flag. (All levels can be overridden if desired.)
• Both console (stdout) and GUI (popup window) support.
• Log file support. Uses appdirs for log file paths.
• Structured logging via yasf.sf() (optional - you can still use simple strings).
• Sentry support. Just provide your Sentry DSN.
• Informative log message formatting (or you can change it if you like).
• ISO 8601 timestamp format (with fractional seconds).
• Cross platform (Windows, Linux, MacOS). Pure Python.
• Multiprocessing support.
• AWS CloudWatch logs support. Structured logs enable CloudWatch Logs Insights.

Simple Example

from balsa import get_logger, Balsa

application_name = 'example'

log = get_logger(application_name)


def main():
    balsa = Balsa(application_name, 'james abel')
    balsa.init_logger()
    log.error('my error example')

This will yield output of this form:

2021-10-24T10:49:04.150790-07:00 - example - balsa_simple_example.py - 12 - main - ERROR - my error example

Where did the name come from?

Balsa lumber is very soft and light, with a coarse, open grain. The Balsa package is light weight, malleable, and open source.

balsa's Issues

It would be nice to include the celery addin for sentry.

Sentry needs to be told specifically to include celery for task monitoring.
PR incoming ;-)

in GUI mode, when capturing stdout or stderr, prefix the log line with stdout or stderr

Currently in GUI mode, stdout and stderr are captured. This is because many GUI OSs (Windows) raise an exception or error when a GUI app writes to stdout or stderr.

While this currently works in Balsa, there's no indication that a log was indeed from stdout or stderr. The lines are directly written to the log without an indication of where they came from.

Current behavior:
2024-05-06T10:53:40.229075-07:00 - root - MainProcess - balsa.py - 71 - write - INFO - ZeroDivisionError

Desired behavior:
2024-05-06T10:53:40.229075-07:00 - root - MainProcess - balsa.py - 71 - write - INFO - stderr: "ZeroDivisionError"

Make balsa tkinter threadsafe

In python 3 the tkinter module is technically threadsafe, but there are caveats.

So it is worthwhile to make Balsa account for this, by using the mttkinter library, which replaces tkinter in memory and modifies the Tk class to uses a Queue.Queue object for events.

From the mttkinter library issues page...

Tk is not thread-safe, unless it is built with the thread-safe flag. However, the Tcl-interpreter must also be built with the thread-safe flag to ensure thread-safety for Tkinter.

optionally provide traceback

Do a traceback.format_exc() on error or above, with an option to turn this off.
In GUI mode, display a 2nd dialog box with the traceback.

tolerate not having tkinter

The embedded Python interpreter (which is currently only available for Windows) does not include tkinter and there is currently no straight-forward way to install it (there is no "ensuretkinter" like there is "ensurepip"). So, we can't rely on tkinter being present. As a workaround, in order to at least not raise a "module not found error", add this code:

• put a try/except around the "import tkinter"
• in the GUI code, do not use tkinter if the "import tkinter" failed
  Of course, with this workaround we'll lose the ability to pop up error dialog boxes. But it's better than not being able to run at all. Hopefully services like Sentry will be sufficient for us to view the error messages.
  In the longer term, try to lobby Microsoft to add tkinter in embedded Python.

add a 'turn off sentry I'm doing development right now' env var

It's tempting to turn off Sentry during development and then forget to turn it back on. Need a simple way of turning it off during development. Clearing the DSN is a pain, since you then have to set it back to the correct (somewhat long) value string. Probably do something like use an env var:

set BALSA_DEV=TRUE

and use

balsa_dev = bool(distutils.util.strtobool(os.getenv('BALSA_DEV', 'FALSE')))

then:

use_sentry=not balsa_dev

use twine for PyPI

use twine ( https://pypi.org/project/twine ) instead of what's now in pypi.bat

write test case(s) to ensure all the log messages are delivered properly

Test if the log files are correct.
Test if logs to stdout are correct.
Test if log to dialog box are correct.