docs/specs/openflowplugin-event-logger.rst

   1 .. contents:: Table of Contents
   2       :depth: 3
   3
   4 ========================================
   5 Openflowplugin Event Logging Using Log4j
   6 ========================================
   7
   8 `Openflowplugin Event Logging Reviews <https://git.opendaylight.org/gerrit/#/c/75415/>`__
   9
  10 Openflowplugin event logger is the feature which is used to log some important events of openflowplugin into a separate
  11 file using log4j.
  12
  13 User should configure log4j appender configuration for openflowplugin event logger in ``etc/org.ops4j.pax.logging.cfg``
  14 file to achieve this.
  15
  16
  17 Problem Description
  18 ===================
  19 When many log events are available in karaf.log file, it will be difficult for user to quickly find the main events with
  20 respect to openflow southbound connection. And also, as there will be huge amount of karaf logs, there are chances of
  21 log events getting rolled out in karaf.log files. Due to which we may tend to miss some of the events related to
  22 openflowplugin.
  23
  24 Openflowplugin event logger feature is intended to overcome this problem by logging important events of openflowplugin
  25 into a separate file using log4j appender, so that user can quickly refer to these event logs to identify  important
  26 events of openflowplugin related to connection, disconnection, reconciliation, port events, errors, failures, etc.
  27
  28 Use Cases
  29 ---------
  30 1. By default openflowplugin event logging feature will not be enabled without any configuration changes in logging
  31    configuration file.
  32
  33 2. User can configure log4j appender for openflowplugin event logger(as mentioned in the configuration section) to
  34    log the important logs of openflowplugin in a separate file at the path mentioned in configuration file.
  35
  36 Proposed Change
  37 ===============
  38 1. A log4j logger with name ``OfEventLog`` will be created and used to log the event at the time of connection,
  39    disconnection, reconciliation, etc.
  40
  41 2. By default the event logger logging level is fixed to DEBUG level. Unless there will be a appender configuration
  42    present in logging configuration file, the events will not be in enqueued for logging.
  43
  44 3. The openflowplugin event logs will be having a pattern consisting of time stamp of the event, description of event
  45    followed by the datapathId of the switch for which events are related.
  46
  47 4. The event logs will be moved to a separate file(data/events/openflow/openflow.log file as per the configuration
  48    mentioned in configuration section) and this can be configured to different path as per the need.
  49
  50 5. The file roll over strategy is chosen as to roll events into other file if the current file reaches maximum size(10MB
  51    as per configuration) and the event logs will be overwritten if such 10 files(as per configuration) are completed.
  52
  53 Command Line Interface (CLI)
  54 ============================
  55 None.
  56
  57 Other Changes
  58 =============
  59
  60 Pipeline changes
  61 ----------------
  62 None.
  63
  64 Yang changes
  65 ------------
  66 None.
  67
  68 Configuration impact
  69 --------------------
  70 Below log4j configuration changes should be added in ``etc/org.ops4j.pax.logging.cfg`` file for logging openflowplugin
  71 events into a separate file.
  72
  73 .. code-block:: none
  74    :caption: org.ops4j.pax.logging.cfg
  75
  76    log4j2.logger.ofp.name = OfEventLog
  77    log4j2.logger.ofp.level = DEBUG
  78    log4j2.logger.ofp.additivity = false
  79    log4j2.logger.ofp.appenderRef.OfEventRollingFile.ref = OfEventRollingFile
  80
  81    log4j2.appender.ofp.type = RollingRandomAccessFile
  82    log4j2.appender.ofp.name = OfEventRollingFile
  83    log4j2.appender.ofp.fileName = \${karaf.data}/events/openflow/openflow.log
  84    log4j2.appender.ofp.filePattern = \${karaf.data}/events/openflow/openflow.log.%i
  85    log4j2.appender.ofp.append = true
  86    log4j2.appender.ofp.layout.type = PatternLayout
  87    log4j2.appender.ofp.layout.pattern = %d{ISO8601} | %m%n
  88    log4j2.appender.ofp.policies.type = Policies
  89    log4j2.appender.ofp.policies.size.type = SizeBasedTriggeringPolicy
  90    log4j2.appender.ofp.policies.size.size = 10MB
  91    log4j2.appender.ofp.strategy.type = DefaultRolloverStrategy
  92    log4j2.appender.ofp.strategy.max = 10
  93    log4j2.appender.ofp.strategy.fileIndex = min
  94
  95 Clustering considerations
  96 -------------------------
  97 The openflowplugin event logger will be configured in the controller and are related to log events only in that
  98 controller. This will not be affecting cluster environment in any way.
  99
 100 Other Infra considerations
 101 --------------------------
 102 N.A.
 103
 104 Security considerations
 105 -----------------------
 106 None.
 107
 108 Scale and Performance Impact
 109 ----------------------------
 110 None.
 111
 112 Targeted Release
 113 ----------------
 114 Sodium.
 115
 116 Alternatives
 117 ------------
 118 N.A.
 119
 120 Usage
 121 =====
 122
 123 Features to Install
 124 -------------------
 125 included with common openflowplugin features.
 126
 127 REST API
 128 --------
 129 None
 130
 131 CLI
 132 ---
 133 None
 134
 135 Implementation
 136 ==============
 137
 138 Assignee(s)
 139 -----------
 140 Primary assignee:
 141  - Somashekhar Javalagi(somashekhar.manohara.javalagi@ericsson.com)
 142
 143 Other contributors:
 144  - D Arunprakash (d.arunprakash@ericsson.com)
 145
 146
 147 Work Items
 148 ----------
 149 N.A.
 150
 151 Dependencies
 152 ============
 153 This doesn't add any new dependencies.
 154
 155
 156 Testing
 157 =======
 158 1. Verifying the event logs in karaf.log file, when there is no appender configuration added in logger configuration
 159    file.
 160 2. Making appender configuration in logger configuration file and verifying the important events of openflowplugin in
 161    the log file specified in configuration.
 162
 163 Unit Tests
 164 ----------
 165 None added newly.
 166
 167 Integration Tests
 168 -----------------
 169 None
 170
 171 CSIT
 172 ----
 173 None
 174
 175 Documentation Impact
 176 ====================
 177
 178 References
 179 ==========
 180