Metadata-Version: 1.1
Name: rfc5424-logging-handler
Version: 1.0.2
Summary: An up-to-date, RFC5424-Compliant syslog handler for the Python logging framework
Home-page: https://github.com/jobec/rfc5424-logging-handler
Author: Joris Beckers
Author-email: joris.beckers@gmail.com
License: BSD
Download-URL: https://pypi.python.org/pypi/rfc5424-logging-handler
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
        
        An 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
        
        Using a 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")
        
        Using 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 - - - - - \xef\xbb\xbfMy syslog message
        
        
        
        Changelog
        ---------
        
        `1.0.2`_ - 2017/08/31
        ~~~~~~~~~~~~~~~~~~~~~
        
        **Fixed**
        
        * Package description rendering on PyPi due to bug `pypa/wheel#189 <https://github.com/pypa/wheel/issues/189>`_
        
        `1.0.1`_ - 2017/08/30
        ~~~~~~~~~~~~~~~~~~~~~
        
        **Added**
        
        * `#12`_: 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
        ~~~~~~~~~~~~~~~~~~~~~
        
        **Changed**
        
        * `#10`_: 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
        ~~~~~~~~~~~~~~~~~~~~~
        
        **Fixed**
        
        * Better input handling
        * Better sanitizing of invalid input
        
        `0.1.0`_ - 2017/01/22
        ~~~~~~~~~~~~~~~~~~~~~
        
        **Added**
        
        * `#4`_: 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
        ~~~~~~~~~~~~~~~~~~~~~
        
        **Added**
        
        * `#5`_ Introduced Python 2.7 compatibility
        
        0.0.1 - 2017/01/11
        ~~~~~~~~~~~~~~~~~~
        
        * Initial release
        
        .. _1.0.2: https://github.com/jobec/rfc5424-logging-handler/compare/1.0.1...1.0.2
        .. _1.0.1: https://github.com/jobec/rfc5424-logging-handler/compare/1.0.0...1.0.1
        .. _1.0.0: https://github.com/jobec/rfc5424-logging-handler/compare/0.2.0...1.0.0
        .. _0.2.0: https://github.com/jobec/rfc5424-logging-handler/compare/0.1.0...0.2.0
        .. _0.1.0: https://github.com/jobec/rfc5424-logging-handler/compare/0.0.2...0.1.0
        .. _0.0.2: https://github.com/jobec/rfc5424-logging-handler/compare/0.0.1...0.0.2
        
        .. _#12: https://github.com/jobec/rfc5424-logging-handler/pull/12
        .. _#10: https://github.com/jobec/rfc5424-logging-handler/pull/10
        .. _#5: https://github.com/jobec/rfc5424-logging-handler/issues/5
        .. _#4: https://github.com/jobec/rfc5424-logging-handler/pull/4
        
Keywords: python logging handler syslog rfc5424
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Development Status :: 5 - Production/Stable
