logging-slackhandler

logging-slackhandler

|Version| |Status| |Python| |License| |Build| |Thanks|

Introduction

This module provides additionals handler, formatter and filter for the logging package, so you can send Python log records to a Slack Incoming Webhook.

Credits

This module is widely inspired by Junhwi Kim <https://github.com/junhwi>'s work on python-slack-logger <https://github.com/junhwi/python-slack-logger>.

How it works

In order to send records to Slack without slowing down code run, messages are posted in background by a threads pool, while new records are added to the queue.

In case of network delays or disconnection, app execution while not be blocked waiting for post response.

Installation

You can install, upgrade or uninstall logging-slackhandler using pip:

.. code-block:: bash

pip install logging-slackhandler
pip install --upgrade logging-slackhandler
pip uninstall logging-slackhandler

Usage

SlackHandler

``SlackHandler`` instances dispatch logging events to Slack Incoming Webhook.

Here is the list of its parameters:

    :webhook_url: Slack Incoming Webhook URL.
    :username: (optional) message sender username.
    :channel: (optional) Slack channel to post to.
    :icon_emoji: (optional) customize emoji for message sender.
    :timeout: (optional) specifies a timeout in seconds for blocking operations.
    :pool_size: (optional) specifies number of workers processing records queue.

The following example shows how to send records to a Slack Incoming Webhooks:

.. code-block:: python

    import logging
    from SlackLogger import SlackHandler

    logger = logging.getLogger(__name__)
    logger.setLevel(logging.DEBUG)

    slack_handler = SlackHandler('YOUR_WEBHOOK_URL')
    logger.addHandler(slack_handler)

    for level in ['debug', 'info', 'warning', 'error', 'critical']:
        getattr(logger, level)('This is a `%s` message', level)

SlackFormatter

SlackFormatter instances format log record and return a dictionary that can be sent as a Slack message attachment.

Here is the list of its parameters:

:attr: (optional) custom attachment parameters to record attributes dictionary.
:lvl_color: (optional) custom record levels to colors dictionary.

You can customize the appearance of Slack message with attr parameter, to bind a Slack attachment property <https://api.slack.com/docs/message-attachments#attachment_structure>_ to a record attribute. Empty strings will not be displayed in message.

Also, lvl_color parameter let you customize color-coding messages, binding a record levelname to an hex color code or Slack special codes (good, warning, danger).

.. code-block:: python

from SlackLogger import SlackFormatter

attr={'pretext': '*Look at me!*', 'title': ''}
lvl_color={'INFO': 'good'}

slack_handler.setFormatter(SlackFormatter(attr=attr, lvl_color=lvl_color))

logger.info('Hi there!')

SlackFilter

``SlackFilter`` instances can be use to determine if the specified record is to
be sent to Slack Incoming Webhook.

Here is the list of its parameters:

    :allow: filtering rule for log record.

You can use ``SlackFilter`` to allow only some records to be sent. When
``SlackFilter`` is defined, records will not be sent to Slack unless you
explicitly ask it for by adding ``extra`` argument, as in following example:

.. code-block:: python

    from SlackLogger import SlackFilter

    logger.addFilter(SlackFilter())

    logger.debug('This is a debug message')
    logger.info('Hi there!', extra={'slack': True})

To have the opposite behavior (sent record by default), just set ``allow``
parameter to ``True`` when creating ``SlackFilter``:

.. code-block:: python

    from SlackLogger import SlackFilter

    logger.addFilter(SlackFilter(allow=True))

    logger.debug('This is a debug message', extra={'slack': False})
    logger.info('Hi there!')

Good to know
------------

Messages order

Messages are processed in a FIFO order from the queue, but due to network latency, Slack response time or message length, concurrent messages can appear in a different order in destination channel than the one you sent them.

If message order is a requirement, you can define SlackHandler with a pool size of 1, so that only one thread will process the queue:

.. code-block:: python

slack_handler = SlackHandler('YOUR_WEBHOOK_URL', pool_size=1)

License

Copyright (c) 2017 Damien Le Bourdonnec

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

.. |Version| image:: https://img.shields.io/pypi/v/logging-slackhandler.svg?colorB=ee2269 :target: https://pypi.python.org/pypi/logging-slackhandler :alt: Package Version .. |Status| image:: https://img.shields.io/pypi/status/logging-slackhandler.svg :target: https://pypi.python.org/pypi/logging-slackhandler :alt: Development Status .. |Python| image:: https://img.shields.io/pypi/pyversions/logging-slackhandler.svg?colorB=fcd20b :target: https://pypi.python.org/pypi/logging-slackhandler :alt: Python Version .. |License| image:: https://img.shields.io/pypi/l/logging-slackhandler.svg :target: https://pypi.python.org/pypi/logging-slackhandler :alt: License .. |Build| image:: https://img.shields.io/travis/Greums/logging-slackhandler.svg :target: https://travis-ci.org/Greums/logging-slackhandler :alt: Build Status .. |Thanks| image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg :target: https://saythanks.io/inbox#badge-modal :alt: Say Thanks!