Examples for rrlog
********************************


*A Remote Rotating Log for Python that works instantly*


Simply locally
================

Into stdout
------------

Log into standard out:

.. literalinclude:: ../demo/demo_stdout.py
   :lines: 42-

→  :py:mod:`rrlog.server.printwriter`



Into files
------------

Log rotating into 3 files, each with 10 lines max. (existing files in the working directory are overwritten)

.. literalinclude:: ../demo/demo_files.py
   :lines: 42-

→  :py:mod:`rrlog.server.filewriter`


Into database tables
---------------------

Log rotating into 3 tables, each with 10 lines max. (existing tables are overwritten)

.. literalinclude:: ../demo/demo_database.py
   :lines: 42-

→  :py:mod:`rrlog.server.printwriter`

→  :py:mod:`rrlog.server.dbwriter_sa`



Remote with pure sockets
=========================

This is preferred over xmlrpc, because faster.

**(Re-)Connection behavior**

Any log client will use the log server as long as the server is available. 
When the server is up again after a downtime (or connection failure), all clients will start to use the server again. 
**While a log server is down, messages are lost silently.** 

**Host and Ports**

By default, the connection uses "localhost" and a default port → :py:data:`rrlog.globalconst.DEFAULTPORT_SOCKET`

You can specify 1..n ports on both sides. The server uses the first free port. The client uses the first port where a server seems available.  



A socket server for stdout
----------------------------


.. literalinclude:: ../demo/demo_socketserverstdout.py
   :lines: 42-

→  :py:mod:`rrlog.server.socketserver`

→  :py:mod:`rrlog.server.printwriter`


A socket server for files
------------------------------

.. literalinclude:: ../demo/demo_socketserverfiles.py
   :lines: 42-

→  :py:mod:`rrlog.server.socketserver`

→  :py:mod:`rrlog.server.filewriter`


A socket server for database tables
---------------------------------------

.. literalinclude:: ../demo/demo_socketserverdatabase.py
   :lines: 42-

→  :py:mod:`rrlog.server.socketserver`

→  :py:mod:`rrlog.server.dbwriter_sa`





A socket client in your application
--------------------------------------

.. literalinclude:: ../demo/demo_socketclient.py
   :lines: 42-

→  :py:mod:`rrlog.socketclient`



Remote with xmlrpc
====================

Remote logging is intended to log on a remote machine. Or, which might be a very common use, to log from multiple processes on the same machine into one logfile/table.

This requires two create* calls. One makes the log server, one makes the client in your application.
Most parameters are now found in the server create* function, e.g. the rotation configuration.

**Host and Ports**

.. todo:module-level variables not auto-documented :-(
By default, the connection uses "localhost" and a default port → :py:data:`rrlog.globalconst.DEFAULTPORT_XMLRPC`

You can specify 1..n ports on both sides. The server uses the first free port. The client uses the first port where a server seems available.  



An XMLRPC server for stdout
----------------------------


.. literalinclude:: ../demo/demo_xmlrpcserverstdout.py
   :lines: 42-

→  :py:mod:`rrlog.server.xmlrpc`

→  :py:mod:`rrlog.server.printwriter`


An XMLRPC server for files
------------------------------

.. literalinclude:: ../demo/demo_xmlrpcserverfiles.py
   :lines: 42-

→  :py:mod:`rrlog.server.xmlrpc`

→  :py:mod:`rrlog.server.filewriter`


An XMLRPC server for database tables
---------------------------------------

.. literalinclude:: ../demo/demo_xmlrpcserverdatabase.py
   :lines: 42-

→  :py:mod:`rrlog.server.xmlrpc`

→  :py:mod:`rrlog.server.dbwriter_sa`


An XMLRPC client in your application
--------------------------------------

.. literalinclude:: ../demo/demo_xmlrpcclient.py
   :lines: 42-

→  :py:mod:`rrlog.xmlrpc`


Care for the correct server running ! For example, a socket server erroneously waiting on that port can cause the XMLRPC Client to block stupidly and wait without any Error message.


.. _example_standardlogging:

Use Pythons standard logging
===================================

*Note: Integration of standard logging is incomplete. In particular, we have to log already formatted strings - no separate arguments for string formatting yet.*

Assume you have a log object. You can register it as a handler, and then use the Python logging system as usual.

.. literalinclude:: ../demo/demo_logginghandler.py
   :lines: 60-

→  :py:func:`rrlog.logging23.handler`

Now it should already work.
But when you log stack traces, they look ugly. 
Each call path is dominated by the Python logging framework, especially its __init__ method.

→  :ref:`example_reducestackpath` to make the stack path look better.


**no custom categories anymore**

A drawback of the standard logging module is that we loose our custom message categories.

We have some LEVELs instead; these are mapped to our category values in a LEVELMAP in :py:mod:`rrlog.logging23`.
By default, the error level is mapped to "E" and so on. You can replace that map with your own.

While we have no custom categories anymore, the logging package, on the other hand, gives us a nice way to register separate handlers.