Send messages to the macOS unified logging system
Project description
Pyoslog
Pyoslog is a simple Python module that allows you to send messages to the macOS unified logging system.
from pyoslog import os_log, OS_LOG_DEFAULT
os_log(OS_LOG_DEFAULT, 'Hello from Python!')
Installation
Pyoslog requires macOS 10.12 or later.
Install using pip
:
python -m pip install pyoslog
The module will install and import without error on earlier macOS versions (and on unsupported Operating Systems and Python versions).
Use pyoslog.is_supported()
if you need to support old macOS versions or other environments and want to know at runtime whether to use pyoslog.
Please note that if is_supported()
returns False
then none of the module's other methods or constants will exist.
Usage
Pyoslog currently provides the methods os_log_create
, os_log_with_type
and os_log
, each with the same signatures as their native versions.
The module also offers a helper method – log
– that by default posts a message of type OS_LOG_TYPE_DEFAULT
to OS_LOG_DEFAULT
.
For example, the shortcut log('message')
is equivalent to os_log_with_type(OS_LOG_DEFAULT, OS_LOG_TYPE_DEFAULT, 'message')
.
The Handler
class is designed for use with Python's inbuilt logging module.
It works as a drop-in replacement for other Handler varieties.
Labelling subsystem and category
Create a log object using os_log_create
and pass it to any of the log methods to add your own subsystem and category labels:
import pyoslog
log = pyoslog.os_log_create('ac.robinson.pyoslog', 'custom-category')
pyoslog.os_log_with_type(log, pyoslog.OS_LOG_TYPE_DEBUG, 'Message to log object', log, 'of type', pyoslog.OS_LOG_TYPE_DEBUG)
Integration with the logging module
Use the pyoslog Handler
to direct messages to pyoslog:
import logging, pyoslog
logger = logging.getLogger('My app name')
logger.setLevel(logging.DEBUG)
handler = pyoslog.Handler()
handler.setSubsystem('org.example.your-app', 'filter-category')
logger.addHandler(handler)
logger.debug('message')
To configure the Handler's output type, use handler.setLevel
with a level from the logging module.
These are mapped internally to the OS_LOG_TYPE
values – for example, handler.setLevel(logging.DEBUG)
will configure the Handler to output messages of type OS_LOG_TYPE_DEBUG
.
Receiving log messages
Logs can be viewed using Console.app or the log
command.
For example, messages sent using the default configuration can be streamed using:
log stream --predicate 'processImagePath CONTAINS "Python"'
Messages sent using custom configurations can be filtered more precisely. For example, to receive messages from the labelled subsystem used in the example above:
log stream --predicate 'subsystem == "ac.robinson.pyoslog"' --level=debug
See man log
for further details about the available options and filters.
Handling cleanup
When labelling subsystem and category using the native C methods there is a requirement to free the log object after use (using os_release
).
The pyoslog module handles this for you – there is no need to del
or release these objects.
Alternatives
At the time this module was created there were no alternatives available on PyPi. There are, however, other options available if this is not seen as a constraint:
Note that the pyobjc module OSLog is for reading from the unified logging system rather than writing to it.
A log.h
binding is on that project's roadmap, but not yet implemented.
License
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pyoslog-0.4.0-cp39-cp39-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c36a9cfd8daa13c1dfe7697e52cf5b58f16081f074ee691633eccdc865d2560 |
|
MD5 | 301bd20711919f86661c80f51b2658da |
|
BLAKE2b-256 | dedf00a8f29786c51291ae7de49beba1387c63db57c8f49f6a29f6a7999fcf59 |