diff options
Diffstat (limited to 'osdf/logging/onap_common_v1/README.md')
| -rwxr-xr-x | osdf/logging/onap_common_v1/README.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/osdf/logging/onap_common_v1/README.md b/osdf/logging/onap_common_v1/README.md new file mode 100755 index 0000000..596cd7f --- /dev/null +++ b/osdf/logging/onap_common_v1/README.md @@ -0,0 +1,214 @@ +# ------------------------------------------------------------------------- +# Copyright (c) 2015-2017 AT&T Intellectual Property +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# ------------------------------------------------------------------------- +# + +# Common Logging Wrapper for Python + +* CommonLogger.py is the module (library) to import +* CommonLogger_test.config is an example configuration file used by CommonLogger_test.py +* CommonLogger_test.py is an example of how to import and use the CommonLogger module + +## Configuration File + +Configure common logging for a python application in a configuration file. +In the file, put key = value assignments + +* defining the filename for each log file you will create, such as +'error=/path/error.log', 'metrics=/path/metrics.log', 'audit=/path/audit.log', +and 'debug=/path/debug.log'. +The name used (shown here as 'error', 'metrics', etc.) is chosen in the program, allowing a single configuration file to be +used by numerous different programs. +(It will be referred to below as <logKey>.) +* defining the style of the log messages to be produced, +using <logKey> suffixed with 'Style', as in 'errorStyle=', and one of the +words 'error', 'metrics', 'audit' and 'debug'. +* defining the minimum level of log messages to be retained in a log file, +using <logKey> suffixed with 'LogLevel', as in 'errorLogLevel=WARN'. +The levels are DEBUG, INFO, WARN, ERROR, and FATAL. +So specifying WARN will retain only WARN, ERROR, and FATAL level +log messages, while specifying DEBUG will retain all levels of log messages: +DEBUG, INFO, WARN, ERROR, and FATAL. + +Comments may be included on any line following a '#' character. + +Common logging monitors the configuration file so if the file is edited +and any its values change, then common logging will implement the changes +in the running application. +This enables operations to change log levels or even log filenames without +interrupting the running application. + +By default, log files are rotated daily at midnight UTC, retaining 6 backup versions by default. + +Other strategies can be specified within the configuration file using the keywords: + +* rotateMethod = one of 'time', 'size', and 'none' (case insensitive) + +If rotateMethod is 'time', the following keywords apply: +* backupCount = Number of rotated backup files to retain, >= 0. 0 retains *all* backups. +* timeRotateIntervalType = one of 'S', 'M', 'H', 'D', 'W0', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', 'midnight' +(seconds, minutes, hours, days, weekday (0=Monday), or midnight UTC) +* timeRotateInterval = number of seconds/minutes/hours/days between rotations. (Ignored for W#.) + +If rotateMethod is 'size', the following keywords apply: +* backupCount = Number of rotated backup files to retain, >= 0. 0 retains *no* backups. +* sizeMaxBytes = maximum number of bytes allowed in the file before rotation +* sizeRotateMode = for now, this defaults to 'a' and may only be specified as 'a'. +It is passed to the underlying Python Logging methods. + + +Besides logging to a file, it is also possible to send log messages elsewhere, +using <logKey> suffixed with 'LogType'. +You can set <logKey>LogType to any of 'filelogger', 'stdoutlogger', 'stderrlogger', 'socketlogger' orlogger 'null' (case insensitive). + +* 'filelogger' is the default specifying logging to a file. +* 'stdoutlogger' and 'stderrlogger' send the output to the corresponding output streams. +* 'socketlogger' will send the output to the corresponding socket host. +* 'nulllogger' turns off logging. + +If <logKey>LogType is 'socket', the following keywords apply: +* <logKey>SocketHost = FQDN or IP address for a host to sent the logs to +* <logKey>SocketPort = the port (> 0) to open on that host + +This is an example configuration file: + + error = /var/log/DCAE/vPRO/error.log + errorLogLevel = WARN + errorStyle = error + + metrics = /var/log/DCAE/vPRO/metrics.log + metricsLogLevel = INFO + metricsStyle = metrics + + audit = /var/log/DCAE/vPRO/audit.log + auditLogLevel = INFO + auditStyle = audit + + debug = /var/log/DCAE/vPRO/debug.log + debugLogLevel = DEBUG + debugStyle = debug + +## Coding Python Applications to Produce ONAP Common Logging + +A python application uses common logging by importing the CommonLogger +module, instantiating a CommonLogger object for each log file, and then +invoking each object's debug, info, warn, error, or fatal methods to log +messages to the file. There are four styles of logging: +error/info logs, debug logs, audit logs, and metrics logs. +The difference between the types of logs is in the list of fields that +are printed out. + +### Importing the CommonLogger Module + +Importing the CommonLogger module is typical: + + sys.path.append("/opt/app/dcae-commonlogging/python") + import CommonLogger + +### Creating a CommonLogger object: + +When creating a CommonLogger object, three arguments are required: + +1. The configuration filename. +2. The keyword name in the configuration file that +defines the log filename and parameters controlling rotation of the logfiles. +(This is the <logKey> referred to above.) +3. The keyword arguments for style and to set default values for the log record fields. + +The style of the log (one of CommonLoger.DebugFile, CommonLogger.AuditFile, +CommonLogger.MetricsFile and CommonLogger.ErrorFile), must be specified either +in the configuration file (e.g., errorStyle=error or metricsStyle=metrics) or +using a style= keyword and one of the values: CommonLoger.DebugFile, +CommonLogger.AuditFile, CommonLogger.MetricsFile and CommonLogger.ErrorFile. + +Keyword arguments for log record fields are as follows. +The annotation indicates whether the field is included in +(d) debug logs, (a) audit logs, (m) metrics logs, and (e) error logs. + +* requestID (dame) +* serviceInstanceID (am) +* threadID (am) +* serverName (am) +* serviceName (am) +* instanceUUID (am) +* severity (am) +* serverIPAddress (am) +* server (am) +* IPAddress (am) +* className (am) +* timer (am) +* partnerName (ame) +* targetEntity (me) +* targetServiceName (me) +* statusCode (am) +* responseCode (am) +* responseDescription (am) +* processKey (am) +* targetVirtualEntity (m) +* customField1 (am) +* customField2 (am) +* customField3 (am) +* customField4 (am) +* errorCategory (e) +* errorCode (e) +* errorDescription (e) + +Sample code: + + """ The style can be specified here or in the config file using errorStyle. """ + errorLog = CommonLogger.CommonLogger("my.config", "error", style=CommonLogger.ErrorFile, serviceName="DCAE/vPRO") + infoLog = CommonLogger.CommonLogger("my.config", "info", serviceName="DCAE/vPRO") + +### Setting default values for fields: + +The object's setFields method allows keyword arguments changing default values for the log record fields. + + errorLog.setFields(serviceName="DCAE/vPRO", threadID="thread-2") + +### Calling Methods + +The object's debug(), info(), warn(), error(), and fatal() methods require a detailMessage argument +(which can be a zero-length string) and allow the keyword arguments for setting log record field +values for just that one message. +Any newlines or '|' characters in the message will be changed to a single space. + + infoLog.info("Something benign happened.") + errorLog.fatal("Something very bad happened.", threadID="thread-4") + +### Output + +Note that no field may contain the '|' (pipe) field separation character, as that +character is used as the separator between fields. +Here is a possible example of a produced log record: + + 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 + 2016-12-09T23:06:02,314+00:00||MainThread|DCAE/vPRO|||||||a FATAL message for the error log + +### Example Code + +The main within CommonLogger.py contains a regression test of the CommonLogger methods. + +CommonLogger_test.py contains a complete demonstration of a python application +using the python CommonLogging wrapper module, including creating UUIDs, +setting default log field values, and timing operations. + +## Upgrading from Previous Versions of CommonLogger + +The current version of CommonLogger is 99% compatible with earlier versions of CommonLogger. +The key change, due to update ONAP logging requirements, is the choice to use different lists +of fields in different types of log files. +This required adding a mandatory "style" to be given, which we chose to do using either a +new keyword in the configuration file, or using a new parameter keyword when creating the logger. |