EEM System Information Tcl Command Extensions

Last Updated: November 17, 2011

The following conventions are used for the syntax documented on the Tcl command extension pages:

  • An optional argument is shown within square brackets, for example:

[type ?]

  • A question mark ? represents a variable to be entered.
  • Choices between arguments are represented by pipes, for example:

priority low|normal|high


Note
All EEM system information commands--sys_reqinfo_xxx--have the Set _cerrno section set to yes.

Note
For all EEM Tcl command extensions, if there is an error, the returned Tcl result string contains the error information.

Note
Arguments for which no numeric range is specified take an integer from -2147483648 to 2147483647, inclusive.

sys_reqinfo_cli_freq

Queries the frequency information of all command-line interface (CLI) events.

Syntax

sys_reqinfo_cli_freq

Arguments

None

Result String

rec_list {{CLI frequency string 0},{CLI frequency str 1}, ...}

Where each CLI frequency string is:

time_sec %ld time_msec %ld match_count %u raise_count %u occurs %u period_sec %ld period_msec %ld pattern {%s}

rec_list

Marks the start of the CLI event frequency list.

time_sec time_msec

Last time when this CLI event was raised.

match count

Number of times that a CLI command matches the pattern specified by this CLI event specification.

raise_count

Number of times that this CLI event was raised. The following fields are information about the CLI event specification:

  • sync--A "yes" means that event publish should be performed sychronously. The event detector will be notified when the Event Manager Server has completed publishing the event. The Event Manager Server will return a code that indicates whether or not the CLI command should be executed.
  • skip--A "yes" means that the CLI command should not be executed if the sync flag is not set.

occurs

Number of occurrences before an event is raised; if this argument is not specified, an event is raised on the first occurrence.

period_sec period_msec

Number of occurrences must occur within this number of POSIX timer units in order to raise event; if this argument is not specified, it does not apply.

pattern

Regular expression used to perform CLI command pattern matching.

Set _cerrno

Yes

sys_reqinfo_cli_history

Queries the history of command-line interface (CLI) commands.

Syntax

sys_reqinfo_cli_history

Arguments

None

Result String

rec_list {{CLI history string 0}, {CLI history str 1},...}

Where each CLI history string is:

time_sec %ld time_msec %ld cmd {%s}

rec_list

Marks the start of the CLI command history list.

time_sec time_msec

Time when the CLI command was run.

cmd

Text of the CLI command.

Set _cerrno

Yes

sys_reqinfo_cpu_all

Queries the CPU utilization of the top processes (both POSIX processes and IOS processes) during a specified time period and in a specified order. This Tcl command extension is supported only in Software Modularity images.

Syntax

sys_reqinfo_cpu_all order cpu_used [sec ?] [msec ?] [num ?]

Arguments

order

(Mandatory) Order used for sorting the CPU utilization of processes.

cpu_used

(Mandatory) Specifies that the average CPU utilization, for the specified time window, will be sorted in descending order.

sec msec

(Optional) The time period, in seconds and milliseconds, during which the average CPU utilization is calculated. Must be integers in the range from 0 to 4294967295. If not specified, or if both sec and msec are specified as 0, the most recent CPU sample is used.

num

(Optional) Number of entries from the top of the sorted list of processes to be displayed. Must be an integer in the range from 1 to 4294967295. Default value is 5.

Result String

rec_list {{process CPU info string 0},{process CPU info string 1}, ...}

Where each process CPU info string is:

pid %u name {%s} cpu_used %u

rec_list

Marks the start of the process CPU information list.

pid

Process ID.

name

Process name.

cpu_used

Specifies that if sec and msec are specified with a number greater than zero, the average percentage is calculated from the process CPU utilization during the specified time period. If sec and msec are both zero or not specified, the average percentage is calculated from the process CPU utilization in the latest sample.

Set _cerrno

Yes

sys_reqinfo_crash_history

Queries the crash information of all processes that have ever crashed. This Tcl command extension is supported only in Software Modularity images.

Syntax

sys_reqinfo_crash_history

Arguments

None

Result String

rec_list {{crash info string 0},{crash info string 1}, ...}
Where each crash info string is:
job_id %u name {%s} respawn_count %u fail_count %u dump_count %u
inst_id %d exit_status 0x%x exit_type %d proc_state {%s} component_id 0x%x
crash_time_sec %ld crash_time_msec %ld

job_id

System manager assigned job ID for the process. An integer between 1 and 4294967295, inclusive.

name

Process name.

respawn_count

Total number of restarts for the process.

fail_count

Number of restart attempts of the process. This count is reset to zero when the process is successfully restarted.

dump_count

Number of core dumps performed.

inst_id

Process instance ID.

exit_status

Last exit status of the process.

exit_type

Last exit type.

proc_state

Sysmgr process states. One of the following: error, forced_stop, hold, init, ready_to_run, run, run_rnode, stop, waitEOltimer, wait_rnode, wait_spawntimer, wait_tpl.

component_id

Version manager assigned component ID for the component to which the process belongs.

crash_time_sec crash_time_msec

Seconds and milliseconds since January 1, 1970, which represent the last time the process crashed.

Set _cerrno

Yes

sys_reqinfo_mem_all

Queries the memory usage of the top processes (both POSIX and IOS) during a specified time period and in a specified order. This Tcl command extension is supported only in Software Modularity images.

Syntax

sys_reqinfo_mem_all order allocates|increase|used [sec ?] [msec ?] [num ?]

Arguments

order

(Mandatory) Order used for sorting the memory usage of processes.

allocates

(Mandatory) Specifies that the memory usage is sorted by the number of process allocations during the specified time window, and in descending order.

increase

(Mandatory) Specifies that the memory usage is sorted by the percentage of process memory increase during the specified time window, and in descending order.

used

(Mandatory) Specifies that the memory usage is sorted by the current memory used by the process.

sec msec

(Optional) The time period, in seconds and milliseconds, during which the process memory usage is calculated. Must be integers in the range from 0 to 4294967295. If both sec and msec are specified and are nonzero, the number of allocations is the difference between the number of allocations in the oldest and latest samples collected in the time period. The percentage is calculated as the the percentage difference between the memory used in the oldest and latest samples collected in the time period. If not specified, or if both sec and msec are specified as 0, the first sample ever collected is used as the oldest sample; that is, the time period is set to be the time from startup until the current moment.

num

(Optional) Number of entries from the top of the sorted list of processes to be displayed. Must be an integer in the range from 1 to 4294967295. Default value is 5.

Result String

rec_list {{process mem info string 0},{process mem info string 1}, ...}

Where each process mem info string is:

pid %u name {%s} delta_allocs %d initial_alloc %u current_alloc %u percent_increase %d

rec_list

Marks the start of the process memory usage information list.

pid

Process ID.

name

Process name.

delta_allocs

Specifies the difference between the number of allocations in the oldest and latest samples collected in the time period.

initial_alloc

Specifies the amount of memory, in kilobytes, used by the process at the start of the time period.

current_alloc

Specifies the amount of memory, in kilobytes, currently used by the process.

percent_increase

Specifies the percentage difference between the memory used in the oldest and latest samples collected in the time period. The percentage difference can be expressed as current_alloc minus initial_alloc times 100 and divided by initial_alloc.

Set _cerrno

Yes

sys_reqinfo_proc

Queries the information about a single POSIX process. This Tcl command extension is supported only in Software Modularity images.

Syntax

sys_reqinfo_proc job_id ?

Arguments

job_id

(Mandatory) System manager assigned job ID for the process. Must be an integer between 1 and 4294967295, inclusive.

Result String

job_id %u component_id 0x%x name {%s} helper_name {%s} helper_path {%s} path {%s}
node_name {%s} is_respawn %u is_mandatory %u is_hold %u dump_option %d 
max_dump_count %u respawn_count %u fail_count %u dump_count %u 
last_respawn_sec %ld last_respawn_msec %ld inst_id %u proc_state %s
level %d exit_status 0x%x exit_type %d

job_id

System manager assigned job ID for the process. An integer between 1 and 4294967295, inclusive.

component_id

Version manager assigned component ID for the component to which the process belongs.

name

Process name.

helper_name

Helper process name.

helper_path

Executable path of the helper process.

path

Executable path of the process.

node_name

System manager assigned node name for the node to which the process belongs.

is_respawn

Flag that specifies that the process can be respawned.

is_mandatory

Flag that specifies that the process must be alive.

is_hold

Flag that specifies that the process is spawned until called by the API.

dump_option

Core dumping options.

max_dump_count

Maximum number of core dumping permitted.

respawn_count

Total number of restarts for the process.

fail_count

Number of restart attempts of the process. This count is reset to zero when the process is successfully restarted.

dump_count

Number of core dumps performed.

last_respawn_sec last_respawn_msec

Seconds and milliseconds in POSIX timer units since January 1, 1970, which represent the last time the process was started.

inst_id

Process instance ID.

proc_state

Sysmgr process states. One of the following: error, forced_stop, hold, init, ready_to_run, run, run_rnode, stop, waitEOltimer, wait_rnode, wait_spawntimer, wait_tpl.

level

Process run level.

exit_status

Last exit status of the process.

exit_type

Last exit type.

Set _cerrno

Yes

sys_reqinfo_proc_all

Queries the information of all POSIX processes. This Tcl command extension is supported only in Software Modularity images.

Syntax

sys_reqinfo_proc_all

Arguments

None

Result String

rec_list {{process info string 0}, {process info string 1},...}

Where each process info string is the same as the result string of the sysreq_info_proc Tcl command extension.

Set _cerrno

Yes

sys_reqinfo_routername

Queries the router name.

Syntax

sys_reqinfo_routername

Arguments

None

Result String

routername %s

Where routername is the name of the router.

Set _cerrno

Yes

sys_reqinfo_snmp

Queries the value of the entity specified by a Simple Network Management Protocol (SNMP) object ID.

Syntax

sys_reqinfo_snmp oid ? get_type exact|next

Arguments

oid

(Mandatory) SNMP OID in dot notation (for example, 1.3.6.1.2.1.2.1.0).

get_type

(Mandatory) Type of SNMP get operation that needs to be applied to the specified oid. If the get_type is "exact," the value of the specified oid is retrieved; if the get_type is "next," the value of the lexicographical successor to the specified oid is retrieved.

Result String 

oid {%s} value {%s}

oid

SNMP OID.

value

Value string of the associated SNMP data element.

Set _cerrno

Yes

(_cerr_sub_err =  2)    FH_ESYSERR  (generic/unknown error from OS/system)

This error means that the operating system reported an error. The POSIX errno value that is reported with the error should be used to determine the cause of the operating system error.

(_cerr_sub_err = 22)    FH_ENULLPTR  (event detector internal error - ptr is null)

This error means that an internal EEM event detector pointer was null when it should have contained a value.

(_cerr_sub_err = 37)    FH_ENOSNMPDATA  (can't retrieve data from SNMP)

This error means that there was no data for the SNMP object type.

(_cerr_sub_err = 51)    FH_ESTATSTYP  (invalid statistics data type)

This error means that the SNMP statistics data type was invalid. 

(_cerr_sub_err = 54)    FH_EFDUNAVAIL  (connection to event detector unavailable)

This error means that the event detector was unavailable.

sys_reqinfo_syslog_freq

Queries the frequency information of all syslog events.

Syntax

sys_reqinfo_syslog_freq

Arguments

None

Result String

rec_list {{event frequency string 0}, {log freq str 1}, ...}

Where each event frequency string is:

time_sec %ld time_msec %ld match_count %u raise_count %u occurs %u 
period_sec %ld period_msec %ld pattern {%s}

time_sec time_msec

Seconds and milliseconds in POSIX timer units since January 1, 1970, which represent the time the last event was raised.

match_count

Number of times that a syslog message matches the pattern specified by this syslog event specification since event registration.

raise_count

Number of times that this syslog event was raised.

occurs

Number of occurrences needed in order to raise the event; if not specified, the event is raised on the first occurrence.

period_sec period_msec

Number of occurrences must occur within this number of POSIX timer units in order to raise the event; if not specified, the period check does not apply.

pattern

Regular expression used to perform syslog message pattern matching.

Set _cerrno

Yes

(_cerr_sub_err =  2)    FH_ESYSERR  (generic/unknown error from OS/system)

This error means that the operating system reported an error. The POSIX errno value that is reported with the error should be used to determine the cause of the operating system error.

(_cerr_sub_err =  9)    FH_EMEMORY  (insufficient memory for request)

This error means that an internal EEM request for memory failed.

(_cerr_sub_err = 22)    FH_ENULLPTR  (event detector internal error - ptr is null)

This error means that an internal EEM event detector pointer was null when it should have contained a value.

(_cerr_sub_err = 45)    FH_ESEQNUM  (sequence or workset number out of sync)

This error means that the event detector sequence or workset number was invalid.

(_cerr_sub_err = 46)    FH_EREGEMPTY  (registration list is empty)

This error means that the event detector registration list was empty.

(_cerr_sub_err = 54)    FH_EFDUNAVAIL  (connection to event detector unavailable)

This error means that the event detector was unavailable.

sys_reqinfo_syslog_history

Queries the history of the specified syslog message.

Syntax

sys_reqinfo_syslog_history

Arguments

None

Result String

rec_list {{log hist string 0}, {log hist str 1}, ...}

Where each log hist string is:

time_sec %ld time_msec %ld msg {%s}

time_sec time_msec

Seconds and milliseconds since January 1, 1970, which represent the time the message was logged.

msg

Syslog message.

Set _cerrno

Yes

(_cerr_sub_err =  2)    FH_ESYSERR  (generic/unknown error from OS/system)

This error means that the operating system reported an error. The POSIX errno value that is reported with the error should be used to determine the cause of the operating system error.

(_cerr_sub_err = 22)    FH_ENULLPTR  (event detector internal error - ptr is null)

This error means that an internal EEM event detector pointer was null when it should have contained a value.

(_cerr_sub_err = 44)    FH_EHISTEMPTY  (history list is empty)

This error means that the history list was empty.

(_cerr_sub_err = 45)    FH_ESEQNUM  (sequence or workset number out of sync)

This error means that the event detector sequence or workset number was invalid.

(_cerr_sub_err = 54)    FH_EFDUNAVAIL  (connection to event detector unavailable)

This error means that the event detector was unavailable.

© 2011 Cisco Systems, Inc. All rights reserved.