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.
Testing
The pyoslog module's tests require the pyobjc OSLog framework wrappers in order to verify output and, as a result, can only be run on macOS 10.15 or later.
After installing the OSLog wrappers (via python -m pip install pyobjc-framework-OSLog
), navigate to the tests directory and run:
python -m unittest
Alternatives
At the time this module was created there were no alternatives available on PyPi. Since then, the macos-oslog module has been released, with broadly equivalent functionality to pyoslog. There are also other options available if PyPi access 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 (and as a result is used for testing pyoslog).
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.5.0-cp39-cp39-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0ae7ddcdf0cc86b0080e1c2c7d7f13d019fe17e07be5df7f91680d94ee3dd6c2 |
|
MD5 | 949f6c6318d3ee5328d60a49f195f8b8 |
|
BLAKE2b-256 | 531ec92b38a550c54f015f5bafddec3918dd98471c02ea1c46b2ee9739b25572 |