docs/sections/services/snmptrap/logging.rst - onap/dcaegen2 - Gitiles

 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0

 Logging
 =======

 Logging is controlled by the configuration provided to **SNMPTRAP** by CBS,
 or via the fallback config file specified as the environment
 variable "CBS_SIM_JSON" at startup.  The section of that JSON configuration
 that influences the various forms of application logging is referenced
 throughout this document, with examples.

 Using the JSON configuration, a base directory is specified for application
 data and EELF log files.  Specific filenames (again, from the JSON
 config) are appended to the base directory value to create a full-path
 filename for use by SNMPTRAP.

 Also available is the ability to modify how frequently logs are rolled to
 time-stamped versions (and a new empty file is started) as well as what
 severity level to log to program diagnostic logs.  Files will be rolled to
 an archived/timestamped version hourly.  The actual archival (to a
 timestamped filename) occurs when the first trap is
 received **in a new hour** (or minute, or day - depending
 on "roll_frequency" value).

 Defaults are shown below:

 .. code-block:: json

     "files": {
         <other json data>
         ...
         "roll_frequency": "hour",
         "minimum_severity_to_log": 2
         <other json data>
         ...
     },


 Where to Access Information: APPLICATION DATA (TRAPS)
 -----------------------------------------------------

 APPLICATION DATA (TRAPS)
 ^^^^^^^^^^^^^^^^^^^^^^^^

 **SNMPTRAP** produces application-specific logs (e.g. trap logs/payloads,
 etc) as well as various other statistical and diagnostic logs.  The
 location of these logs is controlled by the JSON config, using these
 values:

 .. code-block:: json

     "files": {
         "**runtime_base_dir**": "/opt/app/snmptrap",
         "log_dir": "logs",
         "data_dir": "data",
         "pid_dir": "tmp",
         "arriving_traps_log": "snmptrapd_arriving_traps.log",
         "snmptrapd_diag": "snmptrapd_prog_diag.log",
         "traps_stats_log": "snmptrapd_stats.csv",
         "perm_status_file": "snmptrapd_status.log",
         "roll_frequency": "hour",
         "minimum_severity_to_log": 2
         <other json data>
         ...
     },

 The base directory for all data logs is specified with:

     **runtime_base_dir**

 Remaining log file references are appended to the *runtime_base_dir*
 value to specify a logfile location.  The result using the
 above example would create the files:

 .. code-block:: bash

     /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
     /opt/app/snmptrap/logs/snmptrapd_prog_diag.log
     /opt/app/snmptrap/logs/snmptrapd_stats.csv
     /opt/app/snmptrap/logs/snmptrapd_status.log


 ARRIVING TRAPS
 ^^^^^^^^^^^^^^^

 **SNMPTRAP** logs all arriving traps.  These traps are saved in a
 filename created by appending *runtime_base_dir*, *log_dir*
 and *arriving_traps_log* from the JSON config.  Using the example
 above, the resulting arriving trap log would be:

 .. code-block:: bash

     /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log

 An example from this log is shown below:

 .. code-block:: none

     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"}]

 *(Add:  varbind type enumerations)*

 PUBLISHED TRAPS
 ^^^^^^^^^^^^^^^

 SNMPTRAP's first priority is to receive and decode SNMP traps, then
 publish the results to a configured DMAAP/MR message bus.  Traps that
 are successfully published (e.g. publish attempt gets a "200/ok"
 response from the DMAAP/MR server) are logged to a file named by
 the technology being used combined with the topic being published to.

 If you find a trap in this published log, it has been acknowledged as
 received by DMAAP/MR.  If consumers complain of "missing traps", the
 source of the problem will be downstream (*not with SNMPTRAP*) if
 the trap has been logged here.

 For example, with a json config of:

 .. code-block:: json

     "dmaap_info": {
         "location": "mtl5",
         "client_id": null,
         "client_role": null,
         "topic_url": "http://172.17.0.1:3904/events/ONAP-COLLECTOR-SNMPTRAP"

 and

 .. code-block:: json

     "files": {
         "**runtime_base_dir**": "/opt/app/snmptrap",

 result in traps that are confirmed (200/ok) as published logged to the file:

 .. code-block:: bash

     /opt/app/snmptrap/logs/DMAAP_ONAP-COLLECTOR-SNMPTRAP.json

 An example from this JSON log is shown below:

 .. code-block:: json

     {
         "uuid": "0f40196a-78bb-11e8-bac7-005056865aac",
         "agent address": "127.0.0.1",
         "agent name": "server001",
         "cambria.partition": "server001",
         "community": "",
         "community len": 0,
         "epoch_serno": 15299605440000,
         "protocol version": "v2c",
         "time received": 1529960544.4896748,
         "trap category": "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"
             }
         ]
     }


 EELF
 ^^^^

 For program/operational logging, **SNMPTRAP** follows the EELF logging
 convention.  Please be aware that the EELF specification results in
 messages spread across various files.  Some work may be required to
 find the right location (file) that contains the message you are
 looking for.

 EELF logging is controlled by the configuration provided
 to **SNMPTRAP** by CBS, or via the fallback config file specified
 as an environment variable "CBS_SIM_JSON" at startup.  The section
 of that JSON configuration that influences EELF logging is:

 .. code-block:: json

     "files": {
         <other json data>
         ...
         "**eelf_base_dir**": "/opt/app/snmptrap/logs",
         "eelf_error": "error.log",
         "eelf_debug": "debug.log",
         "eelf_audit": "audit.log",
         "eelf_metrics": "metrics.log",
         "roll_frequency": "hour",
     },
     <other json data>
     ...


 The base directory for all EELF logs is specified with:

         **eelf_base_dir**

 Remaining eelf_<file> references are appended to the eelf_base_dir value
 to specify a logfile location.  The result using the above example would
 create the files:

 .. code-block:: bash

         /opt/app/snmptrap/logs/error.log
         /opt/app/snmptrap/logs/debug.log
         /opt/app/snmptrap/logs/audit.log
         /opt/app/snmptrap/logs/metrics.log

 Again using the above example configuration, these files will be rolled
 to an archived/timestamped version hourly.  The actually archival (to a
 timestamped filename) occurs when the first trap is
 received **in a new hour** (or minute, or day - depending
 on "roll_frequency" value).

 Error / Warning Messages
 ------------------------

 Program Diagnostics
 ^^^^^^^^^^^^^^^^^^^

 Detailed application log messages can be found in "snmptrapd_diag" (JSON
 config reference).  These can be very verbose and roll quickly
 depending on trap arrival rates, number of varbinds encountered,
 minimum_severity_to_log setting in JSON config, etc.

 In the default config, this file can be found at:

 .. code-block:: bash

     /opt/app/snmptrap/logs/snmptrapd_diag.log

 Messages will be in the general format of:

 .. code-block:: none

     2018-04-25T17:28:10,305|<module>|snmptrapd||||INFO|100||arriving traps logged to: /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
     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
     2018-04-25T17:28:10,306|<module>|snmptrapd||||INFO|100||Runtime PID file: /opt/app/snmptrap/tmp/snmptrapd.py.pid
     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
     2018-04-25T17:28:48,023|snmp_engine_observer_cb|snmptrapd||||DETAILED|100||dns cache expired or missing for 192.168.1.139 - refreshing
     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
     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
     2018-04-25T17:28:48,036|notif_receiver_cb|snmptrapd||||DETAILED|100||processing varbinds for 0f40196a-78bb-11e8-bac7-005056
     2018-04-25T17:28:48,040|notif_receiver_cb|snmptrapd||||DETAILED|100||adding 0f40196a-78bb-11e8-bac7-005056 to buffer

     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"}]}
     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"}]}


 Platform Status
 ^^^^^^^^^^^^^^^

 .. code-block:: json

         "perm_status_file": "snmptrapd_status.log",
	.. This work is licensed under a Creative Commons Attribution 4.0 International License.
	.. http://creativecommons.org/licenses/by/4.0

	Logging
	=======

	Logging is controlled by the configuration provided to SNMPTRAP by CBS,
	or via the fallback config file specified as the environment
	variable "CBS_SIM_JSON" at startup. The section of that JSON configuration
	that influences the various forms of application logging is referenced
	throughout this document, with examples.

	Using the JSON configuration, a base directory is specified for application
	data and EELF log files. Specific filenames (again, from the JSON
	config) are appended to the base directory value to create a full-path
	filename for use by SNMPTRAP.

	Also available is the ability to modify how frequently logs are rolled to
	time-stamped versions (and a new empty file is started) as well as what
	severity level to log to program diagnostic logs. Files will be rolled to
	an archived/timestamped version hourly. The actual archival (to a
	timestamped filename) occurs when the first trap is
	received in a new hour (or minute, or day - depending
	on "roll_frequency" value).

	Defaults are shown below:

	.. code-block:: json

	"files": {
	<other json data>
	...
	"roll_frequency": "hour",
	"minimum_severity_to_log": 2
	<other json data>
	...
	},


	Where to Access Information: APPLICATION DATA (TRAPS)
	-----------------------------------------------------

	APPLICATION DATA (TRAPS)
	^^^^^^^^^^^^^^^^^^^^^^^^

	SNMPTRAP produces application-specific logs (e.g. trap logs/payloads,
	etc) as well as various other statistical and diagnostic logs. The
	location of these logs is controlled by the JSON config, using these
	values:

	.. code-block:: json

	"files": {
	"runtime_base_dir": "/opt/app/snmptrap",
	"log_dir": "logs",
	"data_dir": "data",
	"pid_dir": "tmp",
	"arriving_traps_log": "snmptrapd_arriving_traps.log",
	"snmptrapd_diag": "snmptrapd_prog_diag.log",
	"traps_stats_log": "snmptrapd_stats.csv",
	"perm_status_file": "snmptrapd_status.log",
	"roll_frequency": "hour",
	"minimum_severity_to_log": 2
	<other json data>
	...
	},

	The base directory for all data logs is specified with:

	runtime_base_dir

	Remaining log file references are appended to the runtime_base_dir
	value to specify a logfile location. The result using the
	above example would create the files:

	.. code-block:: bash

	/opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
	/opt/app/snmptrap/logs/snmptrapd_prog_diag.log
	/opt/app/snmptrap/logs/snmptrapd_stats.csv
	/opt/app/snmptrap/logs/snmptrapd_status.log


	ARRIVING TRAPS
	^^^^^^^^^^^^^^^

	SNMPTRAP logs all arriving traps. These traps are saved in a
	filename created by appending runtime_base_dir, log_dir
	and arriving_traps_log from the JSON config. Using the example
	above, the resulting arriving trap log would be:

	.. code-block:: bash

	/opt/app/snmptrap/logs/snmptrapd_arriving_traps.log

	An example from this log is shown below:

	.. code-block:: none

	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"}]

	(Add: varbind type enumerations)

	PUBLISHED TRAPS
	^^^^^^^^^^^^^^^

	SNMPTRAP's first priority is to receive and decode SNMP traps, then
	publish the results to a configured DMAAP/MR message bus. Traps that
	are successfully published (e.g. publish attempt gets a "200/ok"
	response from the DMAAP/MR server) are logged to a file named by
	the technology being used combined with the topic being published to.

	If you find a trap in this published log, it has been acknowledged as
	received by DMAAP/MR. If consumers complain of "missing traps", the
	source of the problem will be downstream (not with SNMPTRAP) if
	the trap has been logged here.

	For example, with a json config of:

	.. code-block:: json

	"dmaap_info": {
	"location": "mtl5",
	"client_id": null,
	"client_role": null,
	"topic_url": "http://172.17.0.1:3904/events/ONAP-COLLECTOR-SNMPTRAP"

	and

	.. code-block:: json

	"files": {
	"runtime_base_dir": "/opt/app/snmptrap",

	result in traps that are confirmed (200/ok) as published logged to the file:

	.. code-block:: bash

	/opt/app/snmptrap/logs/DMAAP_ONAP-COLLECTOR-SNMPTRAP.json

	An example from this JSON log is shown below:

	.. code-block:: json

	{
	"uuid": "0f40196a-78bb-11e8-bac7-005056865aac",
	"agent address": "127.0.0.1",
	"agent name": "server001",
	"cambria.partition": "server001",
	"community": "",
	"community len": 0,
	"epoch_serno": 15299605440000,
	"protocol version": "v2c",
	"time received": 1529960544.4896748,
	"trap category": "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"
	}
	]
	}



	EELF
	^^^^

	For program/operational logging, SNMPTRAP follows the EELF logging
	convention. Please be aware that the EELF specification results in
	messages spread across various files. Some work may be required to
	find the right location (file) that contains the message you are
	looking for.

	EELF logging is controlled by the configuration provided
	to SNMPTRAP by CBS, or via the fallback config file specified
	as an environment variable "CBS_SIM_JSON" at startup. The section
	of that JSON configuration that influences EELF logging is:

	.. code-block:: json

	"files": {
	<other json data>
	...
	"eelf_base_dir": "/opt/app/snmptrap/logs",
	"eelf_error": "error.log",
	"eelf_debug": "debug.log",
	"eelf_audit": "audit.log",
	"eelf_metrics": "metrics.log",
	"roll_frequency": "hour",
	},
	<other json data>
	...


	The base directory for all EELF logs is specified with:

	eelf_base_dir

	Remaining eelf_<file> references are appended to the eelf_base_dir value
	to specify a logfile location. The result using the above example would
	create the files:

	.. code-block:: bash

	/opt/app/snmptrap/logs/error.log
	/opt/app/snmptrap/logs/debug.log
	/opt/app/snmptrap/logs/audit.log
	/opt/app/snmptrap/logs/metrics.log

	Again using the above example configuration, these files will be rolled
	to an archived/timestamped version hourly. The actually archival (to a
	timestamped filename) occurs when the first trap is
	received in a new hour (or minute, or day - depending
	on "roll_frequency" value).

	Error / Warning Messages
	------------------------

	Program Diagnostics
	^^^^^^^^^^^^^^^^^^^

	Detailed application log messages can be found in "snmptrapd_diag" (JSON
	config reference). These can be very verbose and roll quickly
	depending on trap arrival rates, number of varbinds encountered,
	minimum_severity_to_log setting in JSON config, etc.

	In the default config, this file can be found at:

	.. code-block:: bash

	/opt/app/snmptrap/logs/snmptrapd_diag.log

	Messages will be in the general format of:

	.. code-block:: none

	2018-04-25T17:28:10,305\|<module>\|snmptrapd\|\|\|\|INFO\|100\|\|arriving traps logged to: /opt/app/snmptrap/logs/snmptrapd_arriving_traps.log
	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
	2018-04-25T17:28:10,306\|<module>\|snmptrapd\|\|\|\|INFO\|100\|\|Runtime PID file: /opt/app/snmptrap/tmp/snmptrapd.py.pid
	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
	2018-04-25T17:28:48,023\|snmp_engine_observer_cb\|snmptrapd\|\|\|\|DETAILED\|100\|\|dns cache expired or missing for 192.168.1.139 - refreshing
	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
	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
	2018-04-25T17:28:48,036\|notif_receiver_cb\|snmptrapd\|\|\|\|DETAILED\|100\|\|processing varbinds for 0f40196a-78bb-11e8-bac7-005056
	2018-04-25T17:28:48,040\|notif_receiver_cb\|snmptrapd\|\|\|\|DETAILED\|100\|\|adding 0f40196a-78bb-11e8-bac7-005056 to buffer

	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"}]}
	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"}]}


	Platform Status
	^^^^^^^^^^^^^^^

	.. code-block:: json

	"perm_status_file": "snmptrapd_status.log",