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 **SNMPTRAP** by CBS,
   8 or via the fallback config file specified as the environment
   9 variable "CBS_SIM_JSON" at startup.  The section of that 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.  Files will be rolled to
  21 an archived/timestamped version hourly.  The actual archival (to a
  22 timestamped filename) occurs when the first trap is
  23 received **in a new hour** (or minute, or day - depending
  24 on "roll_frequency" value).
  25
  26 Defaults are shown below:
  27
  28 .. code-block:: json
  29
  30     "files": {
  31         <other json data>
  32         ...
  33         "roll_frequency": "hour",
  34         "minimum_severity_to_log": 2
  35         <other json data>
  36         ...
  37     },
  38
  39
  40 Where to Access Information: APPLICATION DATA (TRAPS)
  41 -----------------------------------------------------
  42
  43 APPLICATION DATA (TRAPS)
  44 ^^^^^^^^^^^^^^^^^^^^^^^^
  45
  46 **SNMPTRAP** produces application-specific logs (e.g. trap logs/payloads,
  47 etc) as well as various other statistical and diagnostic logs.  The
  48 location of these logs is controlled by the JSON config, using these
  49 values:
  50
  51 .. code-block:: json
  52
  53     "files": {
  54         "**runtime_base_dir**": "/opt/app/snmptrap",
  55         "log_dir": "logs",
  56         "data_dir": "data",
  57         "pid_dir": "tmp",
  58         "arriving_traps_log": "snmptrapd_arriving_traps.log",
  59         "snmptrapd_diag": "snmptrapd_prog_diag.log",
  60         "traps_stats_log": "snmptrapd_stats.csv",
  61         "perm_status_file": "snmptrapd_status.log",
  62         "roll_frequency": "hour",
  63         "minimum_severity_to_log": 2
  64         <other json data>
  65         ...
  66     },
  67
  68 The base directory for all data logs is specified with:
  69
  70     **runtime_base_dir**
  71
  72 Remaining log file references are appended to the *runtime_base_dir*
  73 value to specify a logfile location.  The result using the
  74 above example would create the files:
  75
  76 .. code-block:: bash
  77
  78     /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
  79     /opt/app/snmptrap/logs/snmptrapd_prog_diag.log
  80     /opt/app/snmptrap/logs/snmptrapd_stats.csv
  81     /opt/app/snmptrap/logs/snmptrapd_status.log
  82
  83
  84 ARRIVING TRAPS
  85 ^^^^^^^^^^^^^^^
  86
  87 **SNMPTRAP** logs all arriving traps.  These traps are saved in a
  88 filename created by appending *runtime_base_dir*, *log_dir*
  89 and *arriving_traps_log* from the JSON config.  Using the example
  90 above, the resulting arriving trap log would be:
  91
  92 .. code-block:: bash
  93
  94     /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
  95
  96 An example from this log is shown below:
  97
  98 .. code-block:: none
  99
 100     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"}]
 101
 102 *(Add:  varbind type enumerations)*
 103
 104 PUBLISHED TRAPS
 105 ^^^^^^^^^^^^^^^
 106
 107 SNMPTRAP's first priority is to receive and decode SNMP traps, then
 108 publish the results to a configured DMAAP/MR message bus.  Traps that
 109 are successfully published (e.g. publish attempt gets a "200/ok"
 110 response from the DMAAP/MR server) are logged to a file named by
 111 the technology being used combined with the topic being published to.
 112
 113 If you find a trap in this published log, it has been acknowledged as
 114 received by DMAAP/MR.  If consumers complain of "missing traps", the
 115 source of the problem will be downstream (*not with SNMPTRAP*) if
 116 the trap has been logged here.
 117
 118 For example, with a json config of:
 119
 120 .. code-block:: json
 121
 122     "dmaap_info": {
 123         "location": "mtl5",
 124         "client_id": null,
 125         "client_role": null,
 126         "topic_url": "http://172.17.0.1:3904/events/ONAP-COLLECTOR-SNMPTRAP"
 127
 128 and
 129
 130 .. code-block:: json
 131
 132     "files": {
 133         "**runtime_base_dir**": "/opt/app/snmptrap",
 134
 135 result in traps that are confirmed (200/ok) as published logged to the file:
 136
 137 .. code-block:: bash
 138
 139     /opt/app/snmptrap/logs/DMAAP_ONAP-COLLECTOR-SNMPTRAP.json
 140
 141 An example from this JSON log is shown below:
 142
 143 .. code-block:: json
 144
 145     {
 146         "uuid": "0f40196a-78bb-11e8-bac7-005056865aac",
 147         "agent address": "127.0.0.1",
 148         "agent name": "server001",
 149         "cambria.partition": "server001",
 150         "community": "",
 151         "community len": 0,
 152         "epoch_serno": 15299605440000,
 153         "protocol version": "v2c",
 154         "time received": 1529960544.4896748,
 155         "trap category": "DCAE-COLLECTOR-UCSNMP",
 156         "sysUptime": "751564798",
 157         "notify OID": "1.3.6.1.4.1.999.0.1",
 158         "notify OID len": 9,
 159         "varbinds": [
 160             {
 161                 "varbind_oid": "1.3.6.1.4.1.999.0.1.1",
 162                 "varbind_type": "OctetString",
 163                 "varbind_value": "TEST TRAP"
 164             }
 165         ]
 166     }
 167
 168
 169
 170 EELF
 171 ^^^^
 172
 173 For program/operational logging, **SNMPTRAP** follows the EELF logging
 174 convention.  Please be aware that the EELF specification results in
 175 messages spread across various files.  Some work may be required to
 176 find the right location (file) that contains the message you are
 177 looking for.
 178
 179 EELF logging is controlled by the configuration provided
 180 to **SNMPTRAP** by CBS, or via the fallback config file specified
 181 as an environment variable "CBS_SIM_JSON" at startup.  The section
 182 of that JSON configuration that influences EELF logging is:
 183
 184 .. code-block:: json
 185
 186     "files": {
 187         <other json data>
 188         ...
 189         "**eelf_base_dir**": "/opt/app/snmptrap/logs",
 190         "eelf_error": "error.log",
 191         "eelf_debug": "debug.log",
 192         "eelf_audit": "audit.log",
 193         "eelf_metrics": "metrics.log",
 194         "roll_frequency": "hour",
 195     },
 196     <other json data>
 197     ...
 198
 199
 200 The base directory for all EELF logs is specified with:
 201
 202         **eelf_base_dir**
 203
 204 Remaining eelf_<file> references are appended to the eelf_base_dir value
 205 to specify a logfile location.  The result using the above example would
 206 create the files:
 207
 208 .. code-block:: bash
 209
 210         /opt/app/snmptrap/logs/error.log
 211         /opt/app/snmptrap/logs/debug.log
 212         /opt/app/snmptrap/logs/audit.log
 213         /opt/app/snmptrap/logs/metrics.log
 214
 215 Again using the above example configuration, these files will be rolled
 216 to an archived/timestamped version hourly.  The actually archival (to a
 217 timestamped filename) occurs when the first trap is
 218 received **in a new hour** (or minute, or day - depending
 219 on "roll_frequency" value).
 220
 221 Error / Warning Messages
 222 ------------------------
 223
 224 Program Diagnostics
 225 ^^^^^^^^^^^^^^^^^^^
 226
 227 Detailed application log messages can be found in "snmptrapd_diag" (JSON
 228 config reference).  These can be very verbose and roll quickly
 229 depending on trap arrival rates, number of varbinds encountered,
 230 minimum_severity_to_log setting in JSON config, etc.
 231
 232 In the default config, this file can be found at:
 233
 234 .. code-block:: bash
 235
 236     /opt/app/snmptrap/logs/snmptrapd_diag.log
 237
 238 Messages will be in the general format of:
 239
 240 .. code-block:: none
 241
 242     2018-04-25T17:28:10,305|<module>|snmptrapd||||INFO|100||arriving traps logged to: /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
 243     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
 244     2018-04-25T17:28:10,306|<module>|snmptrapd||||INFO|100||Runtime PID file: /opt/app/snmptrap/tmp/snmptrapd.py.pid
 245     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
 246     2018-04-25T17:28:48,023|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||dns cache expired or missing for 192.168.1.139 - refreshing
 247     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
 248     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
 249     2018-04-25T17:28:48,036|notif_receiver_cb|snmptrapd||||DETAILED|100||processing varbinds for 0f40196a-78bb-11e8-bac7-005056
 250     2018-04-25T17:28:48,040|notif_receiver_cb|snmptrapd||||DETAILED|100||adding 0f40196a-78bb-11e8-bac7-005056 to buffer
 251
 252     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.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"}]}
 253     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"}]}
 254
 255
 256 Platform Status
 257 ^^^^^^^^^^^^^^^
 258
 259 .. code-block:: json
 260
 261         "perm_status_file": "snmptrapd_status.log",