Writing Monitors for the Event Monitoring Service

Transcription

1 Writing Monitors for the Event Monitoring Service HP 9000 Networking Edition 1 E0897 Copyright 1997 Hewlett-Packard Company.

2 Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty. A copy of the specific warranty terms applicable to your Hewlett-Packard product and replacement parts can be obtained from your local Sales and Service Office. Restricted Rights Legend. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS for DOD agencies, and subparagraphs (c) (1) and (c) (2) of the Commercial Computer Software Restricted Rights clause at FAR for other agencies. Hewlett-Packard Company Homestead Road Cupertino, California U.S.A. Use of this manual and flexible disk(s) or tape cartridge(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited. 2

3 Copyright Notices copyright Hewlett-Packard Company, all rights reserved. Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as allowed under the copyright laws. Trademark Notices MC/ServiceGuard is a registered trademark of Hewlett-Packard Company. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. 3

4 4

5 Contents 1. Overview of the Event Monitoring Service Terms and Definitions The Event Monitoring Service (EMS) The EMS API The Registrar The Resource Dictionary The EMS Application Programming Interface (API) Functions Logging and Tracing rm_copy rm_create rm_destroy rm_get rm_get_next_event rm_log rm_monitor_start rm_monitor_stop rm_notify rm_perror rm_print rm_send_reply rm_set rm_strerror

6 Contents rm_uncompress_object Writing a Resource Monitor Steps Toward Writing and Installing a Resource Monitor Startup and Initialization Processing a Subclass Request Event Processing a Monitor Request Event Processing a Resource Update Event Processing a Terminate Event Processing an Unregister Event Testing a Resource Monitor with montest About the montest Tool Using montest How montest Works Sample montest output montest Error Messages Writing a Target Application Processing a Notification Message Processing a Restart Notification Object

7 1 Overview of the Event Monitoring Service 7

8 Overview of the Event Monitoring Service Terms and Definitions Terms and Definitions client EMS ITO notification polling interval Registrar resource resource class resource dictionary The application that sends or cancels requests to monitor particular resources. Examples of this are MC/ServiceGuard, when it starts a package, and the SAM interface to EMS, when a user creates a monitor request. Event Monitoring Service. A set of APIs, together with the Registrar process and the resource dictionary, which allow client applications to request that resources be monitored and a target application notified. The Event Monitoring Service defines the interface between resource monitors and the client and target applications. HP OpenView IT/Operations, formerly known as OperationsCenter. A communication from the resource monitor to the target application that an event has occurred during this polling interval that meets the user-configured criteria for notification. specifies how often the resource monitor should check the resource value to see if it satisfies the notification criteria. Valid values are seconds (24 hours). The Registrar process provides the link between resource status consumers (clients) and resource status providers (resource monitors). May be any entity an application developer names. Examples include a network interface, CPU statistics, a MIB object, a network service, and the status of a database. Refers to a category of resources (e.g. LAN ) and is useful during configuration. A file describing the hierarchy of resources that can be monitored and the processes that will perform the resource monitoring. 8 Chapter 1

9 Overview of the Event Monitoring Service Terms and Definitions resource instance resource monitor target Refers to an actual instantiation of a resource. For example, lan0 may refer to a particular network interface that is installed on the monitored system. The process that is used to obtain the status of a resource and send event notifications if appropriate. A monitor checks resources on the local system and sends notifications to the target application. The target application is notified when a monitored resource reaches the condition for which notification was requested. For example, the target application could be MC/ServiceGuard or ITO. Chapter 1 9

10 Overview of the Event Monitoring Service The Event Monitoring Service (EMS) The Event Monitoring Service (EMS) Figure 1-1 illustrates the major components of the Event Monitoring Service (EMS). EMS is made up of three major components: the EMS API, the Registrar, and the resource dictionary. These parts enable client applications, like MC/ServiceGuard and the SAM interface to EMS, to communicate with resource monitors. The resource monitors then inform target applications when the resources they monitor are at critical user-defined values. Figure 1-1 The Event Monitoring Service System A Client Application System B Target Application EMS API (optional) LAN System C Registrar Resource Dictionary Resource Monitor EMS API Resource-Specific Interface Resource The method of informing the target application of a critical resource value can vary for different target applications. Five notification mechanisms are supported: an MC/ServiceGuard method, a TCP/IP 10 Chapter 1

11 Overview of the Event Monitoring Service The Event Monitoring Service (EMS) method, and a UDP/IP method, an opcmsg method (for ITO), and a method using SNMP traps. The resource monitor application does not need to be aware of or understand the notification method for communicating with the target application. A client wishing to use the Event Monitoring Services makes requests to the Registrar to determine the available resources. The Registrar answers the requests using data from the resource dictionary. When a request is made that exceeds the scope of the information in the dictionary, the Registrar will launch monitor applications and pass the requests down to them. Monitor applications will answer back to the Registrar, which will reply back to the requester. After identifying the resources to monitor, the client will make a monitor request to the Registrar. The request will contain information about what to monitor and whom to notify when something interesting happens. The Registrar will pass this information down to the appropriate monitor application. The monitor application will check the resource as specified in the monitor request. The request can be for immediate or periodic checking against thresholds or state changes. When the resource does something interesting, the monitor will make a notification according to information in the monitor request. Chapter 1 11

12 Overview of the Event Monitoring Service The EMS API The EMS API The EMS API allows you to write resource monitors and target applications. Target applications are the processes that receive notification messages from the resource monitors. The EMS API defines a set of messages that allow a client application to register monitor requests with the appropriate resource monitors. The resource monitors use the API to communicate with the client applications, to make comparisons between the current resource values and pre-selected threshold values, and to send notifications to target applications when the resource values are deemed critical. Target applications use the API to translate UDP/IP or TCP/IP notification messages into EMS objects and then to read the fields of the EMS objects. The EMS API can be called from any program written in C or C++. The API has been designed to provide for future expansion while guaranteeing binary compatibility. The users of the API (client applications and resource monitors) operate on opaque Resource Monitor objects. Each object has standard functions defined that allow the user to store and retrieve information from the API without having to know the specifics of the objects implementation. This allows for future expansion of the API without forcing recompilation of the applications that use the API. In general, the EMS API is accessed through the /etc/opt/resmon/lib/libresmon.1 shared library. The API is installed entirely in user space. MC/ServiceGuard uses a special version of the client API functions due to its requirements to always be loaded in memory and to never write to disk. The API is not thread safe. 12 Chapter 1

13 Overview of the Event Monitoring Service The Registrar The Registrar The Registrar is the link between the client applications and the resource monitors. It communicates with the resource monitors on behalf of the client applications to retrieve information requested by the clients. The Registrar runs on the same system as the resource monitors. The Registrar does not need to keep any state information and does not need to be highly available. It does not need to be running while a resource is being monitored. The Registrar is needed only to start the monitors and to display resource configuration information to users. The Registrar is started via inetd(1m). To allow this to happen, the Registrar needs a well-known port number assignment. At installation, the Registrar s reserved port number will be added to the /etc/services file. The entry will be as follows: registrar registrar 1712/tcp 1712/udp # resource monitoring service # resource monitoring service Note that the Registrar does not actually use its UDP listening port. It is included only because the Internet Assigned Numbers Authority (IANA) prefers to assign ports in pairs. One Registrar process will be started each time a client application calls rm_client_connect(), so a Registrar will always be connected to one client. Depending on the requests sent by the client, the Registrar may be connected to 0, 1, 2, or more resource monitors concurrently. The information in the messages must contain enough information to allow the Registrar to route the requests and replies correctly. Figure 1-2 gives an example of what kinds of connections are possible. Chapter 1 13

14 Overview of the Event Monitoring Service The Registrar Figure 1-2 Connections Among Clients and Registrars System A Client Application System B Client Application System C Registrar Registrar Registrar Resource Monitor Resource Monitor Resource Monitor Resource Resource Resource Resource Each time the Registrar starts, it reads the resource dictionary, exchanges internal version information with the client application, and prepares to receive client requests. When a request arrives, the Registrar analyzes it to determine if it is one that it can reply to, or whether it needs to consult with a resource monitor. When the Registrar needs to consult with a resource monitor, it needs to determine if the resource monitor is currently running. If the appropriate resource monitor process is not found, the Registrar starts the process and waits until the resource monitor can communicate with the Registrar. The resource monitor will be ready to communicate when it has called rm_monitor_start() and rm_get_next_event(). 14 Chapter 1

15 Overview of the Event Monitoring Service The Registrar EMS will start a new instance of a resource monitor if no running processes exactly match the path name and arguments specified after the MONITOR keyword in the resource dictionary. (See Syntax on page 18.) EMS hashes the complete command line into a unique number. A named pipe is created in /etc/opt/resmon/pipe with this number as its name. When the Registrar needs to communicate with a monitor, it checks to see whether any process is reading from the corresponding named pipe. If so, it begins communicating with that process. Otherwise, it starts the monitor in a way that causes the monitor to open a named pipe. For this reason, monitors cannot be started from an HP-UX shell; they must be started by the Registrar. Chapter 1 15

16 Overview of the Event Monitoring Service The Resource Dictionary The Resource Dictionary The purpose of the resource dictionary is to give a preliminary picture of the resource structure on a given system. Its main function is to indicate to the Registrar which resource monitors should be contacted when information is needed about a certain resource. The resource dictionary defines resources on the local system. The resource dictionary is installed as a set of files in the /etc/opt/resmon/dictionary directory. A dictionary file will contain entries for one or more logical resources. A logical resource is defined as a unique string that maps to one physical resource. Many logical resources can map to the same physical resource, as indicated in Figure 1-2 on page 14. Resource Discovery Although the resource dictionary files are generally static, since they are created when a monitor is installed, a resource monitor can define resources dynamically. For example, a resource class called /applications/foo might be defined in the resource dictionary. If a client application sends a request to the Registrar for a list of resources beneath /applications/foo, the Registrar would forward the request to the resource monitor for that resource class. At that time, the monitor would check the system to determine what resources exist in that class, and it would reply with the list of resources. If another client requested the same information five minutes later, the monitor would check the system again. If the list of foo applications had changed, the monitor would return the updated list to the client. For resource classes that will contain a frequently changing set of resource instances, just enter the resource class in the resource dictionary, and write the resource monitor to return the list of resource instances in a Subclass Reply. For resource classes that will contain a static list of resource instances, whose names never change, create an entry in the resource dictionary for each resource instance. 16 Chapter 1

17 Overview of the Event Monitoring Service The Resource Dictionary File Naming The /etc/opt/resmon/dictionary/default file contains the structure and hierarchy of expected resource classes. EMS delivers the topmost resources in this file. Resource monitor providers are free to extend the default class hierarchy with their own file. Resource monitor providers should include their resource dictionary entries in one file, and use a name that is unlikely to be used by other resource monitor providers. All resource dictionary files will be installed into one directory, so it is important that the names of the files from two resource monitor providers do not collide. A suggestion is to use a name related to the type of resources that will be monitored, an underscore, and a two-digit version number. For example, a dictionary file for FDDI LAN monitors might be called /etc/opt/resmon/dictionary/fddi_01 The order of entries in each dictionary file is not important. It will be the responsibility of the Registrar to sort the tree of all resource dictionary entries. Resources may appear anywhere in the file; however, resource information may not be duplicated. In the case of duplicate records, the last one read will be the one used. Since the resource monitors can return additional information about the resource classes, the potential exists for a resource dictionary entry to be overwritten by a resource monitor. In this case, the last definition (from the resource monitor) will be used. Wildcarding The SAM interface to EMS allows users to select all resource instances in a resource class, if all instances are of the same type. For example, the resource class /vg/vg_name/lv/status contains a resource instance to monitor the status of every volume group. In the SAM interface to EMS, users may specify an asterisk (*) to create a monitor request for all volume groups at once. Wildcards may be specified in SAM any time all resource instances in a subclass are of the same type. If the type is RM_ENUMERATED_TYPE, all resource instances must have the same set of state names and values. When you write your monitor, if you want to enable users to specify wildcards in SAM, make sure all your resource instances are of the same type and are located in the same resource subclass. Chapter 1 17

18 Overview of the Event Monitoring Service The Resource Dictionary If you do not want users to specify wildcard characters in SAM for resource instances of the same type, make sure the resources are located in different resource subclasses. For example, if you have a resource instance that monitors CPU usage and another that monitors average run queues, they might be the same type, but you would not want users to be able to specify them together with a wildcard character. In this case, you would put them in different resource subclasses to prevent wildcarding. Syntax Resource class and instance information shares a common format in the dictionary file. Each description is a multiline record consisting of keywords and information. Keywords begin all lines except those lines following a continuation symbol (\). No more than one keyword is allowed on a line. All white space at the beginning of each line will be removed during parsing. The # character (except when it is found in a quoted string) indicates the beginning of a comment, which extends to the end of the line. Three keywords are necessary to describe a resource, although some may be omitted if not appropriate. RESOURCE_NAME: resource_name Required. The RESOURCE_NAME is the key identifier that allows a resource monitor to be integrated into EMS. resource_name is a full path name (starting with /). This can be either a class name or an instance, with nothing to differentiate between the two. DESCRIPTION: text Optional. The DESCRIPTION allows humans to understand what information a particular resource class or instance provides. It is displayed when a user selects View Description in the SAM interface to EMS. The description should be less than 80 characters, if possible, but it can be up to 2047 characters. It must contain no tabs. You cannot include newline characters (\n) in the description, so it is better to keep it to 80 characters or fewer so that it will format correctly in the SAM interface to EMS. 18 Chapter 1

19 Overview of the Event Monitoring Service The Resource Dictionary Make the description as descriptive as possible. Start the description with a one-line title. Include the word subclass in the title, if the resource is a subclass. If the resource is a resource instance, include the resource name and any variables it requires. Make sure the description explains what the resource is and, if appropriate, a list of values it can have. If the DESCRIPTION field is missing, the RmDescription field will be set to NULL in any resource monitor object that refers to this resource. MONITOR: monitor_name [args] Optional. If the MONITOR keyword is missing, the resource is assumed to be a resource class. Resource classes must contain at least one resource in their subtree that is linked to a monitor. Resource classes that do not contain at least one resource in their subtree will not be visible to client applications. When the resource instances in a subclass do not appear in the resource dictionary, because the monitor is written to return a list of them in a Subclass Reply, the MONITOR keyword appears in an entry for a resource class. monitor_name [args] is the invocation of the monitor, consisting of the full path of the monitor executable plus any additional command-line arguments. Shell expansion is not performed on the arguments. Note that two entries in the dictionary that specify the same MONITOR command will result in only one copy of the monitor being started by the Registrar. Chapter 1 19

20 Overview of the Event Monitoring Service The Resource Dictionary Resource Dictionary Examples Following is the resource dictionary entry for the Disk Monitor. It contains only one level, because the subcalsses and resource instances beneath the top level are dynamic, so the monitor has been written to supply the rest of the hierarchy when it receives Subclass Requests. RESOURCE_NAME: /vg DESCRIPTION: Volume Groups Subclass (/vg)\n\nthis subclass contains the resources related to LVM volume groups. MONITOR: /etc/opt/resmon/lbin/diskmond -l Following are some dictionary entries from the MIB Monitor: # The LAN status, derived from MIB II RESOURCE_NAME: /net/interfaces/lan/status MONITOR: /etc/opt/resmon/lbin/lanmond # Job queue from the HP-UX MIB RESOURCE_NAME: /system/jobqueue1min MONITOR: /etc/opt/resmon/lbin/mibmond # Job queue from the HP-UX MIB RESOURCE_NAME: /system/jobqueue5min MONITOR: /etc/opt/resmon/lbin/mibmond # Job queue from the HP-UX MIB RESOURCE_NAME: /system/jobqueue15min MONITOR: /etc/opt/resmon/lbin/mibmond # Number of users from the HP-UX MIB RESOURCE_NAME: /system/numusers MONITOR: /etc/opt/resmon/lbin/mibmond # Define a container for the filesystem resources RESOURCE_NAME: /system/filesystem DESCRIPTION: Filesystem Resources # The filesystem free space, derived from the HP-UX MIB RESOURCE_NAME: /system/filesystem/availmb MONITOR: /etc/opt/resmon/lbin/fsmond 20 Chapter 1

21 Overview of the Event Monitoring Service The Resource Dictionary Naming Hierarchy Here is the resource naming structure described in the /etc/opt/resmon/dictionary/default file. Resource monitor providers should check the contents of that file to find the latest naming structure, and to find the best resource class to use to name their resources. /applications /network_services /named /policy_mgr /telnet /db /user-defined /processes /net /interfaces /lan /fddi /token_ring /ethernet /switched /x25 /fibre_channel /atm /subnetwork /protocols /tcp /udp /ip /system /cpu /memory /io_interfaces /peripherals /net_attached_devices /mass_storage /printer /routers /gated Chapter 1 21

22 Overview of the Event Monitoring Service The Resource Dictionary Default Resource Dictionary Following is the resource dictionary file that describes the naming hierarchy shown in the previous section. The default resource dictionary file is /etc/opt/resmon/dictionary/default. RESOURCE_NAME: / DESCRIPTION: This is the top level of the Resource Dictionary RESOURCE_NAME: /applications DESCRIPTION: Application Resources RESOURCE_NAME: /applications/db DESCRIPTION: Database Application Resources RESOURCE_NAME: /applications/user-defined DESCRIPTION: User-Defined Applications Resources RESOURCE_NAME: /processes DESCRIPTION: Process Resources RESOURCE_NAME: /net DESCRIPTION: Network Resources RESOURCE_NAME: /net/interfaces DESCRIPTION: Network Interface Resources RESOURCE_NAME: /net/interfaces/lan DESCRIPTION: LAN Resources RESOURCE_NAME: /net/interfaces/lan/fddi DESCRIPTION: FDDI Resources RESOURCE_NAME: /net/interfaces/lan/token_ring DESCRIPTION: Token Ring Resources RESOURCE_NAME: /net/interfaces/lan/ethernet DESCRIPTION: Ethernet Resources RESOURCE_NAME: /net/interfaces/switched DESCRIPTION: Switched Resources RESOURCE_NAME: /net/interfaces/switched/x25 DESCRIPTION: X.25 Resources RESOURCE_NAME: /net/interfaces/switched/fibre_channel DESCRIPTION: Fibre Channel Resources RESOURCE_NAME: /net/interfaces/switched/atm DESCRIPTION: ATM Resources RESOURCE_NAME: /protocols DESCRIPTION: Protocol Resources RESOURCE_NAME: /protocols/tcp DESCRIPTION: TCP Resources RESOURCE_NAME: /protocols/udp 22 Chapter 1

23 Overview of the Event Monitoring Service The Resource Dictionary DESCRIPTION: UDP Resources RESOURCE_NAME: /protocols/ip DESCRIPTION: IP Resources RESOURCE_NAME: /net/subnet DESCRIPTION: Subnet Resources RESOURCE_NAME: /system DESCRIPTION: System Resources RESOURCE_NAME: /system/cpu DESCRIPTION: CPU Resources RESOURCE_NAME: /system/memory DESCRIPTION: Memory Resources RESOURCE_NAME: /system/io_interfaces DESCRIPTION: I/O Resources RESOURCE_NAME: /peripherals DESCRIPTION: Peripheral Resources RESOURCE_NAME: /peripherals/mass_storage DESCRIPTION: Mass Storage Resources RESOURCE_NAME: /peripherals/printers DESCRIPTION: Printer Resources RESOURCE_NAME: /routers DESCRIPTION: Router Resources Chapter 1 23

24 Overview of the Event Monitoring Service The Resource Dictionary 24 Chapter 1

25 2 The EMS Application Programming Interface (API) 25

26 The EMS Application Programming Interface (API) Functions Functions The EMS API provides the following functions: rm_create() rm_get() rm_set() rm_destroy() rm_copy() rm_log() rm_perror() rm_print() rm_strerror() rm_monitor_start() rm_get_next_event() rm_notify() rm_send_reply() rm_monitor_stop() rm_uncompress_object() Creates an object of the type specified by the user. Returns a data item within an object. Stores a data item in an object. Frees the memory associated with an object. Replicates an object. Prints a user-defined message to a log file. Prints an error message to a log file. Formats an EMS object to a log file. Formats an error message to a buffer. Establishes communication with the Registrar and EMS API. Blocks for an event from the API. Sends notification of a resource change. Sends a reply to the Registrar. Terminates communication with the Registrar and EMS API. Converts a TCP/IP or UDP/IP notification message into an EMS object. These functions are described in the following sections. Chapter 3, Writing a Resource Monitor, on page 59 and Chapter 5, Writing a Target Application, on page 109 give examples of how to use these functions. 26 Chapter 2

27 The EMS Application Programming Interface (API) Functions Table 2-1 EMS Data Types The EMS API and the objects within EMS use several data types. These types are described in Table 2-1 below: Data Types Type Size on HP-UX Description ubit16 16 bits A 16-bit unsigned integer. Used to store values between 0 and 65,535. ubit32 32 bits A 32-bit unsigned integer. Used to store values between 0 and 4,294,967,295. int, pid_t 32 bits A 32-bit signed integer. Used to store values between -2,147,483,648 and 2,147,483,647 time_t 32 bits Defined in /usr/include/sys/time.h to be a long. Used to store the number of seconds since 00:00 UTC on January 1, rm_error_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store error codes reported by a EMS API function. rm_object_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store the various object types defined by the EMS API. rm_field_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store values that identify a particular field inside an object. rm_option_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store constants that are defined for certain object fields. rm_return_type 32 bits Defined in /opt/resmon/include/resmon.h to be an enum. Used to store the reason that an EMS function returned. Chapter 2 27

28 The EMS Application Programming Interface (API) Functions Type Size on HP-UX Description rm_value_type * 32 bits A pointer to a union defined in /opt/resmon/include/resmon.h. This union can be used to store any type of Resource Value or Threshold Value used by EMS. char * 32 bits A character pointer (also referred to as a string). void * 32 bits A generic pointer used to store any address. rm_object_addr 32 bits Defined in /opt/resmon/include/resmon.h to be a void *. Contains the address of a memory block that defines an opaque object. fd_set 256 bytes A bit array capable of holding 256 bytes (2048 bits). Used with select(2) in rm_get_next_event(). Table 2-2 EMS Resource Types Resources in the Event Monitoring Service must be defined to have one of the following types: Resource Types Type RM_RESOURCE_CLASS_TYPE Description The resource is a resource class, which is used to hold other resource classes and/or resource instances. 28 Chapter 2

29 The EMS Application Programming Interface (API) Functions Type RM_ENUMERATED_TYPE RM_STRING_TYPE RM_SBIT32_TYPE RM_UBIT32_TYPE RM_FLOAT64_TYPE RM_SBIT64_TYPE RM_UBIT64_TYPE RM_ERROR_TYPE The resource is an Enumerated Type, which assumes values from a predefined set of states. The states are made up of state names and associated state values. For example, a particular resource may assume the values UP, DOWN, and INITIALIZING, and values can be assigned to each of these states: UP = 1, INITIALIZING = 2, and DOWN = 3 The Enumerated Type contains both the state name and the state value. The values for an enumerated type should be ordered from best to worst, in ascending order, as in the above example. That way, a monitor can test a value to determine whether it is, for example, >UP, or >=INITIALIZING. The state names for Enumerated Types should be all uppercase. The resource is a string of characters with a terminating NULL byte. The resource is a signed 32-bit integer. The resource is an unsigned 32-bit integer. The resource is a double-precision floating point value. Reserved for future use. Reserved for future use. Description This type indicates that an error occurred when trying to obtain a resource value. The associated value is undefined. One of the first tasks a resource monitor developer has is to decide what type of resource the resource monitor will be written to monitor. For example, it may make sense to have a LAN Utilization resource that is an RM_FLOAT64_TYPE, since it will assume values between 0.0 and 1.0. Chapter 2 29

30 The EMS Application Programming Interface (API) Functions Of course, each physical resource may be referred to by multiple logical resources. Each logical resource that is monitored will have just one type, however. For example, a resource monitor written to watch the physical CPU resource may define multiple logical resources related to the CPU: Number of active processors might be an RM_UBIT32_TYPE. CPU Utilization might be an RM_FLOAT64_TYPE. CPU State might be an RM_ENUMERATED_TYPE. Resource monitors determine the type of a resource, and client applications use the type specified by the resource monitor (except in the case of an RM_ENUMERATED_TYPE, in which case the client may choose to refer to either the state name or state value). 30 Chapter 2

31 The EMS Application Programming Interface (API) Logging and Tracing Table 2-3 Logging and Tracing See rm_print on page 50, rm_perror on page 49, rm_log on page 43, and rm_strerror on page 56 for the specifications for the user-callable logging functions. By default, only User Events, Panics, and Errors are logged. To see log messages with a lower severity, and to see internal trace information for debugging purposes, use the RM_LOG_LEVEL environment variable. The environment variable is read by the client application and is passed through the Registrar to any resource monitors that are queried on behalf of the client application. In this way, the client application, the Registrar, and the resource monitor will all have the same logging level. For verbose tracing, set RM_LOG_LEVEL=NOTES in the client application environment. Table 2-3 shows the environment variable values that are understood by EMS. RM_LOG_LEVEL Defined Values RM_LOG_LEVEL Value ERRORS (default) WARNINGS NOTES DEBUG Messages Logged User Events and messages with a severity level of RM_AUDIT_LVL, RM_PANIC_LVL or RM_ERROR_LVL. This is the default logging level. User Events and messages with a severity level of RM_AUDIT_LVL, RM_PANIC_LVL, RM_ERROR_LVL, and RM_WARN_LVL. User Events and messages with a severity level of RM_AUDIT_LVL, RM_PANIC_LVL, RM_ERROR_LVL, RM_WARN_LVL, and RM_NOTE_LVL. User Events and messages with a severity level of RM_AUDIT_LVL, RM_PANIC_LVL, RM_ERROR_LVL, RM_WARN_LVL, and RM_NOTE_LVL, plus internal product tracing. In addition, you can create a file called /etc/opt/resmon/debug to force client applications to always use verbose logging. Chapter 2 31

32 The EMS Application Programming Interface (API) Logging and Tracing Client applications log to /etc/opt/resmon/log/client.log, resource monitors log to /etc/opt/resmon/log/api.log, and the Registrar logs to /etc/opt/resmon/log/registrar.log. When a log file reaches 500K bytes, EMS creates a backup copy of it and starts a new file. Only one backup file is kept for each type of EMS process (client, resource monitor, or Registrar). The backup file name is the name of the file with a.old extension, for example, client.log.old. Normally, target applications cannot use the EMS logging functions, because they do not normally call rm_monitor_start(), which initializes the logging functions. Target applications should use the syslog(3c) facility. 32 Chapter 2

33 The EMS Application Programming Interface (API) rm_copy rm_copy Called by resource monitors to clone an object. Function Prototype rm_object_addr rm_copy ( const rm_object_addr obj, rm_error_type *error_code ); Parameters obj error_code Returned Value The object to be copied. Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. Upon successful completion, rm_copy() returns the new object. If an error occurs, the value returned is (rm_object_addr)null, and error_code is set to one of the values described in the file /opt/resmon/include/resmon.h. The new object is created by the EMS API and has its own copy of the data stored in obj. Therefore, calling rm_destroy() on obj will not affect the new object. Side Effects This function allocates memory using malloc(3c). The memory must be freed by the user using the rm_destroy() function when the object is no longer needed. If rm_copy() returns an error, no object is created, so it is not necessary to call rm_destroy(). Chapter 2 33

34 The EMS Application Programming Interface (API) rm_create rm_create Used by resource monitors to create objects. Function Prototype rm_object_addr rm_create ( rm_object_type type, rm_error_type *error_code ); Parameters type The type of object the user wishes to create. Valid values (defined in resmon.h) are as follows: RM_SUBCLASS_CHILD_OBJECT RM_RESOURCE_STATE_OBJECT RM_RESOURCE_UPDATE_OBJECT Possibly created as part of a reply to a Subclass Request. Created when asynchronously updating a resource value before calling rm_notify(). error_code Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. Returned Value Upon successful completion, rm_create() returns the object requested. If an error occurs, the value returned is (rm_object_addr)null, and error_code is set to one of the values described in the file /opt/resmon/include/resmon.h. Side Effects This function allocates memory using malloc(3c). The memory must be freed by the user using the rm_destroy() function when the object is no longer needed. If rm_create() returns an error, no object is created, so it is not necessary to call rm_destroy(). 34 Chapter 2

35 The EMS Application Programming Interface (API) rm_destroy rm_destroy Used by resource monitors and target applications to destroy objects that are no longer needed. Function Prototype void rm_destroy (rm_object_addr obj); Parameters obj Side Effects The object to be destroyed. This function deallocates memory using free(3c). Any references to fields inside the object are invalid once the object has been destroyed. Note that since rm_get() returns pointers to fields inside objects, those references are invalid once rm_destroy() has been called. Usage Notes If obj contains other objects, those objects will also be destroyed. For example, a Subclass Reply object may contain Resource State objects. If a Subclass Reply object is destroyed, the Resource State objects will automatically be destroyed as well. If obj is NULL, rm_destroy() has no effect. Chapter 2 35

36 The EMS Application Programming Interface (API) rm_get rm_get Used by resource monitors and target applications to retrieve data from an object. The caller passes the object and field identifier of interest, and rm_get() uses the supplied address to store the data. Function Prototype int rm_get ( const rm_object_addr obj, rm_field_type field, void *addr, rm_error_type *error_code ); Parameters obj field addr The object that contains the data item to be retrieved. A value that identifies which portion of the object is of interest. The valid field specifiers associated with each object are described in Chapter 3, Writing a Resource Monitor, on page 59 and Chapter 5, Writing a Target Application, on page 109. An address where the result will be stored. Note that addr is always specified as the address of a variable. The type of the variable must match the TYPE specified in Chapter 3 or Chapter 5. For example, to retrieve the message tag from a Monitor Request object, a resource monitor should set addr to the address of an unsigned 32-bit integer. ubit32 msg_tag; rm_error_type error_code; rm_get(obj, RmMsgTag, &msg_tag, &error_code); To retrieve the resource name from a Subclass Request object, the monitor should set addr to the address of a character pointer, not the address of a character array. 36 Chapter 2

37 The EMS Application Programming Interface (API) rm_get The following example correctly sets a character pointer to point to the resource name: char *resource_name; rm_error_type error_code; rm_get(obj, RmResourceName, &resource_name, &error_code); /* CORRECT */ Following is an incorrect example of getting a resource name: error_code char resource_name[256]; rm_error_type error_code; rm_get(obj, RmResourceName, resource_name, &error_code); /* WRONG */ Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. Returned Value Upon successful completion, rm_get() returns 0. If an error occurs, the value returned is -1, and error_code is set to one of the values described in the file /opt/resmon/include/resmon.h. Usage Notes The only supported method of modifying object data is through the rm_set() function. Any other method if modifying data inside an object is unsupported. Similarly, rm_get() is the only supported method of obtaining data from an object. If the field you want to obtain data from is an integer, rm_get copies the value to the location pointed to by addr, and you can destroy the object obj without affecting the contents of addr. If the field is an enumerated type (like an object type) or a character string, the address of the field inside the EMS object is returned in the addr field. The data is not copied. Therefore, if you destroy the object pointed to by obj, you also destroy the value pointed to by addr. Likewise, if addr points to an enumerated or character type, and you free(3c) the memory pointed to by addr, the corresponding field of the object obj is actually destroyed. For enumerated and character types, you should copy the data pointed to by addr after calling rm_get() if you need to reference it after the containing object has been destroyed. Chapter 2 37

38 The EMS Application Programming Interface (API) rm_get_next_event rm_get_next_event This function is used by monitors to determine when a message is ready to be received from the EMS API. Normally, this function blocks until a message has been received from the EMS API. If the resource monitor is written in such a way that it cannot block indefinitely, parameters are provided that are similar to those found in select(2). These parameters can be used to specify file descriptors that should be watched for activity. They can also be used to specify a maximum blocking time. Use of these parameters is optional, and should be necessary only for resource monitors that need to listen to multiple communication channels in order to monitor the resources they support. The following events will cause rm_get_next_event() to return: A message arrives from the Registrar. This message will be a Subclass Request or Monitor Request. A timer pops, indicating that the EMS API needs an update from the resource monitor about a resource value. A timer pops, indicating that there has been no activity associated with this resource monitor for a lengthy period (60 minutes), and that the resource monitor may terminate. A message has arrived from some source other than the EMS API. This event applies only to resource monitors that use the select(2) parameters. A timer pops, indicating that the time interval specified by the resource monitor has expired without any messages arriving. This event applies only to resource monitors that use the select(2) parameters. A monitor request is unregistered. The resource monitor is informed when a monitor request is unregistered, although in general no action is necessary. Function Prototype int rm_get_next_event ( rm_select_type *select_data, rm_return_type *return_type, rm_object_addr *obj, rm_error_type *error_code ); 38 Chapter 2

39 The EMS Application Programming Interface (API) rm_get_next_event Table 2-4 Parameters select_data rm_select_type Data fields Contains both call and return values. The resource monitor optionally supplies values that determine whether any file descriptors other than the EMS API communications socket should be monitored for data traffic using select(2). Upon return, the file descriptors that have data are marked. If select_data is NULL, the EMS API blocks indefinitely until a Resource Monitor message arrives. The following fields of the rm_select_type data structure are (optionally) used: Field Name Type Description readfds fd_set On input specifies the file descriptors to be checked for being ready to read, and on output indicates which file descriptors are ready to read. The EMS API will automatically add the file descriptors of all sockets it uses to communicate with the Registrar to this list and remove them before returning the readfds structure. Note: Messages from the EMS API have a lower priority than other messages. They will be processed only when the file descriptors in readfds, writefds, and exceptfds do not contain pending messages. Resource Monitors that do not need to use this field should set it to all zeros. See select(2) for more information. Chapter 2 39

40 The EMS Application Programming Interface (API) rm_get_next_event Field Name Type Description writefds fd_set On input specifies the file descriptors to be checked for being ready to write, and on output indicates which file descriptors are ready to write. Note: Messages from the EMS API have a lower priority than other messages. They will be processed only when the file descriptors in readfds, writefds, and exceptfds do not contain pending messages. Resource Monitors that do not need to use this field should set it to all zeros. See select(2) for more information. exceptfds fd_set On input specifies the file descriptors to be checked for having error conditions pending, and on output indicates which file descriptors have error conditions pending. The EMS API will automatically add the file descriptors of all sockets it uses to communicate with the Registrar to this list and remove them before returning the exceptfds structure. Note: Messages from the EMS API have a lower priority than other messages. They will be processed only when the file descriptors in readfds, writefds, and exceptfds do not contain pending messages. Resource Monitors that do not need to use this field should set it to all zeros. See select(2) for more information. num_fds int Upon return, this value specifies how many file descriptors are marked in the file descriptor fields. See select(2) for more information. 40 Chapter 2

41 The EMS Application Programming Interface (API) rm_get_next_event Field Name Type Description timeout struct timeval * If the timeout argument is not a null pointer, it points to an object of type struct timeval that specifies a maximum interval to wait for the selection to complete. Resource monitors that can block indefinitely should set this field to NULL. See select(2) for more information. return_type Identifies the type of event that occurred. Valid values are as follows: RM_SUBCLASS_REQUEST_EVENT RM_MONITOR_REQUEST_EVENT RM_RESOURCE_UPDATE_EVENT RM_TERMINATE_EVENT RM_SELECT_EVENT A Subclass Request message has been received from the EMS API. The resource monitor is expected to send a Subclass Reply. See Processing a Subclass Request Event on page 67 for more information. A Monitor Request message has been received from the EMS API. The resource monitor is expected to send a Monitor Reply. See Processing a Monitor Request Event on page 78 for more information. A timer popped indicating that an update is needed on a particular resource value. The resource monitor is expected to retrieve the current value of the resource. See Processing a Resource Update Event on page 84 for more information. A timer popped indicating that no activity associated with this resource has occurred in the last 60 minutes. The resource monitor may terminate after receiving this message. See Processing a Terminate Event on page 93 for more information. A call to select(2) returned with one of the user-specified file descriptors selected. The numfds, readfds, writefds, and exceptfds fields should be examined for useful data. See select(2) for more information. Chapter 2 41

42 The EMS Application Programming Interface (API) rm_get_next_event RM_TIMEOUT_EVENT RM_UNREGISTER_EVENT No events occurred in the time interval allotted for the rm_get_next_event() function. This event occurs only when the resource monitor sets a timeout in the select(2) parameters. See select(2) for more information. A monitor request has been unregistered. See Processing an Unregister Event on page 96 for more information. Parameters obj error_code Returned Value If the return_type is RM_SUBCLASS_REQUEST_EVENT, RM_MONITOR_REQUEST_EVENT, RM_RESOURCE_UPDATE_EVENT, or RM_UNREGISTER_EVENT, an object of the appropriate type is created by rm_get_next_event(). The resource monitor must free the memory associated with that object by calling rm_destroy() when the object is no longer needed. Provides additional information about failure conditions of the function. Valid values are listed in the file /opt/resmon/include/resmon.h. Upon successful completion, rm_get_next_event() returns 0 and creates an object to indicate what type of event occurred. If an error occurs, the value returned is -1, and error_code is set to one of the values described in the file /opt/resmon/include/resmon.h. If rm_get_next_event() returns an error, no object is created, so it is not necessary to call rm_destroy(). 42 Chapter 2

43 The EMS Application Programming Interface (API) rm_log rm_log Used by resource monitors to print user-defined messages to an EMS log file. Resource monitors log messages to /etc/opt/resmon/log/api.log. Normally, target applications cannot use the EMS logging functions, because they do not normally call rm_monitor_start(), which initializes the logging functions. Target applications should use the syslog(3c) facility. Function Prototype void rm_log (sbit32 log_level, char *fmt, /* [arg,] */... ); Parameters log_level Identifies the severity level of the message. Valid values are as follows: RM_AUDIT_LVL RM_PANIC_LVL RM_ERROR_LVL RM_WARN_LVL RM_NOTE_LVL fmt [arg,...] The message will always be logged, regardless of the value of the RM_LOG_LEVEL environment variable. The program has encountered a critical internal error. Correct operation in the future is unlikely. The program has encountered an unexpected error. Future operation may not be reliable. The program has encountered a recoverable error condition. Unless accompanied by a more serious error message, operation should continue successfully. The message is intended for informational purposes only. A format, similar to printf(3s). Arguments, similar to printf(3s). Chapter 2 43

44 The EMS Application Programming Interface (API) rm_log Usage Notes By default, only messages at levels RM_AUDIT_LVL, RM_PANIC_LVL, and RM_ERROR_LVL are logged. Messages at RM_WARN_LVL are not logged by default. Therefore, if you want to ensure that a message is logged, set the log level to RM_AUDIT_LVL, RM_PANIC_LVL, or RM_ERROR_LVL. See Logging and Tracing on page 31 for more details. 44 Chapter 2