Metadata-Version: 1.2
Name: logsweet
Version: 0.1.0
Summary: Broadcast and receive log messages over network.
Home-page: https://github.com/mastersign/logsweet
Author: Tobias Kiertscher
Author-email: dev@mastersign.de
Maintainer: Tobias Kiertscher
Maintainer-email: dev@mastersign.de
License: BSD-3
Description: 
        logsweet
        ========
        
           A suite with a variety of tools for handling log messages.
        
        The name *logsweet* is a word play by combining *sweet logging* and a
        *suite of logging tools*.
        
        Requirements
        ------------
        
        -  Python ≥3.4
        
        Installation
        ------------
        
        Python Package ``logsweet``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ::
        
           pip install logsweet
        
        or
        
        ::
        
           python ./setup.py install
        
        Docker Image ``mastersign/logsweet``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        There is a public Docker image for *logsweet* available.
        
        .. code:: sh
        
           docker run --rm -it mastersign/logsweet [command] [OPTIONS] [ARGUMENTS]
        
        Remember to mount log files as volumes into the container, when using
        the ``watch`` or ``mock`` command.
        
        Usage
        -----
        
        Logsweet supports the following commands:
        
        -  ``watch`` watches for new lines in text files (e.g. log files) and
           broadcasts them via a ∅MQ PUB socket and/or sends them via a ∅MQ PUSH
           socket.
        -  ``listen`` listens to new lines broadcasted via ∅MQ PUB socket and/or
           collects new lines from ∅MQ PUSH sockets and prints them on the
           console.
        -  ``proxy`` can connect to watchers at the backend and to listeners at
           the frontend. It supports both transmission modes (PUB/SUB and
           PUSH/PULL) at both backend and frontend. It can be used as a single
           point of knowledge or to build groups of log streams.
        -  ``mock`` to write random log messages to text files for testing
           purposes.
        
        One or more known services
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        At the service hosts ``service-1`` and ``service-2`` run:
        
        .. code:: sh
        
           logsweet watch -b *:9000 "/var/log/myservice/*.log"
        
        To watch the two services:
        
        .. code:: sh
        
           logsweet listen -c service-1:9000 -c service-2:9000
        
        Use a proxy for dynamic services
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        First start the proxy on host ``log-proxy`` to wait for backend
        connections from services on port 9001 and frontend connections from
        listeners on port 9002:
        
        .. code:: sh
        
           logsweet proxy -bb *:9001 -fb *:9002
        
        Run one or more listeners to print the messages:
        
        .. code:: sh
        
           logsweet listen -c log-proxy:9002
        
        Start one or more watchers to send log messages to the proxy:
        
        .. code:: sh
        
           logsweet watch -c log-proxy:9001 "/var/log/myservice/*.log"
        
        Use two proxies for high availability
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        First start two proxies on host ``log-proxy-1`` and ``log-proxy-2``:
        
        .. code:: sh
        
           logsweet proxy -bb *:9001 -fb *:9002
        
        Then start one or more listeners to print the messages:
        
        .. code:: sh
        
           logsweet listen -c log-proxy-1:9002 -c log-proxy-2:9002
        
        Start one or more watchers to send log messages to the proxies:
        
        .. code:: sh
        
           logsweet watch -c log-proxy-1:9002 -c log-proxy-2:9002 "/var/log/myservice/*.log"
        
        If multiple proxies are alive, the load is balanced evenly over all
        proxies. If a proxy becomes unavailable, its load is automatically taken
        by the remaining proxies.
        
        Write random log messages for testing
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        You can write random log messages to one or more log files in order to
        test *logsweet* and its usage scenarios:
        
        .. code:: sh
        
           logsweet mock -i 0.2 /var/log/test/1.log /var/log/test/2.log
        
        Use the ``-i`` or ``--interval`` option to control the interval for new
        log messages in seconds.
        
        Configuration
        -------------
        
        The commands ``watch`` and ``listen`` can process a YAML configuration
        file. The configuration controls *filtering*, *coloring* output and
        triggering *actions*.
        
        For the command ``watch`` to print the text lines, the switch ``--echo``
        must be used.
        
        A configuration file is specified with the ``-cfg <yaml file>`` option.
        Here is an example:
        
        .. code:: yaml
        
           version: '0.1'
        
           # The include statement is an array of regular expressions or a single one.
           # A log messages is dropped if it does not match any of the expressions.
           include:
             - 'error|Error|ERROR'
             - 'warning|Warning|WARNING'
        
           # The exclude statement is an array of regular expressions or a single one.
           # A log message is dropped if it matches any of the expressions.
           exclude: 'ignore\s+this'
        
           # The colors statement is an array of colorization rules.
           # The rules are tried in the given order until one matches.
           colors:
             # A colorization rule must have a pattern, which is a regular expression,
             # optionally with named groups.
             - pattern: '\[ERROR\]'
               # There are multiple color statements with the syntax of.
               # <foreground color> [on <background color>]
               # Every color is a color name from the X11 rgb.txt.
               # Spcifically the names supported by the Python package colorful
               # are supported.
               # The color names are Camel Case with a lower first letter.
               line: red  # line specifies a color for the whole line
               match: black on lightGrey # match specifies a color for the whole match
        
             - pattern: '^.*?(?P<level>\[[A-Z]+\]).*(?P<user>admin|user)'
               line: lightGrey
               match: white
               level: yellow
               user: cyan
        
           # The actions statement is an array of action rules.
           # The rules are all tried, regardless of matches.
           # To execute actions from a watch or listen command,
           # the switch -x or --exec-action must be used.
           actions:
             # An action rule must have a pattern, which is a regular expression,
             # optionally with named groups.
             - pattern: '\[ERROR\] (?P<err>.*)$'
               # If the rule has an url property, it is considered an HTTP GET action.
               # The URL is treaded as a Python string template,
               # that means it can contain variables from the named regex groups.
               url: 'http://127.0.0.1:23456/notify-error/${err}'
               # A timeout in seconds can be specified,
               # to limit the amount of time used to execute the HTTP request.
               timeout: 2.5
        
        
        *******
        Changes
        *******
        
        All notable changes to this project will be documented in this file.
        Until this project reaches the maturity of version 1.0.0, the versioning
        follows the following rules:
        
        - The MAJOR number is 0.
        - The MINOR number increases, if backward compatibility was broken
          or an important set of features has been added.
        - The PATCH number increases, if backward compatible features
          have been added or bugs got fixed.
        
        After this project reaches the version number 1.0.0 it will follow
        `Semantic Versioning <http://semver.org/>`_.
        
        ..
        	This document follows the guidelines in http://keepachangelog.md.
        	Use the following change groups:
        
        		Added, Changed, Deprecated, Removed, Fixed, Security
        
        	Add a link to the GitHub diff like
        
        		.. _`<this version>`: https://github.com/mastersign/logsweet/compare/v<last-version>...v<this-version>
        		`<this version>`_ - <date>
        		==========================
        
        
        Unreleased
        ==========
        
        Added
        -----
        
        - proxy
        - binding and connecting on all sides
        - Docker release
        - YAML configuration for filtering, coloring and HTTP actions
        - improved CLI
        
        0.0.0 - 2019-02-21
        ===================
        
        Added
        -----
        
        - basic project structure
        - text file watcher with ZeroMQ PUB
        - ZeroMQ SUB with printing
        - mockup log files
        - basic CLI
        
        
Keywords: lib logsweet
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
