pcs-log 1.6.137.221205144037

Generic logger

pcs_log

1.6.137.221205144037

• Usage
• LogP reference

** pcs_log

• »
• pcs_log 1.6.137 documentation

---

Welcome to pcs_log’s documentation!

Document version: 1.6.137.221205144037

Note

This project is under active development.

Source

You can get the complete source-code from GitHub repository

Detailed documentation

The detailed documentation is on Read the Docs

Table of contents

Usage

Installation

To use pcs_log, first install it using pip:

(.venv) $ pip install pcs_log

Use in your program

• This module handles the most often used logging options:

  • log to console

  • log to syslog

  • log to file with autorotation

  • additional a standalone logging server accessible via telnet

  • multiprocessing logs

  • mutithreading logs

  • enhanced formatting options

normally imported as

import logging
from pcs_alog.Logp import LogP

LogP reference

Note

Normally you import only “LogP” from this module.

import logging
from pcs_log.LogP import LogP

This is a “singleton” and used for all your code-modules. You should insert this two lines in every module using logging, but call SetupLogging() only once. (except you make your program or parts of it to “daemons”, in this case you MUST call this function AFTER daemonizing within the daemonized codeblock again, because all the file-handles are deleted on daemonizing)

• class LogP._LogP

  • property GetLogging: tuple
    Return logging functions

    • Returns
      The logging functions in order logging.error, logging.status, logging.warning, logging.msg, logging.info, logging.debug, logging.trace

    • Return type
      tuple

  • PollRestart() → None
    Prüfe ob der Logserver neu gestartet werden muss

  • SetupLogging(*, AppName: str, Verbose: int = 0, NoDaemon: bool = True, StdErr: bool = False, StdErrIsStdOut: bool = False, LogPath: str = '', LogFileInterval: int = 86400, LogFileCount: int = 14, Quiet: bool = False, LogProcInfo: bool = False, LogProcInfoModLen: int = 15, LogProcInfoFuncLen: int = 15, LogLevelType: int = 2, LogMultiProc: bool = False, LogMultiProcLen: int = 15, LogMultiThread: bool = False, LogMultiThreadLen: int = 15, LogStackOnDebug: str = 'NONE', LogLongLevel: str = 'DEBUG', LogStackDepth: int = 5, LogDebugIp: str = '127.0.0.1', LogDebugPort: int = 0, LogDebugCacheSize: int = 100, NoReset: bool = False, TimeOnSyslog: bool = True, translation: Optional[dict] = None, **kwargs) → None

    Creates a defined Log-setting with rich options.

    Note

    All arguments are named arguments - NO positional arguments!

    • param AppName
      Name of application

    • type AppName
      str

    • param Verbose
      Detail of logging. Defaults to 0. Possible values:

      0 = ERROR and STATUS
      1 = MSG, WARNING, STATUS, ERROR
      2 = INFO, MSG, WARNING, STATUS, ERROR
      3 = DEBUG, INFO, MSG, WARNING, STATUS, ERROR
      4 = TRACE, DEBUG, INFO, MSG, WARNING, STATUS, ERROR
      

    • type Verbose
      int, optional

    • param NoDaemon
      Is this an terminal-task. Defaults to True. If this is False => I am a daemon.

      On deamons output to StdErr do not make any sense, so this is ignored and “syslog” or “logfile” is used.

    • type NoDaemon
      bool, optional

    • param StdErr
      Log to StdErr. Defaults to False. If this is set the log goes to StdErr. Ignored if we are a daemon.

    • type StdErr
      bool, optional

    • param StdErrIsStdOut
      Redirect StdErr-Logging to StdOut. Defaults to False.

    • type StdErrIsStdOut
      bool, optional

    • param TimeOnSyslog
      Show timestamp if logging to StdErr. Defaults to True.

    • type TimeOnSyslog
      bool, optional

    • param LogPath
      Log to a Log-file. Defaults to ‘’.

      Log to the file which is given as the argument. this file is rotated on a daily base and holded up to 14 files

    • type LogPath
      str, optional

    • param LogFileInterval
      Number of seconds a logfile lasts until it is rotated. Defaults to 60*60*24 => one day.

    • type LogFileInterval
      int, optional

    • param LogFileCount
      Number of log-file kept. Defaults to 14.

    • type LogFileCount
      int, optional

    • param Quiet
      Output only errors. Defaults to False.

    • type Quiet
      bool, optional

    • param LogProcInfo
      Show process and thread. Defaults to False.

    • type LogProcInfo
      bool, optional

    • param LogLevelType
      Format of LevelInfo. Defaults to 2.

      0=None,
      1=Number,
      2=Name,
      3=Both.
      

    • type LogLevelType
      int, optional

    • param LogMultiProc
      Show process-names. Defaults to False.

    • type LogMultiProc
      bool, optional

    • param LogMultiThread
      Show thread-names. Defaults to False.

    • type LogMultiThread
      bool, optional

    • param LogProcInfoModLen
      Length of the ‘module’ part of the log. Defaults to 15.

      Set to 0 for not alligning this part. Optimally this is the length of the longest modulename in your program. This is only used to allign the log-lines to make the rading easier. This names are NEVER truncated.

    • type LogProcInfoModLen
      int, optional

    • param LogProcInfoFuncLen
      Length of the ‘function’ part of the log. Defaults to 15.

      Set to 0 for not alligning this part. Optimally this is the length of the longest functionname in your program. This is only used to allign the log-lines to make the rading easier. This names are NEVER truncated.

    • type LogProcInfoFuncLen
      int, optional

    • param LogMultiProcLen
      Length of the ‘procedure’ part of the log. Defaults to 15.

      Set to 0 for not alligning this part. Optimally this is the length of the longest procedurename in your program. This is only used to allign the log-lines to make the rading easier. This names are NEVER truncated.

    • type LogMultiProcLen
      int, optional

    • param LogMultiThreadLen
      Length of the ‘thread’ part of the log. Defaults to 15.

      Set to 0 for not alligning this part. Optimally this is the length of the longest threadname in your program. This is only used to allign the log-lines to make the rading easier. This names are NEVER truncated.

    • type LogMultiThreadLen
      int, optional

    • param LogStackOnDebug
      Log-level below or equal a call-stack trace is included.

      Defaults to “NONE” => Disabled. The levels are:

      "ERROR"
      "STATUS"
      "WARNING"
      "MSG"
      "INFO"
      "DEBUG"
      "TRACE"
      "NONE"
      

      All other values are interpretet as “NONE”. Value is not case-sensitive.

    • type LogStackOnDebug
      str, optional

    • param LogLongLevel
      Log-level below or equal a long info is included.

      Above this level except the ERROR-level the fields

      processname,
      threadname,
      module,
      line-no and
      levelinfo
      

      are not within the output. Alternative this can be a comma-separated list of levelnames in this case for this log-levels long infos are provided. Within this list “NONE” is ignored. Defaults to “DEBUG”.

      The levels are:

      "ERROR"
      "STATUS"
      "WARNING"
      "MSG"
      "INFO"
      "DEBUG"
      "TRACE"
      "NONE"
      

      All other values are interpretet as “NONE”. Value is not case-sensitive.

    • type LogLongLevel
      str, optional

    • param LogStackDepth
      Maximum number of call-stack entries to display. Defaults to 5.

    • type LogStackDepth
      int, optional

    • param LogDebugPort
      If 0 no debug-server is started. Else the value has to be between 1024 and 65535. A log-server is started on ‘LogDebugIp’ at port ‘LogDebugPort’.

      It is possible to connect to this port (e.g with telnet) to receive ALL log-messages from this program. ALL means really all, no mather which loglevel is set. This output also includes all possible information about process, thread, module and function. The stacktrace (‘LogStackOnDebug’) is also honored. This output can be really heavy, but can help to debug already running programs without the need to restart with another loglevel.

      This server runs as a separated process and you have to terminate it by calling the Stop() function of the LogP-object, otherwise this process may block the termination of your program. This server will restart himselve if it is terminated by any means except you call the above mentioned functions.

      Note

      This port has to be free.

      Defaults to 0.

    • type LogDebugPort
      int, optional

    • param LogDebugIp
      The IP-address to bind to. This address must exist on the host this program is running. ‘0.0.0.0’ for ‘all IPs’ is also valid. Only examined if ‘LogDebugPort’ > 0. Defaults to ‘127.0.0.1’,

    • type LogDebugIp
      str, optional

    • param LogDebugCacheSize
      Only used if ‘LogDebugPort’ > 0. This is the number of log-messages cached for use at a new connection to the server. So if someone connects to the server he receives the last ‘LogDebugCacheSize’ log messages and after them all new messages.

      This is like a history. If set to 0 this function is disabled. Defaults to 100.

    • type LogDebugCacheSize
      int, optional

    • param NoReset
      Do not reset logger on init. Defaults to False.

      Note

      Use with care. Could tend to mess up the logging.

    • type NoReset
      bool, optional

    • param translation
      If given the programmer can overwrite the error-messages used. There are 2 functions to help creating this dict:

      LogP._PrintInitTranslation() LogP._PrintActualTranslation()

      they do exactly what their name says: they print either the default value for the translationtable or the actual value after overwriting some or all values with this dict. default = {}

    • type translation
      dict, optional

    • After calling this function the new logging is set up. Use the standard functions
      logger.error, logger.warning, etc and additional you can use logger.msg, logger.status and logger.trace.

    • The severity is in descending order:
      ERROR, STATUS, WARNING, MSG, INFO, DEBUG, TRACE

    At the end of your program call:

    LogP.Stop()

    this will stop the optional logger-process which send the output to a telnet-connection if LogDebugPort is not 0.

    Output format:

    General overview:
        2022-06-22 07:37:42,494 Appname:MainProcess:MainThread LogP:main:461 - 40=   ERROR - Message
                                ^       ^           ^          ^               ^     ^       ^
                                |       |           |          |               |     |       |
        Name of application ----+       |           |          |               |     |       |
            only if not StdErr          |           |          |               |     |       |
        Name of process ----------------+           |          |               |     |       |
            if LogMultiProc = true                  |          |               |     |       |
        Name of thread if --------------------------+          |               |     |       |
            LogMultiThread = true                              |               |     |       |
        Module, function and linenumber -----------------------+               |     |       |
            only if LogProcInfo = true                                         |     |       |
        Level-number of message if LogLevelType = 1 or 3 ----------------------+     |       |
        Level-name of message if LogLevelType = 2 or 3 ------------------------------+       |
        The message given to the log-call ---------------------------------------------------+
    
        The minimal log entry for StdErr is:
            2022-06-22 07:37:42,494 Errormessage
        The maximal log entry is shown above.
    
    The output format to StdErr is like this:
        2022-06-22 07:37:42,494 MainProcess:MainThread LogP:main:461     - 40=   ERROR - Message
            No "Appname" because you know whitch program is running.
            The timestamp is only written if 'TimeOnSyslog' is True.
            REMEMBER: this is send to StdErr or to StdOut if 'StdErrIsStdOut' is True.
    
    The output format to sylog like this:
        Appname:MainProcess:MainThread LogP:main:461 - 40=   ERROR - Errormessage
            No timestamp because syslogg adds his own timestamp.
    
    The output format to a logfile is like this:
        2022-06-22 07:37:42,494 Appname:MainProcess:MainThread LogP:main:461 - 40=   ERROR - Message
    
    
    if a call-stack trace is requested lines like these are appended:
            File "./LogP.py", line 471, in <module>
            main()
            File "./LogP.py", line 448, in main
            abc()
            File "./LogP.py", line 411, in abc
            LogP.debug('Debug')
    

  • Stop()
    Stop the Log-Server

---

© Copyright 2022, Ing. Rainer Pietsch.

Built with Sphinx using a theme provided by Read the Docs.