Chapter 8. Logging Events from Applications and Scripts
Prev |  | Next

## Chapter 8. Logging Events from Applications and Scripts

The ESP framework provides two ways for you to send events from your local applications and scripts to ESP:

- By using the `eventmon` Application Programming Interface (API)

- By using the `esplogger` tool

| Note: You can also use the `openlog`, `syslog`, and `closelog` SYSLOG functions to send event information through SYSLOG. Refer to the `syslog(3c)` man page for more information.

## Event Classification and Sequence Numbers

The ESP framework uses a standardized event classification scheme for the events that it registers. This classification scheme was implemented to:

- Provide a meaningful representation of the events that have occurred so that users can easily interpret them

- Provide an easy way to locate the source of an error by providing a general category and more specific information

In this scheme, events are categorized by class and type. An event class describes a general area that ESP monitors (for example, SCSI). An event type provides greater detail about individual events (for example, a SCSI controller initialization failure).

ESP automatically generates event class and type numbers when you create custom events and classes. You can use these numbers with your local applications and scripts to send event information to the ESP framework through the `eventmon` API and `esplogger` tool.

The ESP framework also uses unique sequence numbers for system messages. These sequence numbers provide a mechanism that enables ESP to isolate problems at the source code level.

## Using the eventmon API

The `eventmon` API contains a set of functions that you can call from your local C or C++ programs to send event information to the event monitoring component of ESP (`eventmond`). The `eventmon` API includes the following functions:

- `int EVMONAPI emapiIsDaemonInstalled();`

  This function determines whether the `eventmond` software is installed on the system.

  Parameters:

  None

  Return value:

  An integer: A nonzero value indicates that the `/usr/etc/eventmond` executable file exists on the system. A zero indicates that the file does not exist on the system.

- `int EVMONAPI emapiIsDaemonStarted();`

  This function determines whether `eventmond` is running on the system. You should use this function to verify that `eventmond` is running before you use any other `eventmon` API functions.

  Parameters:

  None

  Return value:

  An integer: A nonzero value indicates that `eventmond` is running on the system. A zero indicates that `eventmond` is not running on the system.

- `int EVMONAPI emapiDeclareDaemonUnload();`

  This function unloads `eventmond` from memory. (Note that the `eventmond` daemon can remain in the memory for up to 2 seconds after this function is called while the unload process completes.)

  Parameters:

  None

  Return value:

  An integer: A nonzero value indicates that `eventmond` successfully unloaded from memory. A zero indicates that an error prevented `eventmond` from successfully unloading from memory.

  An application must have root permissions/privileges to call this function.

- `int EVMONAPI emapiDeclareDaemonReloadConfig();`

  This function causes `eventmond` to reload the configuration information. This process includes three steps:

  1. Drop all filtering information from the internal `eventmond` memory tables.

  2. Connect to system tables that contain the filtering information.

  3. Reconfigure the internal `eventmond` memory tables with the information from the system tables.

  This function has the same functionality as the following shell command:

  `kill -HUP` eventmon_pid

  Parameters:

  None

  Return value:

  An integer: A nonzero value indicates that `eventmond` successfully reloaded the configuration information. A zero indicates that an error prevented `eventmond` from successfully reloading the configuration information.

  An application must have root permissions/privileges to call this function.

- `int EVMONAPI emapiSendEvent(char *hostname_from,unsigned long timehost,int etype, int epri, char *eventbuffer);`

  This function sends information about an event (event class sequence number and priority/facility code) to `eventmond`.

  Parameters:

  `char *hostname_from`

  - The name of the host where the event occurred (Use NULL to indicate the local host.)

  `unsigned long timehost`

  - The time stamp (in seconds since 00:00:00 UTC on January 1, 1970) of the event (Use 0 to specify the current time.)

  `int etype`

  - A number that specifies the event type (must be a nonzero value)

  `int epri`

  - The priority/facility code

  `char *eventbuffer`

  - A valid ASCIZ buffer that contains the event message string (It must be a valid string pointer and have a nonzero size.)
    The buffer cannot be larger than the number of bytes specified by EVMONAPI_MAXEVENTSIZE (16 KB, as defined in the `eventmonapi.h` file).

  Return value:

  An integer: A nonzero value indicates that the information was successfully passed to `eventmond` for processing. A zero indicates that an error prevented the information from successfully reaching `eventmond`.

The following sample code fragment demonstrates how to use the `eventmon` API:

          #include <stdio.h>
          #include <sys/syslog.h>
          #include <eventmonapi.h>

          main()
          { if(!emapiIsDaemonStarted())
            { printf("EventMon daemon not started!\n”);
              exit(0);
            }
            return emapiSendEvent("legalov.sgi.com",0,0x20101C,
                   LOG_MAKEPRI(LOG_USER,LOG_INFO), "Hello world!");
          }

## Using the esplogger Tool

Use the `esplogger` tool to pass event information from your local scripts to the event monitoring component of ESP (`eventmond`). You can run `esplogger` from a UNIX prompt or from a UNIX shell script. `esplogger` uses the following command syntax:

    esplogger -s <sequence_number> {-f <filename> | -m "<message>"} [-p <priority>] [-t <time>]
    esplogger -h
    esplogger -V

where:

- The -`s <sequence_number>` option specifies the sequence number (in decimal or hexadecimal). You must use this option with the `-t` option and the `-f` or `-m` options.

- The `-f <filename>` option specifies the file that contains data to log in the ESP framework. You must include the `-s` option with this option. You cannot use this option with the `-m` option.

- The `-m <message >` option specifies a message to log in the ESP framework. You must include the `-s` option with this option. You cannot use this option with the `-f` option.

- The `-p <priority>` option specifies the priority (for example, local0.notice). Refer to the `syslog(3C)` man page for descriptions of the priority values. If you do not specify a priority value, `esplogger` sets the priority to local0.info. You must use this option with the `-s` option and the `-f` or `-m` option.

- The `-t <time>` option specifies the time that the event occurred. You must specify the time in seconds since 00:00:00 UTC on January 1, 1970 (in decimal notation). If you do not specify the time, `esplogger` defaults the time to the time that it received the event. You must use this option with the `-s` option and the `-f` or `-m` option.

- The `-h` option prints the usage information.

- The `-V` option prints the `esplogger` version number.

| Note: You can also use `logger` to send event information through SYSLOG. Refer to the `logger(1)` man page for more information.

### Example 1

    esplogger -s 200356 -f availmon.dat

This example sets the sequence number to 200356, the priority to local0.info (1030), and the time to the time that `esplogger` received the event. Then, it passes this information and the data in the `availmon.dat` file to `eventmond`.

### Example 2

    esplogger -s 0x00200000 -p syslog.warning -m "Start SVP"

This example sets the sequence number to 0x00200000, the priority to syslog.warning (324), and the time to the time that `esplogger` received the event. Then, it passes this information and the message to `eventmond`.

Prev | Table of Contents | Next
Chapter 7. Sending Notifications |  | Chapter 9. Default Event Classes and Types