A more up-to-date, RFC5424-Compliant syslog handler for the Python logging framework
Project description
Python rfc5424 syslog logging handler
=====================================
.. image:: https://img.shields.io/pypi/v/rfc5424-logging-handler.svg
:target: https://pypi.python.org/pypi/rfc5424-logging-handler
.. image:: https://img.shields.io/pypi/pyversions/rfc5424-logging-handler.svg
:target: https://pypi.python.org/pypi/rfc5424-logging-handler#downloads
.. image:: https://travis-ci.org/jobec/rfc5424-logging-handler.svg?branch=master
:target: https://travis-ci.org/jobec/rfc5424-logging-handler
.. image:: https://codecov.io/github/jobec/rfc5424-logging-handler/coverage.svg?branch=master
:target: https://codecov.io/github/jobec/rfc5424-logging-handler?branch=master
A more up-to-date, `RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ compliant syslog handler for the Python logging framework
* Free software: BSD License
* Homepage: https://github.com/jobec/rfc5424-logging-handler
Features
--------
* `RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ Compliant
* No need for complicated formatting strings
Installation
------------
Python package::
pip install rfc5424-logging-handler
Usage
-----
Basics
~~~~~~
After installing you can use this package like this:
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(address=('10.0.0.1', 514))
logger.addHandler(sh)
msg_type = 'interesting'
logger.info('This is an %s message', msg_type)
This will send the following message to the syslog server::
<14>1 2020-01-01T05:10:20.841485+01:00 myserver syslogtest 5252 - - \xef\xbb\xbfThis is an interesting message
Note the UTF8 Byte order mark (BOM) preceding the message. While required by
`RFC 5424 section 6.4 <https://tools.ietf.org/html/rfc5424#section-6.4>`_ if the message is known to be UTF-8 encoded,
there are still syslog receivers that cannot handle it. To bypass this limitation, set the ``msg_as_utf8`` parameter
to ``False`` like this:
.. code-block:: python
sh = Rfc5424SysLogHandler(address=('10.0.0.1', 514), msg_as_utf8=False)
Extended
~~~~~~~~
Full blown example:
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(
address=('10.0.0.1', 514),
hostname="overridden_server_name",
appname="my_wonderfull_app",
procid=555,
structured_data={'sd_id_1': {'key1': 'value1'}},
enterprise_id=32473
)
logger.addHandler(sh)
msg_type = 'interesting'
extra = {
'msgid': 'some_unique_msgid',
'structured_data': {
'sd_id2': {'key2': 'value2', 'key3': 'value3'}
}
}
logger.info('This is an %s message', msg_type, extra=extra)
That will send the following message to the syslog server::
<14>1 2020-01-01T05:10:20.841485+01:00 overridden_server_name my_wonderfull_app 555 some_unique_msgid [sd_id_1@32473 key1="value1"][sd_id2@32473 key3="value3" key2="value2"] \xef\xbb\xbfThis is an interesting message
With logger adapter
~~~~~~~~~~~~~~~~~~~
There's also an `LoggerAdapter` subclass available that makes it more easy to send structured data or a message ID with every message
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler, Rfc5424SysLogAdapter
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(address=('10.0.0.1', 514))
logger.addHandler(sh)
adapter = Rfc5424SysLogAdapter(logger)
msg_type = 'interesting'
adapter.info('This is an %s message',
msg_type, structured_data={'sd_id2': {'key2': 'value2', 'key3': 'value3'}})
adapter.info('This is an %s message', msg_type, msgid='some_unique_msgid')
adapter.info('This is an %s message',
msg_type,
structured_data={'sd_id2': {'key2': 'value2', 'key3': 'value3'}}, msgid='some_unique_msgid')
# Since version 1.0 it's also possible to override the appname, hostname and procid per message
adapter.info('Some other message',
msgid='some_unique_msgid', appname="custom_appname",
hostname="my_hostname", procid="5678")
>From a logging config dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Python supports `configuring the logging system from a dictionary <https://docs.python.org/3/howto/logging-cookbook.html#an-example-dictionary-based-configuration>`_.
Below is an example using the rfc5424 log handler to log to syslog and the stream handler to log to console.
.. code-block:: python
import logging
import logging.config
log_settings = {
'version': 1,
'formatters': {
'console': {
'format': '[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s',
},
},
'handlers': {
'console': {
'level': 'DEBUG',
'class': 'logging.StreamHandler',
'formatter': 'console'
},
'syslog': {
'level': 'INFO',
'class': 'rfc5424logging.handler.Rfc5424SysLogHandler',
'address': ('127.0.0.1', 514),
'hostname': 'overridden_server_name',
'enterprise_id': 32473,
'appname': 'my_wonderfull_app',
},
},
'loggers': {
'syslogtest': {
'handlers': ['console', 'syslog'],
'level': 'DEBUG',
},
}
}
logging.config.dictConfig(log_settings)
logger = logging.getLogger('syslogtest')
logger.info('This message appears on console and is sent to syslog')
logger.debug('This debug message appears on console only')
Prevent a field from being sent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want the appname, hostname or procid field to be empty, instead of it being determined automatically, set it to
NILVALUE explicitly. Setting it to `None` or an empty string will cause it to be filled automatically.
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler, NILVALUE
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(
address=('10.0.0.1', 514),
hostname=NILVALUE,
appname=NILVALUE,
procid=NILVALUE,
)
logger.addHandler(sh)
logger.info('My syslog message')
msg_type = 'interesting'
extra = {
'msgid': 'some_unique_msgid',
'structured_data': {
'sd_id2': {'key2': 'value2', 'key3': 'value3'}
}
}
logger.info('This is an %s message', msg_type, extra=extra)
That will send the following message to the syslog server::
<14>1 2020-01-01T05:10:20.841485+01:00 - - - - - My syslog message
Changelog
---------
1.0.1 (2017-08-30)
~~~~~~~~~~~~~~~~~~
* It's now possible to send syslog messages as `MSG-ANY <https://tools.ietf.org/html/rfc5424#section-6>`_
which suppresses the UTF-8 byte order mark (BOM) when sending messages.
1.0.0 (2017-05-30)
~~~~~~~~~~~~~~~~~~
* Procid, appname and hostname can now be set per message, both with the handler as well as with the adapter
.. note::
This release has a slight change in behaviour. Setting one of the appnama, hostname of procid message to None of an
empty string will cause it to be filled in automatically. Previously, setting it to an empty string caused it to
be set to NILVALUE (a - ). You now need to set it explicilty to NILVALUE if you want to omit it from the message.
0.2.0 (2017-01-27)
~~~~~~~~~~~~~~~~~~
* Better input handling
* Better sanitizing of invalid input
0.1.0 (2017-01-22)
~~~~~~~~~~~~~~~~~~
* Adapter class to make it easier to log message IDs or structured data
* Logging of EMERGENCY, ALERT and NOTICE syslog levels by using the adapter class
* Extensive test suite
0.0.2 (2017-01-18)
~~~~~~~~~~~~~~~~~~
* Introduced Python 2.7 compatibility
0.0.1 (2017-01-11)
~~~~~~~~~~~~~~~~~~
* Initial release
=====================================
.. image:: https://img.shields.io/pypi/v/rfc5424-logging-handler.svg
:target: https://pypi.python.org/pypi/rfc5424-logging-handler
.. image:: https://img.shields.io/pypi/pyversions/rfc5424-logging-handler.svg
:target: https://pypi.python.org/pypi/rfc5424-logging-handler#downloads
.. image:: https://travis-ci.org/jobec/rfc5424-logging-handler.svg?branch=master
:target: https://travis-ci.org/jobec/rfc5424-logging-handler
.. image:: https://codecov.io/github/jobec/rfc5424-logging-handler/coverage.svg?branch=master
:target: https://codecov.io/github/jobec/rfc5424-logging-handler?branch=master
A more up-to-date, `RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ compliant syslog handler for the Python logging framework
* Free software: BSD License
* Homepage: https://github.com/jobec/rfc5424-logging-handler
Features
--------
* `RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ Compliant
* No need for complicated formatting strings
Installation
------------
Python package::
pip install rfc5424-logging-handler
Usage
-----
Basics
~~~~~~
After installing you can use this package like this:
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(address=('10.0.0.1', 514))
logger.addHandler(sh)
msg_type = 'interesting'
logger.info('This is an %s message', msg_type)
This will send the following message to the syslog server::
<14>1 2020-01-01T05:10:20.841485+01:00 myserver syslogtest 5252 - - \xef\xbb\xbfThis is an interesting message
Note the UTF8 Byte order mark (BOM) preceding the message. While required by
`RFC 5424 section 6.4 <https://tools.ietf.org/html/rfc5424#section-6.4>`_ if the message is known to be UTF-8 encoded,
there are still syslog receivers that cannot handle it. To bypass this limitation, set the ``msg_as_utf8`` parameter
to ``False`` like this:
.. code-block:: python
sh = Rfc5424SysLogHandler(address=('10.0.0.1', 514), msg_as_utf8=False)
Extended
~~~~~~~~
Full blown example:
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(
address=('10.0.0.1', 514),
hostname="overridden_server_name",
appname="my_wonderfull_app",
procid=555,
structured_data={'sd_id_1': {'key1': 'value1'}},
enterprise_id=32473
)
logger.addHandler(sh)
msg_type = 'interesting'
extra = {
'msgid': 'some_unique_msgid',
'structured_data': {
'sd_id2': {'key2': 'value2', 'key3': 'value3'}
}
}
logger.info('This is an %s message', msg_type, extra=extra)
That will send the following message to the syslog server::
<14>1 2020-01-01T05:10:20.841485+01:00 overridden_server_name my_wonderfull_app 555 some_unique_msgid [sd_id_1@32473 key1="value1"][sd_id2@32473 key3="value3" key2="value2"] \xef\xbb\xbfThis is an interesting message
With logger adapter
~~~~~~~~~~~~~~~~~~~
There's also an `LoggerAdapter` subclass available that makes it more easy to send structured data or a message ID with every message
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler, Rfc5424SysLogAdapter
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(address=('10.0.0.1', 514))
logger.addHandler(sh)
adapter = Rfc5424SysLogAdapter(logger)
msg_type = 'interesting'
adapter.info('This is an %s message',
msg_type, structured_data={'sd_id2': {'key2': 'value2', 'key3': 'value3'}})
adapter.info('This is an %s message', msg_type, msgid='some_unique_msgid')
adapter.info('This is an %s message',
msg_type,
structured_data={'sd_id2': {'key2': 'value2', 'key3': 'value3'}}, msgid='some_unique_msgid')
# Since version 1.0 it's also possible to override the appname, hostname and procid per message
adapter.info('Some other message',
msgid='some_unique_msgid', appname="custom_appname",
hostname="my_hostname", procid="5678")
>From a logging config dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Python supports `configuring the logging system from a dictionary <https://docs.python.org/3/howto/logging-cookbook.html#an-example-dictionary-based-configuration>`_.
Below is an example using the rfc5424 log handler to log to syslog and the stream handler to log to console.
.. code-block:: python
import logging
import logging.config
log_settings = {
'version': 1,
'formatters': {
'console': {
'format': '[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s',
},
},
'handlers': {
'console': {
'level': 'DEBUG',
'class': 'logging.StreamHandler',
'formatter': 'console'
},
'syslog': {
'level': 'INFO',
'class': 'rfc5424logging.handler.Rfc5424SysLogHandler',
'address': ('127.0.0.1', 514),
'hostname': 'overridden_server_name',
'enterprise_id': 32473,
'appname': 'my_wonderfull_app',
},
},
'loggers': {
'syslogtest': {
'handlers': ['console', 'syslog'],
'level': 'DEBUG',
},
}
}
logging.config.dictConfig(log_settings)
logger = logging.getLogger('syslogtest')
logger.info('This message appears on console and is sent to syslog')
logger.debug('This debug message appears on console only')
Prevent a field from being sent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want the appname, hostname or procid field to be empty, instead of it being determined automatically, set it to
NILVALUE explicitly. Setting it to `None` or an empty string will cause it to be filled automatically.
.. code-block:: python
import logging
from rfc5424logging import Rfc5424SysLogHandler, NILVALUE
logger = logging.getLogger('syslogtest')
logger.setLevel(logging.INFO)
sh = Rfc5424SysLogHandler(
address=('10.0.0.1', 514),
hostname=NILVALUE,
appname=NILVALUE,
procid=NILVALUE,
)
logger.addHandler(sh)
logger.info('My syslog message')
msg_type = 'interesting'
extra = {
'msgid': 'some_unique_msgid',
'structured_data': {
'sd_id2': {'key2': 'value2', 'key3': 'value3'}
}
}
logger.info('This is an %s message', msg_type, extra=extra)
That will send the following message to the syslog server::
<14>1 2020-01-01T05:10:20.841485+01:00 - - - - - My syslog message
Changelog
---------
1.0.1 (2017-08-30)
~~~~~~~~~~~~~~~~~~
* It's now possible to send syslog messages as `MSG-ANY <https://tools.ietf.org/html/rfc5424#section-6>`_
which suppresses the UTF-8 byte order mark (BOM) when sending messages.
1.0.0 (2017-05-30)
~~~~~~~~~~~~~~~~~~
* Procid, appname and hostname can now be set per message, both with the handler as well as with the adapter
.. note::
This release has a slight change in behaviour. Setting one of the appnama, hostname of procid message to None of an
empty string will cause it to be filled in automatically. Previously, setting it to an empty string caused it to
be set to NILVALUE (a - ). You now need to set it explicilty to NILVALUE if you want to omit it from the message.
0.2.0 (2017-01-27)
~~~~~~~~~~~~~~~~~~
* Better input handling
* Better sanitizing of invalid input
0.1.0 (2017-01-22)
~~~~~~~~~~~~~~~~~~
* Adapter class to make it easier to log message IDs or structured data
* Logging of EMERGENCY, ALERT and NOTICE syslog levels by using the adapter class
* Extensive test suite
0.0.2 (2017-01-18)
~~~~~~~~~~~~~~~~~~
* Introduced Python 2.7 compatibility
0.0.1 (2017-01-11)
~~~~~~~~~~~~~~~~~~
* Initial release
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
Close
Hashes for rfc5424-logging-handler-1.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 49abe946d8c15a0dcd05ce93e09a3bc1f02674350547502bfd3eced3435e7d74 |
|
MD5 | 7781885b462256018ee506e13acce384 |
|
BLAKE2b-256 | 53f48f5e4fa53dfcd5c467c07d2a8329fe61d15e28c9c281d0fc9060460a888a |
Close
Hashes for rfc5424_logging_handler-1.0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7cb8ee479f4f87d70fb2c18c74ea7205bad795b96930330fe8dae00d0a26b0b4 |
|
MD5 | 9c9f89c5586f7b1a093a3b72b7233283 |
|
BLAKE2b-256 | b0c366dd98bbbd3fd3725171671dbfd9892e13e40a7ae6f5162eefda3c4e0c54 |