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:
- None of the data fields may contain the .:. (dot, colon, dot) log file field separator.
- The
keyword NULL can not be entered as data. SAM replaces NULL entered as data with the empty string.
- The message text cannot contain any of the command line options (dash followed by option letter), unless
the standard -- (dash, dash) UNIX
option-termination string occurs before the message text.
- Each field must be one word except the msg field.
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:
- If a down event already exists for the object, you can add a log entry for the object. This entry can indicate a state of GONE and a time field that indicates the time that the object was removed, rather than when the object went down
- If a down event already exists for the object, you can modify the log entry for the down event so the state field is changed from DOWN to GONE
- If no down event exists for the object, you can add one log entry for the down event, and another for the gone event
- If no down event exists for the object, you can add one new log entry for the gone event
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.