7. How to specify you own custom shell instructions#

Prerequisites:

In order to specify you own custom shell instructions, here are the steps to follow:

Find what you want to monitor. E.g. let’s pretend you want to monitor the following metrics:
- Cumulated CPU usage (over all CPU cores) of Firefox.
- Cumulated CPU usage (over all CPU cores) of Java.
- Cumulated CPU usage (over all CPU cores) of CSS (Control System Studio).
- Error message in /path/to/file.log.
- Error message in /path/to/another-file.log.
Find out what shell instruction you want to use in order to retrieve the wanted data for each thing to monitor. E.g.:
- Cumulated CPU usage (over all CPU cores) of Firefox:
```
ps -eo %cpu,args | grep firefox | awk '{print $1}' | paste -sd+ - | bc
```
- Cumulated CPU usage (over all CPU cores) of Java:
```
ps -eo %cpu,args | grep java | awk '{print $1}' | paste -sd+ - | bc
```
- Cumulated CPU usage (over all CPU cores) of CSS (Control System Studio):
```
ps -eo %cpu,args | grep css | awk '{print $1}' | paste -sd+ - | bc
```
- Error message in /path/to/file.log:
```
cat /path/to/file.log | grep -i 'error'
```
- Error message in /path/to/another-file.log.
```
cat /path/to/another-file.log | grep -i 'error'
```

On the target, make sure that the needed packages have been white-listed like described in the security how-to. I.e., in this example the needed packages are ps, grep, awk, paste, bc and cat, so after following carefully the security how-to instructions, here is how to white-list the needed packages:

target $ sudo ln -s /bin/ps /home/sshmonitor-user/bin
target $ sudo ln -s /bin/grep /home/sshmonitor-user/bin
target $ sudo ln -s /bin/awk /home/sshmonitor-user/bin
target $ sudo ln -s /bin/paste /home/sshmonitor-user/bin
target $ sudo ln -s /bin/bc /home/sshmonitor-user/bin
target $ sudo ln -s /bin/cat /home/sshmonitor-user/bin

Create a .substitutions file in order to specify the shell instructions. E.g. in this example, you might want a substitution file that looks like the one bellow:

$ vi myTargetMonitoringTop/iocBoot/iocMyTargetMonitoring/custom_monitoring.substitutions

    > global
    > {
    >     PREFIX = "${PREFIX_MACRO}"
    >     SSH_OPTS_AND_ARGS = "${SSH_OPTS_AND_ARGS_MACRO}"
    > }
    >
    > file "${TOP}/db/ssh_monitor_core.template"
    > {
    >     {
    >         CATEGORY = "custom:"
    >
    >         # scalar shell instruction 1 used to extract CPU usage of Firefox
    >         # the result of this shell instruction is stored in the record called "${PREFIX}${CATEGORY}${PV_NAME_SCALAR_1}"
    >         PV_NAME_SCALAR_1 = "cpu_usage_firefox"
    >         SCALAR_1_INSTRUCTION = "ps -eo %cpu,args | grep firefox | awk '{print $1}' | paste -sd+ - | bc"
    >         LOAD_SCALAR_1 = ""
    >
    >         # scalar shell instruction 2 used to extract CPU usage of Java
    >         # (the result of this shell instruction is stored in the record called "${PREFIX}${CATEGORY}${PV_NAME_SCALAR_2}"
    >         PV_NAME_SCALAR_2 = "cpu_usage_java"
    >         SCALAR_2_INSTRUCTION = "ps -eo %cpu,args | grep java | awk '{print $1}' | paste -sd+ - | bc"
    >         LOAD_SCALAR_2 = ""
    >
    >         # scalar shell instruction 3 used to extract CPU usage of CSS (Control System Studio)
    >         # the result of this shell instruction is stored in the record called "${PREFIX}${CATEGORY}${PV_NAME_SCALAR_3}"
    >         PV_NAME_SCALAR_3 = "cpu_usage_css"
    >         SCALAR_3_INSTRUCTION = "ps -eo %cpu,args | grep css | awk '{print $1}' | paste -sd+ - | bc"
    >         LOAD_SCALAR_3 = ""
    >
    >         # string shell instruction 1 used to extract error message from /path/to/file.log
    >         # the result of this shell instruction is stored in the record called "${PREFIX}${CATEGORY}${PV_NAME_STRING_1}"
    >         PV_NAME_STRING_1 = "error_message_file_1"
    >         STRING_1_INSTRUCTION = "cat /path/to/file.log | grep -i 'error'"
    >         LOAD_STRING_1 = ""
    >
    >         # string shell instruction 2 used to extract error message from /path/to/another-file.log
    >         # the result of this shell instruction is stored in the record called "${PREFIX}${CATEGORY}${PV_NAME_STRING_2}"
    >         PV_NAME_STRING_2 = "error_message_file_2"
    >         STRING_2_INSTRUCTION = "cat /path/to/another-file.log | grep -i 'error'"
    >         LOAD_STRING_2 = ""
    >     }
    > }

Load your custom .substitutions file in the .cmd file (e.g. st_target1.cmd):

$ vi myTargetMonitoringTop/iocBoot/iocMyTargetMonitoring/st_target1.cmd

    > ...
  + > dbLoadTemplate("${TOP}/iocBoot/${IOC}/custom_monitoring.substitutions", "PREFIX_MACRO=${PREFIX}, SSH_OPTS_AND_ARGS_MACRO=${SSH_OPTS_AND_ARGS}")
    > ...

Run SSH Monitor and make sure everything is working as intended.