docs/sections/services/snmptrap/logging.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Logging
   5 =======
   6
   7 Logging is controlled by the configuration provided to **trapd** by CBS,
   8 or via the fallback config file specified as the environment
   9 variable "CBS_SIM_JSON" at startup.  The section of the JSON configuration
  10 that influences the various forms of application logging is referenced
  11 throughout this document, with examples.
  12
  13 Using the JSON configuration, a base directory is specified for application
  14 data and EELF log files.  Specific filenames (again, from the JSON
  15 config) are appended to the base directory value to create a full-path
  16 filename for use by SNMPTRAP.
  17
  18 Also available is the ability to modify how frequently logs are rolled to
  19 time-stamped versions (and a new empty file is started) as well as what
  20 severity level to log to program diagnostic logs.  The actual archival (to a
  21 timestamped filename) occurs when the first trap is
  22 received **in a new hour** (or minute, or day - depending
  23 on "roll_frequency" value).
  24
  25 Defaults are shown below:
  26
  27 .. code-block:: json
  28
  29     "files": {
  30         <other json data>
  31         ...
  32         "roll_frequency": "day",
  33         "minimum_severity_to_log": 3
  34         <other json data>
  35         ...
  36     },
  37
  38
  39 Roll Frequency
  40 """"""""""""""
  41
  42 Roll frequency can be modified based on your environment (e.g. if trapd is handling a
  43 heavy trap load, you will probably want files to roll more frequently).  Valid "roll_frequency" values are:
  44
  45 - minute
  46 - hour
  47 - day
  48
  49 Minimum Severity To Log
  50 """""""""""""""""""""""
  51
  52 Logging levels should be modified based on your need.  Log levels in lab environments should be "lower"
  53 (e.g. minimum severity to log = "0" creates verbose logging) vs. production (values of "3" and above is a good choice).
  54
  55 Valid "minimum_severity_to_log" values are:
  56
  57 - "1"   (debug mode - everything you want to know about process, and more.  *NOTE:* Not recommended for production environments)
  58 - "2"   (info - verbose logging.  *NOTE:* Not recommended for production environments)
  59 - "3"   (warnings - functionality not impacted, but abnormal/uncommon event)
  60 - "4"   (critical - functionality impacted, but remains running)
  61 - "5"   (fatal - causing runtime exit)
  62
  63
  64 WHERE ARE THE LOG FILES?
  65 ------------------------
  66
  67 APPLICATION DATA
  68 ^^^^^^^^^^^^^^^^
  69
  70 **trapd** produces application-specific logs (e.g. trap logs/payloads,
  71 etc) as well as various other statistical and diagnostic logs.  The
  72 location of these logs is controlled by the JSON config, using these
  73 values:
  74
  75 .. code-block:: json
  76
  77     "files": {
  78         "runtime_base_dir": "/opt/app/snmptrap",
  79         "log_dir": "logs",
  80         "data_dir": "data",
  81         "pid_dir": "tmp",
  82         "arriving_traps_log": "snmptrapd_arriving_traps.log",
  83         "snmptrapd_diag": "snmptrapd_prog_diag.log",
  84         "traps_stats_log": "snmptrapd_stats.csv",
  85         "perm_status_file": "snmptrapd_status.log",
  86         "roll_frequency": "hour",
  87         "minimum_severity_to_log": 2
  88         <other json data>
  89         ...
  90     },
  91
  92 The base directory for all data logs is specified with:
  93
  94     **runtime_base_dir**
  95
  96 Remaining log file references are appended to the *runtime_base_dir*
  97 value to specify a logfile location.  The result using the
  98 above example would create the files:
  99
 100 .. code-block:: bash
 101
 102     /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
 103     /opt/app/snmptrap/logs/snmptrapd_prog_diag.log
 104     /opt/app/snmptrap/logs/snmptrapd_stats.csv
 105     /opt/app/snmptrap/logs/snmptrapd_status.log
 106
 107
 108 ARRIVING TRAPS
 109 ^^^^^^^^^^^^^^^
 110
 111 **trapd** logs all arriving traps.  These traps are saved in a
 112 filename created by appending *runtime_base_dir*, *log_dir*
 113 and *arriving_traps_log* from the JSON config.  Using the example
 114 above, the resulting arriving trap log would be:
 115
 116 .. code-block:: bash
 117
 118     /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
 119
 120 An example from this log is shown below:
 121
 122 .. code-block:: none
 123
 124     1529960544.4896748 Mon Jun 25 17:02:24 2018; Mon Jun 25 17:02:24 2018 com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP 15299605440000 1.3.6.1.4.1.999.0.1 server001 127.0.0.1 server001 v2c 751564798 0f40196a-78bb-11e8-bac7-005056865aac , "varbinds": [{"varbind_oid": "1.3.6.1.4.1.999.0.1.1", "varbind_type": "OctetString", "varbind_value": "TEST TRAP"}]
 125
 126 *NOTE:*  Format of this log will change with 1.5.0; specifically, "varbinds" section will be reformatted/json struct removed and will be replaced with a flat file format.
 127
 128 PUBLISHED TRAPS
 129 ^^^^^^^^^^^^^^^
 130
 131 SNMPTRAP's main purpose is to receive and decode SNMP traps, then
 132 publish the results to a configured DMAAP/MR message bus.  Traps that
 133 are successfully published (e.g. publish attempt gets a "200/ok"
 134 response from the DMAAP/MR server) are logged to a file named by
 135 the technology being used combined with the topic being published to.
 136
 137 If you find a trap in this published log, it has been acknowledged as
 138 received by DMAAP/MR.  If consumers complain of "missing traps", the
 139 source of the problem will be downstream (*not with SNMPTRAP*) if
 140 the trap has been logged here.
 141
 142 For example, with a json config of:
 143
 144 .. code-block:: json
 145
 146     "dmaap_info": {
 147         "location": "mtl5",
 148         "client_id": null,
 149         "client_role": null,
 150         "topic_url": "http://172.17.0.1:3904/events/ONAP-COLLECTOR-SNMPTRAP"
 151
 152 and
 153
 154 .. code-block:: json
 155
 156     "files": {
 157         "**runtime_base_dir**": "/opt/app/snmptrap",
 158
 159 result in traps that are confirmed as published (200/ok response from DMAAP/MR) logged to the file:
 160
 161 .. code-block:: bash
 162
 163     /opt/app/snmptrap/logs/DMAAP_ONAP-COLLECTOR-SNMPTRAP.json
 164
 165 An example from this JSON log is shown below:
 166
 167 .. code-block:: json
 168
 169     {
 170         "uuid": "0f40196a-78bb-11e8-bac7-005056865aac",
 171         "agent address": "127.0.0.1",
 172         "agent name": "server001",
 173         "cambria.partition": "server001",
 174         "community": "",
 175         "community len": 0,
 176         "epoch_serno": 15299605440000,
 177         "protocol version": "v2c",
 178         "time received": 1529960544.4896748,
 179         "trap category": "DCAE-COLLECTOR-UCSNMP",
 180         "sysUptime": "751564798",
 181         "notify OID": "1.3.6.1.4.1.999.0.1",
 182         "notify OID len": 9,
 183         "varbinds": [
 184             {
 185                 "varbind_oid": "1.3.6.1.4.1.999.0.1.1",
 186                 "varbind_type": "OctetString",
 187                 "varbind_value": "TEST TRAP"
 188             }
 189         ]
 190     }
 191
 192
 193
 194 EELF
 195 ^^^^
 196
 197 For program/operational logging, **trapd** follows the EELF logging
 198 convention.  Please be aware that the EELF specification results in
 199 messages spread across various files.  Some work may be required to
 200 find the right location (file) that contains the message you are
 201 looking for.
 202
 203 EELF logging is controlled by the configuration provided
 204 to **trapd** by CBS, or via the fallback config file specified
 205 as an environment variable "CBS_SIM_JSON" at startup.  The section
 206 of that JSON configuration that influences EELF logging is:
 207
 208 .. code-block:: json
 209
 210     "files": {
 211         <other json data>
 212         ...
 213         "**eelf_base_dir**": "/opt/app/snmptrap/logs",
 214         "eelf_error": "error.log",
 215         "eelf_debug": "debug.log",
 216         "eelf_audit": "audit.log",
 217         "eelf_metrics": "metrics.log",
 218         "roll_frequency": "hour",
 219     },
 220     <other json data>
 221     ...
 222
 223
 224 The base directory for all EELF logs is specified with:
 225
 226         **eelf_base_dir**
 227
 228 Remaining eelf_<file> references are appended to the eelf_base_dir value
 229 to specify a logfile location.  The result using the above example would
 230 create the files:
 231
 232 .. code-block:: bash
 233
 234         /opt/app/snmptrap/logs/error.log
 235         /opt/app/snmptrap/logs/debug.log
 236         /opt/app/snmptrap/logs/audit.log
 237         /opt/app/snmptrap/logs/metrics.log
 238
 239 Again using the above example configuration, these files will be rolled
 240 to an archived/timestamped version hourly.  The actually archival (to a
 241 timestamped filename) occurs when the first trap is
 242 received **in a new hour** (or minute, or day - depending
 243 on "roll_frequency" value).
 244
 245 Error / Warning Messages
 246 ------------------------
 247
 248 Program Diagnostics
 249 ^^^^^^^^^^^^^^^^^^^
 250
 251 Detailed application log messages can be found in "snmptrapd_diag" (JSON
 252 config reference).  These can be very verbose and roll quickly
 253 depending on trap arrival rates, number of varbinds encountered,
 254 minimum_severity_to_log setting in JSON config, etc.
 255
 256 In the default config, this file can be found at:
 257
 258 .. code-block:: bash
 259
 260     /opt/app/snmptrap/logs/snmptrapd_diag.log
 261
 262 Messages will be in the general format of:
 263
 264 .. code-block:: none
 265
 266     2018-04-25T17:28:10,305|<module>|snmptrapd||||INFO|100||arriving traps logged to: /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
 267     2018-04-25T17:28:10,305|<module>|snmptrapd||||INFO|100||published traps logged to: /opt/app/snmptrap/logs/DMAAP_com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP.json
 268     2018-04-25T17:28:10,306|<module>|snmptrapd||||INFO|100||Runtime PID file: /opt/app/snmptrap/tmp/snmptrapd.py.pid
 269     2018-04-25T17:28:48,019|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||snmp trap arrived from 192.168.1.139, assigned uuid: 1cd77e98-48ae-11e8-98e5-005056865aac
 270     2018-04-25T17:28:48,023|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||dns cache expired or missing for 192.168.1.139 - refreshing
 271     2018-04-25T17:28:48,027|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||cache for server001 (192.168.1.139) updated - set to expire at 1524677388
 272     2018-04-25T17:28:48,034|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||snmp trap arrived from 192.168.1.139, assigned uuid: 0f40196a-78bb-11e8-bac7-005056
 273     2018-04-25T17:28:48,036|notif_receiver_cb|snmptrapd||||DETAILED|100||processing varbinds for 0f40196a-78bb-11e8-bac7-005056
 274     2018-04-25T17:28:48,040|notif_receiver_cb|snmptrapd||||DETAILED|100||adding 0f40196a-78bb-11e8-bac7-005056 to buffer
 275
 276     2018-06-25T21:02:24,491|notif_receiver_cb|snmptrapd||||DETAILED|100||trap 0f40196a-78bb-11e8-bac7-005056865aac : {"uuid": "0f40196a-78bb-11e8-bac7-005056865aac", "agent address": "192.168.1.139", "agent name": "server001", "cambria.partition": "server001", "community": "", "community len": 0, "epoch_serno": 15299605440000, "protocol version": "v2c", "time received": 1529960544.4896748, "trap category": "com.companyname.dcae.dmaap.location.DCAE-COLLECTOR-UCSNMP", "sysUptime": "751564798", "notify OID": "1.3.6.1.4.1.999.0.1", "notify OID len": 9, "varbinds": [{"varbind_oid": "1.3.6.1.4.1.999.0.1.1", "varbind_type": "OctetString", "varbind_value": "TEST TRAP"}]}
 277     2018-06-25T21:02:24,496|post_dmaap|snmptrapd||||DETAILED|100||post_data_enclosed: {"uuid": "0f40196a-78bb-11e8-bac7-005056865aac", "agent address": "192.168.1.139", "agent name": "server001", "cambria.partition": "server001", "community": "", "community len": 0, "epoch_serno": 15299605440000, "protocol version": "v2c", "time received": 1529960544.4896748, "trap category": "com.att.dcae.dmaap.IST3.DCAE-COLLECTOR-UCSNMP", "sysUptime": "751564798", "notify OID": "1.3.6.1.4.1.999.0.1", "notify OID len": 9, "varbinds": [{"varbind_oid": "1.3.6.1.4.1.999.0.1.1", "varbind_type": "OctetString", "varbind_value": "TEST TRAP"}]}
 278
 279
 280 Platform Status
 281 ^^^^^^^^^^^^^^^
 282
 283 A permanent (left to user to archive/compress/etc) status file is maintained in the file referenced by:
 284
 285     **perm_status_file**
 286
 287 .. code-block:: json
 288
 289         "perm_status_file": "snmptrapd_status.log",
 290
 291 Combined with **runtime_base_dir** and **log_dir** settings from snmptrapd.json, the perm_status_file in default installations
 292 can be found at:
 293
 294 .. code-block:: json
 295
 296         /opt/app/uc/logs/snmptrapd_stats.log