samlog(1M)


samlog -- add or modify an entry in the SAM event log

Synopsis

samlog -t objtype -n objname [-s state] [-p PLANNED | UNPLANNED ] [-w time] [-u user_field | NULL] [msg | NULL]

samlog -i evid [-t objtype] [-n objname] [-s state] [-p PLANNED | UNPLANNED] [-w time] [-u user_field | NULL] [msg | NULL]

samlog -h

Description

The samlog command adds and modifies SAM event log entries. You must use this command to add entries to the SAM event log because samlog allocates the event ids. All log entries must be added with this command, which allocates the event id numbers. The first form of the command adds an entry in the log. The second form modifies an entry. The samd SAM daemon also uses this command to record up and down events in the event log. The informationin the added or modified entries is presented in the SAM reports.

Adding an Entry

You can add new entries to the log file so they appear in the SAM reports with their up-time percentages. For example, you can add entries to record the state change of an object. New objects can be creating by using an object type or object name previously unused. However, it is recommended that you use an existing object type and a unique name. For a description of what each argument or field means, see the Options section below. If you do not specify an optional field, SAM uses a default value in the entry. See the Options section below for the defaults.

When you add an entry, keep in mind the following limitations:

Modifying an Entry

You can modify the fields of an entry in the log file. For example, you can mark a down event as being planned, or replace the message field with more informative text. If you mark a down event as being planned, you can use the samrep -k PLANNED command to generate a report that treats planned down time as up time for the computation of the up-time percentage.

To specify a log entry to modify, you must use an event id from the Failures report or the Events report. Enter the event id carefully because errors in this field are difficult to detect. The samlog(1M) command changes the fields specified on the command line and leaves the other fields in the entry unchanged. Each specified field must be a single word, except for the msg field. The keyword NULL clears the msg and user_field fields. You can update an entry multiple times and the effects are accumulative.

If you modify fields other than msg or utoken, be sure your information is accurate and consistent. Errors in the other fields can cause undetected serious errors in the reports.

Indicating an Object is Gone

SAM does not recognize that an object has been physically removed from the cluster. However, if the object is a node, it records that the object is down. The user-added GONE state indicates the object is removed from the cluster. You should never apply this state to the CLUS or TIME type objects.

You can indicate a node or application is removed in four ways:

It is recommended that two log entries be used. Two log entries more accurately reflect the object first being down then being removed.

Options

-i evid
Specifies an event id of an existing log entry to modify. This field is not allowed when adding a new log entry because samlog generates a new event id for an added log entry. Existing event ids can be obtained from the Failures and Events reports.

-t objtype
Specifies the type of the object. This field is required when you add a new log entry. The existing object types are:
CLUS
The cluster itself.
NODE
A single node of the cluster.
TIME
The system time for the cluster.
APPL
An application

If you add a log entry that uses an object type other than the preceding objects types, the object type you specify is limited to a length of 4 characters.

-n objname
Specifies the name of the object. This field is required when you add a log entry. Within a given object type, the name should be unique. Object names can be restricted based on the their object type:
CLUS
The object name must be SELF.
NODE
The object name must be the node number (1,2,3,...).
TIME
The object name must be CHANGE.
APPL
The object name may be chosen by the user.

If you add a new log entry, the object name you specify must be no longer than 7 characters.

-s state
Specifies the new state of the object as UP, DOWN, or GONE. The UP state indicates that the object is fully operational, otherwise it is considered DOWN. GONE is an alternate state for DOWN in which subsequent time is not counted as either up or down time in the availability calculations. When you use samlog to modify its state as GONE, SAM stops accumulating down time for it. If the node is added back to the cluster, an UP event occurs in the log after the GONE event, and time accounting is restarted for the object.

If you add an entry to the log and leave this field unspecified, the DOWN state is used as the default value. If you modify an entry and leave this field unspecified, the existing value for the field is kept.

-p PLANNED | UNPLANNED
Specifies whether the event was PLANNED or UNPLANNED. You may want record planned and unplanned down time to distinguish regularly scheduled maintenance from unexpected failures, for example.
If you add an entry to the log and do not specify this field, the default value of UNPLANNED is is used. If you modify an entry and do not specify this field, the existing value for the field is kept.

-w time
Specifies the time the event occured. You can specify the time in Unix Epoch seconds, and YYYY.MM.DD_HH:MM:SS. If you add an entry to the log and do not specify this field, the current time is used by default. If you modify an entry and leave this field unspecified, the existing value for the field is kept.

-u user_field | NULL
Specifies a user-supplied keyword, number, or other single word. SAM does not use this field when generating reports. If you add an entry to the log and do not specify this field NULL (the empty string) is used by default. If you modify and an entry and do not specify this field, the existing value for the field is kept.

msg | NULL
Specifies a short descriptive message to annotate the event. Unlike the other fields, more than one word can be used for this field. The message can be quoted or unquoted. If you add an entry to the log and do not specify this field, NULL (the empty string) is used by default. If you modify an entry and leave this field unspecified, the existing value for the field is kept.

-h
Displays the help information.

Files

/var/avail/sam/eventlog
SAM event log file
/var/avail/sam/.state
SAM private state file directory for lock and state files

Examples

The following command adds an unplanned down event for a user-monitored application named WEB:

samlog -t APPL -n WEB http server crashed

The following command changes the type of down time for event ID 1234 from unplanned to planned and adds a description:

samlog -i 1234 -p PLANNED upgraded the motherboard

References

intro_sam(1M), samd(1M), samdctl(1M), samrep(1M)
04 Feb 2000
© 2000 The Santa Cruz Operation, Inc. All rights reserved.
UnixWare 7 Release 7.1 - 19 March 2000
© 2000 Compaq Computer Corporation.