EPICS

CA Put Logging

ABSTRACT:	CA Put Logging was developed for DESY EPICS as an additional
		mean to keep tracks of CA puts separately from system IOC 
		logging. This feature is enabled when Access Security is 
		enabled. AS configuration file defines the rules for logging
		CA Puts. The necessary environment variables should be set to 
		enable various forms of logging. Each CA put request is
		registered as a message in a Ring Buffer. Another task 
		(RngLogTask) is responsible to read messages from the Ring 
		Buffer and log them into specified log file and, optionally,
		into Process Variable (PV).

1. CA Put Logging and Access Security

CA Put Logging provides logging of information related to CA Puts performed by various CA clients on Process Variables (PV) located in particular IOC. CA Put Logging can be enabled only when Access Security (AS) is enabled for a particular IOC.

CA Put Logging is done in two steps. At first needed information is extracted and is saved into a Ring Buffer (registering stage). Afterwards another task takes registering information from the Ring Buffer and produces the complete logging message.

1.1. New feature of AS configuration rules.

To provide a possibility to log only CA Puts of interest the new AS rules looks like:

ASG() [{
        [INP()
        ...]
        RULE(,NONE | READ | WRITE [, NOTRAPWRITE | TRAPWRITE] ) {
                [UAG( [, ...])]
                [HAG( [, ...])]
                CALC("")
        }
        ...
}]

Default keyword for CA Puts trapping is NOTRAPWRITE. All CA Puts allowed by AS to be trapped (having TRAPWRITE keyword) will be registered and logged.

1.2. Logged information.

The logged information includes the following data:

1. Data and Time when CA put request happened
2. Host name from which CA put request was sent
3. User name who send CA put request
4. Value of Process Variable (PV) before CA put request
5. Value of PV after CA put request (or sequence of requests)
6. If there were a sequence of CA put requests to the same PV within short time interval maximum and minimum values within current sequence. (this is done for numerical values only).

All this informations is written to specified for particular IOC separated log file and (optionally) is logged into a local for the IOC PV.

NOTE:

Usually, a log message contains more than 40 characters, so stringout EPICS record cannot be used for this purposes as a PV. The transferring of log message into PV is done as a character array (up to 120 characters). Therefore, it is recommended to use for this purpose either waveform record or the home developed rsl-record allowing to save up to 120 characters as a characters array.

Example of logging message for single CA Put:

epicsVME09 Sat Jan 20 00:35:22 2001  20-Jan-01 00:35:17 kryksunh kagarman AHTST:out1_ao.VAL new=3 old=31

Example of logging message for sequence of CA Puts:

epicsVME09 Sat Jan 20 00:46:10 2001  20-Jan-01 00:46:05 kryksunh kagarman AHTST:out1_ao.VAL new=31 old=3 min=3 max=31

NOTE:

In the examples above the IOC name (epicsVME09) followed by the date and time are concatenated by UNIX iocLogServer when it logs the message from IOC. Second date and time represents the IOC time stamp when CA Put request was registered.

3. Software modules participating in CA Put Logging

3.1. EPICS release requirements.

Starting from EPICS release 3.13.4 in iocCore will be implemented Trap Write Hook, that allows to perform CA Put Logging. For ERICS releases earlier than 3.13.4 iocCore needs some modification to include CA Put Logging features.

3.2. EPICS release 3.13.4.

All the necessary routines and libraries to provide Trap Write Hook are placed into base. Modules dealing with CA Put Logging are placed in the directory EpicsBase/src/caPutLog.

3.2.1. Start, stop and CA Put registering routines

The routines to start and stop CA Put Logging and to register CA Put requests are placed in the module caPutLogRng.c.

caPutLogInit routine initializes CA Put Logging during startup (or in run time). It has one argument. It defines the option which CA Puts have to be logged:

1. 0 - log only Puts changing values (default)
2. 1 - log all Puts

caPutLogStop routine stops CA Put Logging and releases all used resources.

caPutLog routine performs registering of each trapped by TrapWriteHook CA Puts into the Ring Buffer.

3.2.2. Ring Buffer logging task

When this task detects a whole sequence of put requests dealing with the same PV name it forms only one logging message fixing the value of PV before the sequence and the value in the last put request of the sequence. For numerical values the maximum and minimum values within the given sequence are also fixed. This task is started by caPutLogInit. It is terminated by caPutLogStop.

3.2.3. Special IOC log client (iocCAPutLogClient)

The scheme of modules interrelations is presented below:

      --------------------------------------
      |              I O C                 |
      --------------------------------------
      |TrapWriteHook +-------+             |
      |     |        | Ring  |-> RngLogTask|
      |     v        |Buffer |     |   |   |
      |  caPutLog--->|       |     |   |   |
      |              +-------+     v   |   |
      |                            PV  |   |
      |                                |   |      +------+
      |                                v   |      |      |
      |                  iocCAPutLogClient------->| UNIX |
      |                                    |      |      |
      +------------------------------------+      +------+
      

3.3. EPICS releases earlier than 3.13.4.

For these releases should be modified directory EpicsBase/src/as. All the necessary modules implementing Trap Write Hook should be placed there. In the directory EpicsBase/src/rsrv in the file camessage.c before and after db_put_field call should be placed call to Trap Write Hook. One can find all the necessary sources on our ftp-server.

4. Enabling/disabling of CA Put Logging

4.1.Enabling of Access Security.

In order to enable CA Put Logging it is necessary first to enable AS. This procedure is described in EPICS Application Developer's Guide [1]. In AS configuration file for all UAG, HAG, ASG and ASL having WRITE access have to be added keyword TRAPWRITE for those elements whose CA Puts have to be trapped (by default it is implied NOTRAPWRITE).

4.2. CA Put Logging environment variables (IOC side).

• EPICS_IOC_CA_PUT_LOG_INET - environment variable defining the Internet address of Log server (on UNIX side). If this variable is not defined or its value is empty the Internet address for standard IOC Log client is used (it must be defined in EPICS_IOC_LOG_INET environment variable, or by default is taken from EPICS configuration file CONFIG_SITE_ENV in directory base/config/)
• EPICS_IOC_CA_PUT_LOG_PORT - environment variable defining the port number of Log server (on UNIX side). By default the port number 7010 is used.
• EPICS_AS_PUT_LOG_PV - environment variable defining the PV name where CA put logging will be done (additionally to logging into UNIX file). It is recommended to use for these purposes waveform or RSL-record type [2]. If this variable is not defined or its value is empty logging into PV will be disabled.

4.3. Downloading and initialization of CA Put Logging

To support CA Put Logging additional modules should be downloaded into IOC:

EPICS release containing Trap Write Hook (3.13.4)

1. caPutLog.o
2. RngLogTask.o
3. iocCAPutLogClient.o

For EPICS release earlier than 3.13.4 modified iocCore containing Trap Write Hook should be downloaded.

To initialize and start CA Put Logging it is necessary to issue one of the following commands to the vxWorks shell:

1. caPutLogInit or caPutLogInit(0) - to start CA Put Logging for Puts changing PV value
2. caPutLogInit(1) - to start CA Put Logging for all CA Puts.

If Access Security is enabled all necessary modules are loaded and all environment variables described above are properly set CA put Logging will be enabled, RngLogTask and iocCAPutLogClient tasks will be initialized. If one (or both) of these two modules is not loaded will be printed message which module is missed, and CA Put Logging will be disabled. To enable it one should load missed modules (with ld shell command) and reinitialize CA Put Logging with caPutLogInit command. (To avoid these manual procedures for next reboot, an appropriate amendments should be done with startup files, in particular, include loading of missed modules in startup).

4.4. CA Put Logging disabling.

In order to disable CA Put Logging into PV one should issue the following command to the vxWorks shell:

caPutLogStop

On this command CA Put Logging will be stopped and all used resources will be released.

To terminate CA Put Logging into PV should be executed the following sequence of actions:

1. CA Put Logging should be stopped (caPutLogStop command)
2. Set EPICS_AS_PUT_LOG_PV environment variable to empty string by typing: putenv("EPICS_AS_PUT_LOG_PV=");
3. Start CA Put Logging again with caPutLogInit command.

5. iocLogServer on UNIX side

In order to save CA Put Log messages on UNIX computer into separate (from general logging) file there must be started one more standard iocLogServer but having different port number. The same port number have to be set in IOC for EPICS_IOC_CA_PUT_LOG_PORT environment variable (see p.4.2).

References

1. Application Developer's Guide.
2. RSL-record type.