Metadata-Version: 1.1
Name: sap-cf-logging
Version: 3.1.0
Summary: Python logging library to emit JSON logs in a SAP CloudFoundry environment
Home-page: https://github.com/SAP/cf-python-logging-support
Author: SAP
Author-email: UNKNOWN
License: Apache License, Version 2.0
Description: 
        Python logging library to emit JSON logs in a SAP CloudFoundry environment.
        ===========================================================================
        
        This is a collection of support libraries for Python applications running on Cloud Foundry that
        serve two main purposes: provide (a) means to emit structured application log messages and (b)
        instrument web applications of your application stack to collect request metrics.
        
        For details on the concepts and log formats, please look at the sibling project for `java logging
        support <https://github.com/SAP/cf-java-logging-support>`__.
        
        
        Features
        -----------
        
        1. Lightweight, no dependencies. Support of Python 2.7 & 3.5.
        2. Compatible with the Python **logging** module. Minimal configuration needed.
        3. Emits JSON logs (`format
           details <https://github.com/SAP/cf-java-logging-support/tree/master/cf-java-logging-support-core/beats>`__).
        4. Supports **correlation-id**.
        5. Supports request instrumentation. Built in support for `Flask 0.1x <http://flask.pocoo.org/>`__ &
           `Sanic 0.5.x <https://github.com/channelcat/sanic>`__. Extensible to support others.
        6. Includes CF-specific information (space id, app id, etc.) to logs.
        7. Supports adding extra properties to JSON log object.
        
        Installation
        ------------
        
        Install the package with pip:
        
        ::
        
            pip install sap_cf_logging
        
        Usage
        -----
        
        Setting up your application
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Logging library needs to be initialized. Depending on you application type, different initialization
        is used. You should usually do this in your application entrypoint.
        
        For CLI applications you just need to call ``cf_logging.init()`` *once* to configure the library.
        The library will try to configure future loggers to emit logs in JSON format.
        
        If you are using one of the supported frameworks, check the `Configuration <#configuration>`__
        section to see how to configure it.
        
        **Setting up the CloudFoundry environment**
        
        In order for your logs to appear in the Kibana dashboard, you have to create an **application-logs**
        service instance and bind it to your application.
        
        
        Configuration
        ~~~~~~~~~~~~~
        
        After installation use the following guide to configure the Python cf logging library.
        
        Flask
        ^^^^^
        
        First import the ``cf_logging`` library and setup Flask logging on the application.
        
        .. code:: python
        
            from sap.cf_logging import flask_logging
        
            app = flask.Flask(__name__)
            flask_logging.init(app, logging.INFO)
        
        Next use Python’s logging library
        
        .. code:: python
        
            @app.route('/')
            def root_route():
                logger = logging.getLogger('my.logger')
                logger.info('Hi')
        
                return 'ok'
        
        Note the logs generated by the application
        
        Sanic
        ^^^^^
        
        .. code:: python
        
            import sanic
            import logging
        
            from sanic.response import HTTPResponse
            from sap.cf_logging import sanic_logging
            from sap.cf_logging.core.constants import REQUEST_KEY,
        
            app = sanic.Sanic('test.cf_logging')
            sanic_logging.init(app)
        
            @app.route('/')
            async def two(request):
                extra = {REQUEST_KEY: request}
                logging.getLogger('my.logger').debug('Hi', extra = extra)
                return HTTPResponse(body='ok')
        
        **Note**: With Sanic you need to pass the request with an ``extra`` parameter in the logging API.
        This is needed in order to get the *correlation_id* generated at the beginning of the request or
        fetched from the HTTP headers.
        
        General
        ^^^^^^^
        
        .. code:: python
        
            import logging
            from sap import cf_logging
        
            cf_logging.init()
        
            logger = logging.getLogger("cli.logger")
            logger.info('hi')
        
        **Notes**: - All loggers set up and created before the initialization of the Cloud Foundry logging library will
        be left untouched. - When using Flask and Sanic with the logging library a before and
        after request middleware is attached, and it will capture response times for each request.
        
        Examples
        ~~~~~~~~
        
        For more examples please see the tests within the ``./tests/`` directory.
        
        Requirements
        ------------
        
        No external requirements are needed to run the package.
        
        Limitations
        -----------
        
        NA
        
        Known Issues
        ------------
        
        NA
        
        How to obtain support
        ---------------------
        
        Please open an issue on the github page.
        
        Contributing
        ------------
        
        Please create a pull request and briefly describe the nature of the change. Please submit a test
        case along with your pull request.
        
        To-Do (upcoming changes)
        ------------------------
        
        NA
        
        Changelog
        ---------
        
        See `CHANGELOG file <https://github.com/SAP/cf-python-logging-support/blob/master/CHANGELOG.md>`__.
        
        License
        -------
        
        Copyright (c) 2017 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed
        under the Apache Software License, v. 2 except as noted otherwise in the `LICENSE file <https://github.com/SAP/cf-python-logging-support/blob/master/LICENSE>`__.
        
        
        
        
        
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.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 :: Software Development
Classifier: Topic :: System :: Logging
