Welcome to pcs_log’s documentation!

Document version: 1.6.139.240629104654

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 
              main()
              File "./LogP.py", line 448, in main
              abc()
              File "./LogP.py", line 411, in abc
              LogP.debug('Debug')
      
    • Stop()
      Stop the Log-Server