osdf/logging/onap_common_v1/README.md

   1 # -------------------------------------------------------------------------
   2 #   Copyright (c) 2015-2017 AT&T Intellectual Property
   3 #
   4 #   Licensed under the Apache License, Version 2.0 (the "License");
   5 #   you may not use this file except in compliance with the License.
   6 #   You may obtain a copy of the License at
   7 #
   8 #       http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 #   Unless required by applicable law or agreed to in writing, software
  11 #   distributed under the License is distributed on an "AS IS" BASIS,
  12 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 #   See the License for the specific language governing permissions and
  14 #   limitations under the License.
  15 #
  16 # -------------------------------------------------------------------------
  17 #
  18
  19 # Common Logging Wrapper for Python
  20
  21 * CommonLogger.py is the module (library) to import
  22 * CommonLogger_test.config is an example configuration file used by CommonLogger_test.py
  23 * CommonLogger_test.py is an example of how to import and use the CommonLogger module
  24
  25 ## Configuration File
  26
  27 Configure common logging for a python application in a configuration file.
  28 In the file, put key = value assignments
  29
  30 * defining the filename for each log file you will create, such as
  31 'error=/path/error.log', 'metrics=/path/metrics.log', 'audit=/path/audit.log',
  32 and 'debug=/path/debug.log'.
  33 The name used (shown here as 'error', 'metrics', etc.) is chosen in the program, allowing a single configuration file to be
  34 used by numerous different programs.
  35 (It will be referred to below as &lt;logKey&gt;.)
  36 * defining the style of the log messages to be produced,
  37 using &lt;logKey&gt; suffixed with 'Style', as in 'errorStyle=', and one of the
  38 words 'error', 'metrics', 'audit' and 'debug'.
  39 * defining the minimum level of log messages to be retained in a log file,
  40 using &lt;logKey&gt; suffixed with 'LogLevel', as in 'errorLogLevel=WARN'.
  41 The levels are DEBUG, INFO, WARN, ERROR, and FATAL.
  42 So specifying WARN will retain only WARN, ERROR, and FATAL level
  43 log messages, while specifying DEBUG will retain all levels of log messages:
  44 DEBUG, INFO, WARN, ERROR, and FATAL.
  45
  46 Comments may be included on any line following a '#' character.
  47
  48 Common logging monitors the configuration file so if the file is edited
  49 and any its values change, then common logging will implement the changes
  50 in the running application.
  51 This enables operations to change log levels or even log filenames without
  52 interrupting the running application.
  53
  54 By default, log files are rotated daily at midnight UTC, retaining 6 backup versions by default.
  55
  56 Other strategies can be specified within the configuration file using the keywords:
  57
  58 * rotateMethod = one of 'time', 'size', and 'none' (case insensitive)
  59
  60 If rotateMethod is 'time', the following keywords apply:
  61 * backupCount = Number of rotated backup files to retain, >= 0. 0 retains *all* backups.
  62 * timeRotateIntervalType = one of 'S', 'M', 'H', 'D', 'W0', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', 'midnight'
  63 (seconds, minutes, hours, days, weekday (0=Monday), or midnight UTC)
  64 * timeRotateInterval = number of seconds/minutes/hours/days between rotations. (Ignored for W#.)
  65
  66 If rotateMethod is 'size', the following keywords apply:
  67 * backupCount = Number of rotated backup files to retain, >= 0. 0 retains *no* backups.
  68 * sizeMaxBytes = maximum number of bytes allowed in the file before rotation
  69 * sizeRotateMode = for now, this defaults to 'a' and may only be specified as 'a'.
  70 It is passed to the underlying Python Logging methods.
  71
  72
  73 Besides logging to a file, it is also possible to send log messages elsewhere,
  74 using &lt;logKey&gt; suffixed with 'LogType'.
  75 You can set &lt;logKey&gt;LogType to any of 'filelogger', 'stdoutlogger', 'stderrlogger', 'socketlogger' orlogger 'null' (case insensitive).
  76
  77 * 'filelogger' is the default specifying logging to a file.
  78 * 'stdoutlogger' and 'stderrlogger' send the output to the corresponding output streams.
  79 * 'socketlogger' will send the output to the corresponding socket host.
  80 * 'nulllogger' turns off logging.
  81
  82 If &lt;logKey&gt;LogType is 'socket', the following keywords apply:
  83 * &lt;logKey&gt;SocketHost = FQDN or IP address for a host to sent the logs to
  84 * &lt;logKey&gt;SocketPort = the port (> 0) to open on that host
  85
  86 This is an example configuration file:
  87
  88     error           = /var/log/DCAE/vPRO/error.log
  89     errorLogLevel   = WARN
  90     errorStyle      = error
  91
  92     metrics         = /var/log/DCAE/vPRO/metrics.log
  93     metricsLogLevel = INFO
  94     metricsStyle      = metrics
  95
  96     audit           = /var/log/DCAE/vPRO/audit.log
  97     auditLogLevel   = INFO
  98     auditStyle      = audit
  99
 100     debug           = /var/log/DCAE/vPRO/debug.log
 101     debugLogLevel   = DEBUG
 102     debugStyle      = debug
 103
 104 ## Coding Python Applications to Produce ONAP Common Logging
 105
 106 A python application uses common logging by importing the CommonLogger
 107 module, instantiating a CommonLogger object for each log file, and then
 108 invoking each object's debug, info, warn, error, or fatal methods to log
 109 messages to the file. There are four styles of logging:
 110 error/info logs, debug logs, audit logs, and metrics logs.
 111 The difference between the types of logs is in the list of fields that
 112 are printed out.
 113
 114 ### Importing the CommonLogger Module
 115
 116 Importing the CommonLogger module is typical:
 117
 118     sys.path.append("/opt/app/dcae-commonlogging/python")
 119     import CommonLogger
 120
 121 ### Creating a CommonLogger object:
 122
 123 When creating a CommonLogger object, three arguments are required:
 124
 125 1. The configuration filename.
 126 2. The keyword name in the configuration file that
 127 defines the log filename and parameters controlling rotation of the logfiles.
 128 (This is the &lt;logKey&gt; referred to above.)
 129 3. The keyword arguments for style and to set default values for the log record fields.
 130
 131 The style of the log (one of CommonLoger.DebugFile, CommonLogger.AuditFile,
 132 CommonLogger.MetricsFile and CommonLogger.ErrorFile), must be specified either
 133 in the configuration file (e.g., errorStyle=error or metricsStyle=metrics) or
 134 using a style= keyword and one of the values: CommonLoger.DebugFile,
 135 CommonLogger.AuditFile, CommonLogger.MetricsFile and CommonLogger.ErrorFile.
 136
 137 Keyword arguments for log record fields are as follows.
 138 The annotation indicates whether the field is included in
 139 (d) debug logs, (a) audit logs, (m) metrics logs, and (e) error logs.
 140
 141 * requestID (dame)
 142 * serviceInstanceID (am)
 143 * threadID (am)
 144 * serverName (am)
 145 * serviceName (am)
 146 * instanceUUID (am)
 147 * severity (am)
 148 * serverIPAddress (am)
 149 * server (am)
 150 * IPAddress (am)
 151 * className (am)
 152 * timer (am)
 153 * partnerName (ame)
 154 * targetEntity (me)
 155 * targetServiceName (me)
 156 * statusCode (am)
 157 * responseCode (am)
 158 * responseDescription (am)
 159 * processKey (am)
 160 * targetVirtualEntity (m)
 161 * customField1 (am)
 162 * customField2 (am)
 163 * customField3 (am)
 164 * customField4 (am)
 165 * errorCategory (e)
 166 * errorCode (e)
 167 * errorDescription (e)
 168
 169 Sample code:
 170
 171     """ The style can be specified here or in the config file using errorStyle. """
 172     errorLog = CommonLogger.CommonLogger("my.config", "error", style=CommonLogger.ErrorFile, serviceName="DCAE/vPRO")
 173     infoLog = CommonLogger.CommonLogger("my.config", "info", serviceName="DCAE/vPRO")
 174
 175 ### Setting default values for fields:
 176
 177 The object's setFields method allows keyword arguments changing default values for the log record fields.
 178
 179     errorLog.setFields(serviceName="DCAE/vPRO", threadID="thread-2")
 180
 181 ### Calling Methods
 182
 183 The object's debug(), info(), warn(), error(), and fatal() methods require a detailMessage argument
 184 (which can be a zero-length string) and allow the keyword arguments for setting log record field
 185 values for just that one message.
 186 Any newlines or '|' characters in the message will be changed to a single space.
 187
 188     infoLog.info("Something benign happened.")
 189     errorLog.fatal("Something very bad happened.", threadID="thread-4")
 190
 191 ### Output
 192
 193 Note that no field may contain the '|' (pipe) field separation character, as that
 194 character is used as the separator between fields.
 195 Here is a possible example of a produced log record:
 196
 197     2015-10-12T15:56:43,182+00:00|netman@localdcae.att.com:~/vPRO_trinity/vPRO.py:905+2015-08-20 20:57:14.463426||||DCAE/vPRO:App-C.Restart|d4d5fc66-70f9-11e5-b0b1-005056866a82|INFO||135.16.76.33|mtvpro01dev1.dev.att.com|||1001|Finished Restart
 198     2016-12-09T23:06:02,314+00:00||MainThread|DCAE/vPRO|||||||a FATAL message for the error log
 199
 200 ### Example Code
 201
 202 The main within CommonLogger.py contains a regression test of the CommonLogger methods.
 203
 204 CommonLogger_test.py contains a complete demonstration of a python application
 205 using the python CommonLogging wrapper module, including creating UUIDs,
 206 setting default log field values, and timing operations.
 207
 208 ## Upgrading from Previous Versions of CommonLogger
 209
 210 The current version of CommonLogger is 99% compatible with earlier versions of CommonLogger.
 211 The key change, due to update ONAP logging requirements, is the choice to use different lists
 212 of fields in different types of log files.
 213 This required adding a mandatory "style" to be given, which we chose to do using either a
 214 new keyword in the configuration file, or using a new parameter keyword when creating the logger.