Metadata-Version: 2.1
Name: humiologging
Version: 1.0.1
Summary: Log utilities for Humio: Handlers, formatters
Home-page: https://github.com/Uninett/humiologging
Author: Uninett Opensource
Author-email: opensource@uninett.no
License: Apache-2.0
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Dist: humiolib

================
Logging to Humio
================

.. image:: https://github.com/Uninett/python-logging-humio/actions/workflows/ci.yml/badge.svg
     :target: https://github.com/Uninett/python-logging-humio/actions/workflows/ci.yml
     :alt: CI Status

This package contains logging handlers and formatters useful for logging
to `Humio <https://www.humio.com/>`_. It's sole runtime dependency is
`humiolib <https://github.com/humio/python-humio>`_.

Runs and tested on Python 3.6, 3.7, 3.8, 3.9.

Contents
========

Formatters
----------

``humiologging.formatters.HumioKVFormatter``
    Turns every attribute on the log record into a key-value pair, as suitable
    for the Humio "kv"-parser. Use with ``HumioHandler``.

``humiologging.formatters.HumioJSONFormatter``
    Turns the log-record into a json object, as suitable for the Humio
    "json"-parser. Used by ``HumioJSONHandler``.

Handlers
--------

``humiologging.handlers.HumioHandler``
    Sends line-based text log messages to Humio. You need to use a formatter
    that Humio can parse, like ``HumioKVFormatter``.

``humiologging.handlers.HumioJSONHandler``
    Sends json-formatted log messages to Humio. Does not need a formatter.

Positional arguments:

    :humio_host: The url of the humio ingest host
    :ingest_token: The API token for a Humio repo

Keyword arguments:

    :level: A log-level
    :tags: A dictionary of key value items that will be addded to each record
    :add_host_tag:
        Whether to automatically add the hostname/ip-address where
        the loghandler is used as a tag

Be careful with setting many tags, see
`Humio Documentation: Tagging <https://docs.humio.com/docs/parsers/tagging/>`_

Testing
=======

Run automated tests with `tox <https://tox.readthedocs.io/en/latest/>`_.

To test against humio: you need the hostname of the humio instance and an
ingest_token for a repo with parser set to the handler you want to test.

With no parser set
------------------

    import logging
    logging.basicConfig(handlers=[HumioJSONHandler(host, token)])
    logging.error('This is a test')

In Humio you should get a single entry with one key for every attribute in the
log record. One additional key `formattedMessage` contains the human-readable
format set in the logging config as a string.

For parser ``kv``
-----------------

    import logging
    logging.basicConfig(handlers=[HumioHandler(host, token).setFormatter(HumioKVFormatter())])
    logging.error('This is a test')

In Humio you should get a single record with,a string containing many key=value
pairs. One additional key `formattedMessage` contains the human-readable
format set in the logging config as a string.


