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 levelinfoare 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
-
