cltelemetryattribute(1CL)

Name | Synopsis | Description | SUBCOMMANDS | Options | Operands | Exit Status | Examples | Attributes | See Also | Notes

Name

cltelemetryattribute, clta– configure system resource monitoring

Synopsis

/usr/cluster/bin/cltelemetryattribute  -V

/usr/cluster/bin/cltelemetryattribute [subcommand] 
 -?

/usr/cluster/bin/cltelemetryattribute subcommand 
 [options] -v [telemetry-attribute …]

/usr/cluster/bin/cltelemetryattribute disable  [-i 
 {- |  clconfigfile}] [-t object-type] {+ |  telemetry-attribute ...}

/usr/cluster/bin/cltelemetryattribute enable  [-i 
 {- |  clconfigfile}] [-t object-type] {+ |  telemetry-attribute ...}

/usr/cluster/bin/cltelemetryattribute export  [-o 
 {- |  clconfigfile}] [-t object-type[,…]]
 [+ |  telemetry-attribute ...]

/usr/cluster/bin/cltelemetryattribute list  [-t object-type[,…]]
 [+ |  telemetry-attribute ...]

/usr/cluster/bin/cltelemetryattribute print  [-b object-instance[,…]]
 [-a] [-d period] [-u] [-n node[,…]] [-t object-type[,…]]
 [+ |  telemetry-attribute ...]

/usr/cluster/bin/cltelemetryattribute set-threshold 
 -b object-instance [-n node] {-p name=value}
 [-p name=value ] […] -t object-type telemetry-attribute

/usr/cluster/bin/cltelemetryattribute show  [-b object-instance[,…]]
 [-n node[,…]] [-t object-type[,…]] [+
 |  telemetry-attribute ...]

/usr/cluster/bin/cltelemetryattribute status  -b object-instance
 [-n node] {-p name} -t object-type [+ |  telemetry-attribute ...]

Description

This command configures the monitoring of system resources.

You can monitor the use of system resources on different types of objects, including the following:

• Disks

• File systems

• IP addresses

• Network interfaces

• Nodes

• Solaris zones

• Resource groups

The aspects of system resources that you can monitor are called telemetry attributes.

This command does the following:

• Enables or disables telemetry attributes

• Sets or modifies thresholds for telemetry attributes

• Displays a list of the attributes that are being monitored, the thresholds that are applied, and the data that is collected about objects

You select the aspects of system resource usage that you want to monitor by identifying the corresponding telemetry attribute. To monitor system resource usage on an object, you enable the corresponding telemetry attributes on that type of object. The Sun Cluster software collects usage data for these attributes on all objects of that type in the cluster.

For a system resource, a particular value might be critical for the performance of your cluster. You can set a threshold for a telemetry attribute so that you are notified if the critical value is crossed. See the set-threshold subcommand and the description of the -p option for information about thresholds.

You can omit subcommand only if options is the -? option or the -V option.

Each option has a long and a short form. Both forms of each option are given with the description of the option in OPTIONS.

The clta command is the short form of the cltelemetryattribute command.

Before you refine the configuration of system resource monitoring, you must initialize monitoring. See the sctelemetry(1M) man page.

You can use this command only in the global zone.

SUBCOMMANDS

The following subcommands are supported:

disable

Disables the specified telemetry attribute for the specified object type.

You can use this subcommand only in the global zone.

The Sun Cluster software collects usage data for system resources that are set to an enabled state. If you set a system resource for an object type to the disabled state, Sun Cluster software does not collect data for any instance that corresponds to that object instance.

The cltelemetryattribute command also disables the data collection on these attributes when both of the following conditions are met:

• You specify a configuration file with the -i option.

• The telemetry attributes are set to disabled in the input file.

You create the configuration file by using the export subcommand.

When you set a telemetry attribute to disabled, the settings of its configured thresholds remain unaltered.

Users other than superuser require solaris.cluster.modify role-based access control (RBAC) authorization to use this subcommand. See the rbac(5) man page.

enable

Enables data collection of the specified telemetry attribute of the specified object type.

You can use this subcommand only in the global zone.

By default, selected attributes are enabled for selected object types.

To enable data collection of telemetry attributes, set the telemetry attributes to enabled.

The Sun Cluster software collects data on only an object type for the telemetry attributes that are enabled for that object type. When you enable an attribute for an object type, Sun Cluster software collects data for that attribute for all object instances of that type on all nodes.

Users other than superuser require solaris.cluster.modify RBAC authorization to use this subcommand. See the rbac(5) man page.

export

Exports the configuration of the telemetry attributes of object types and object instances to a file or to the standard output (stdout).

You can use this subcommand only in the global zone.

The configuration includes whether an attribute is enabled or disabled for an object type. The configuration can also include the limits that are set for the threshold configuration.

Specify a file by using the -o option to write the configuration information to a file. If you do not specify the -o option, the cltelemetryattribute command writes the configuration information to the standard output (stdout).

The export subcommand does not modify cluster configuration data.

Users other than superuser require solaris.cluster.read RBAC authorization to use this subcommand. See the rbac(5) man page.

list

Displays the telemetry attributes that you can configure for the specified object types.

You can use this subcommand only in the global zone.

If you specify the verbose option -v, the list subcommand displays the type of object to which you can apply the attribute.

The properties of a threshold are displayed in the following format:

Threshold: severity, direction, value, rearm

Users other than superuser require solaris.cluster.read RBAC authorization to use this subcommand. See the rbac(5) man page.

print

Displays system resource usage for the specified telemetry attributes that are enabled for the specified object instances or object types.

You can use this subcommand only in the global zone.

The output includes the following data:

• Date and timestamp

• Object instance

• Object type

• Telemetry attribute

• Node

• Value

Users other than superuser require solaris.cluster.read RBAC authorization to use this subcommand. See the rbac(5) man page.

set-threshold

Modifies the settings of a threshold for a specified telemetry attribute for a specified object on a node.

You can use this subcommand only in the global zone.

Use the -p option to specify the threshold to be modified. Also use the -p option to specify the threshold properties that you want to modify. You can modify only the value and rearm threshold properties.

You must change at least one of these properties for the specified threshold. If at least one property is configured, output is displayed when you run the status subcommand.

To deactivate a threshold, specify a blank for value and rearm, as follows:

-y value=,rearm=

Users other than superuser require solaris.cluster.modify RBAC authorization to use this subcommand. See the rbac(5) man page.

show

Displays the properties that are configured for telemetry attributes on object types or object instances.

You can use this subcommand only in the global zone.

These attributes include whether the system resources are enabled for an object type. If you specify the verbose option -v, the show subcommand displays the threshold settings for the telemetry attributes that are enabled for object instances.

The properties of a threshold are displayed in the following format:

Threshold: severity, direction, value, rearm

Users other than superuser require solaris.cluster.read RBAC authorization to use this subcommand. See the rbac(5) man page.

status

Displays the current status of object types on which thresholds are configured on the standard output. If you do not set at least one threshold, there is no output to display when you run the status subcommand.

You can use this subcommand only in the global zone.

Use this subcommand without arguments to display the status for all active thresholds that currently have a warning or a fatal severity level. Possible output for thresholds includes the current severity level of the thresholds.

Users other than superuser require solaris.cluster.read RBAC authorization to use this subcommand. See the rbac(5) man page.

Options

The following options are supported:

-?
--help

Displays help information.

You can specify this option with or without a subcommand.

If you specify this option without a subcommand, the list of all available subcommands is displayed.

If you specify this option with a subcommand, the usage for that subcommand is displayed.

If you specify this option with the set-threshold subcommand, help information is displayed for all resource group properties.

If you specify this option with other options, with subcommands, or with operands, they are all ignored. No other processing occurs.

-a
--average

Prints the average of the data collected over a three-hour period and the standard deviation that is associated with this average.

If you specify the -a option and the -d option together, data that is averaged over three-hour intervals within the specified period is printed.

If you do not specify the -a option, the data that is printed is the latest data.

-b object-instance
--object-instance=object-instance
--object-instance object-instance

Specifies an object instance about which you want to display information or for which you want to set a threshold.

An object instance is always of a certain type. For example, a cluster node phys-schost-1 is an object instance of type node. The Sun Cluster software monitors system resources of an object instance only if the corresponding telemetry attributes are enabled for the object type.

-d period
--date-range=period
--date-range period

Specifies the period during which you want the Sun Cluster software to collect monitoring data.

The format of the dates and times that you specify for the period argument must conform to the International Organization for Standardization (ISO) 8601 International Date Format.

begin-time,end-time]

The period is between the two times that are separated by the comma (,).

begin-time+

The period is between the specified begin time and the current time.

end-time-

The period is between the time that the Sun Cluster software starts and begins collecting data and the specified end time.

Examples of the format of period are as follows:

-d 2006-04-30T18:00,2006-06-16T18:00

From 6:00 p.m. on 30 April 2006 to 6:00 p.m. on 16 June 2006

-d 2006-06-16+

From 12:00 midnight on 16 June 2006 onwards

-d 2006-07-31T18:00+

From 6:00 p.m. on 31 July 2006 onwards

-d 2006-06-16T18:00–

From the time that the Sun Cluster software starts to 6:00 p.m. on 16 June 2006

-d 2006-05-31T12:00,2006-06-16T11:59

From 12:00 midnight on 31 May 2006 to 11:59 p.m. on 16 June 2006

You can use this option only with the print subcommand.

-i {- | clconfigfile}
--input={- | clconfigfile-}
--input {- | clconfigfile-}

Specifies that you want to use the configuration information that is located in the clconfigfile file to specify the telemetry attribute and threshold configuration. See the clconfiguration(5CL) man page.

Specify a dash (-) with this option to provide configuration information through the standard input (stdin). If you specify other options, they take precedence over the options and information in clconfigfile.

-n node
--node=node
--node node

Specifies the node name on which Sun Cluster collects usage data. You can specify a name or a node identifier.

Do not use the -n option when specifying subcommands on object instances of type node, a resource, or a resource group.

-o {- | clconfigfile}
--output={- | clconfigfile-}
--output {- | clconfigfile-}

Writes the telemetry attribute and threshold configuration data to a file or to the standard output (stdout). The format of the configuration information is described in the clconfiguration(5CL) man page.

If you specify a file name with this option, this option creates a new file. Configuration information is then placed in that file. If you specify - with this option, the configuration information is sent to the standard output (stdout). All other standard output for the command is suppressed.

You can use this option only with the export subcommand.

-p name
--property=name
--property name

Specifies a list of properties for the status subcommand.

For information about the properties for which you can set thresholds with the set-threshold subcommand, see the description of the -p name=value option.

-p name=value
--property=name-=value
--property name- value

Specifies the properties of a threshold.

Multiple instances of -p name=value are allowed.

For information about the properties about which you can display information with the status subcommand, see the description of the -p name option.

For each threshold, you must specify a severity property and a direction property to identify the threshold. You cannot modify these properties after a threshold has been set.

Set a value for each threshold. You can also set a rearm for each threshold. Use the set-threshold subcommand to modify the value and rearm properties. Properties and values that you can specify with this option are as follows:

severity

The severity level of a threshold. The possible values to which you can set this property are fatal and warning. A threshold with a severity level of fatal is more critical than a threshold with a severity level of warning.

The severity level is displayed as a visual alarm in Sun Cluster Manager.

direction

The direction of the threshold that is to be applied. The possible values to which you can set this property are falling and rising. By setting the direction property to falling, you specify that the fatal severity level has a lower value than the warning severity level. By setting the direction property to rising, you specify that the fatal severity level has a higher value than the warning severity level.

value

The value for which you want to set a threshold on a telemetry attribute. If the threshold value is crossed, the severity of the telemetry attribute changes. You can associate up to four thresholds with a particular telemetry attribute on an object.

Use the set-threshold subcommand to set or modify the value property.

rearm

A means of clearing the severity on a telemetry attribute. By specifying a rearm value, the severity on a telemetry attribute is cleared when the value of the telemetry attribute crosses the rearm value in the direction opposed to that set in the direction property. If you do not specify the rearm value, the rearm value is as if the threshold value and the rearm value are set to the same value.

The frequency of notifications follows the principle of hysteresis, that is, the frequency is determined by a double-valued function. One value applies when the function is increasing. The other value applies when the function is the same as the value.

Set the values of rearm and value to suit your system. If you do not specify the optional rearm property, it takes value as the default. However, if you set the rearm property to the same value as the value property, or if you do not assign a value to rearm, you receive a notification every time that the value of the monitored telemetry attribute goes above or below the value that is set for value. To avoid receiving a large number of notifications, set rearm to a value other than value.

If you specify rearm with the set-threshold subcommand, the cltelemetryattribute command ensures that the value of rearm complies with the following requirements:

• If direction is rising, value has a value that is greater than or equal to the rearm.

• If direction is falling, value has a value that is smaller than or equal to value.

Use the set-threshold subcommand to change the rearm.

-t object-type
--object-type=object-type
--object-type object-type

Specifies the type of object on which the Sun Cluster software is to collect usage data. All object instances are of a certain type.

Use this option to limit the output of subcommands to objects of the specified type.

The object types for which you can monitor system resources and each object type's associated telemetry attributes are as follows:

Object Type	Description	Telemetry Attribute
disk	Disk	rbyte.rate, wbyte.rate, read.rate, write.rate,
filesystem	File system	block.used, inode.used
ipaddr	IP address	ipacket.rate, opacket.rate
netif	Network interface	ipacket.rate, opacket.rate, rbyte.rate, wbyte.rate
node	Node	cpu.idle, cpu.iowait, cpu.used, loadavg.1mn, loadavg.5mn, loadavg.15mn, mem.used, mem.free, swap.used, swap.free
resourcegroup	Resource group	cpu.used, mem.used, swap.used
zone	Zone	cpu.idle, cpu.iowait, cpu.used, loadavg.1mn, loadavg.5mn, loadavg.15mn

The telemetry attributes that you can monitor are as follows:

Telemetry Attribute	Description
block.used	Percentage of blocks that are used on a device
cpu.idle	Amount of free CPU
cpu.iowait	Amount of CPU waiting for input/output completion
cpu.used	Amount of CPU that is used
inode.used	Percentage of inodes that are used on a device
ipacket.rate	Number of incoming packets per second
loadavg.1mn	Number of processes that waited for the CPU in the last minute
loadavg.5mn	Number of processes that waited for the CPU in the last five minutes
loadavg.15mn	Number of processes that waited for the CPU in the last fifteen minutes
mem.free	Number of Mbytes of free memory
mem.used	Number of Mbytes of memory that is used
opacket.rate	Number of outgoing packets per second
rbyte.rate	Number of Mbits that are read per second
read.rate	Number of read operations per second
swap.free	Number of Mbytes of free swap memory
swap.used	Number of Mbytes of swap memory that is used
wbyte.rate	Number of Mbits that are written per second
write.rate	Number of write operations per second

You cannot monitor all telemetry attributes that are listed in the preceding table for all object types. Use the list subcommand to display object types on which you can collect data, and telemetry attributes that you can monitor on each type of object.

-u
--utc

Display the date and time that is shown with usage data in Coordinated Universal Time (UTC) or in Greenwich Mean Time (GMT). By specifying this option, you bypass the conversion of the date and time to, or from, the local date and time. By default, Sun Cluster software displays the local date and time.

You can use this option only with the print subcommand.

-v
--verbose

Displays verbose information on the standard output (stdout).

-V
--version

Displays the version of the command.

If you specify this option with other options, with subcommands, or with operands, they are all ignored. Only the version of the command is displayed. No other processing occurs.

Operands

The following operands are supported:

telemetry-attribute

Particular telemetry attribute about which you want usage data.

The Sun Cluster software contains particular types of objects on which you can collect usage data. For each object type, you can enable monitoring of telemetry attributes. The Sun Cluster software only collects data for attributes that are enabled.

+

All telemetry groups.

Exit Status

The complete set of exit status codes for all commands in this command set are listed on the Intro(1CL) man page.

If the command is successful for all specified operands, it returns zero (CL_NOERR). If an error occurs for an operand, the command processes the next operand in the operand list. The returned exit code always reflects the error that occurred first.

This command returns the following exit status codes:

0 CL_NOERR

No error

The command that you issued completed successfully.

1 CL_ENOMEM

Not enough swap space

A cluster node ran out of swap memory or ran out of other operating system resources.

3 CL_EINVAL

Invalid argument

You typed the command incorrectly, or the syntax of the cluster configuration information that you supplied with the -i option was incorrect.

6 CL_EACCESS

Permission denied

The object that you specified is inaccessible. You might need superuser or RBAC access to issue the command. See the su(1M) and rbac(5) man pages for more information.

18 CL_EINTERNAL

Internal error was encountered

An internal error indicates a software defect or other defect.

35 CL_EIO

I/O error

A physical input/output error has occurred.

36 CL_ENOENT

No such object

The object that you specified cannot be found for one of the following reasons:

• The object does not exist.

• A directory in the path to the configuration file that you attempted to create with the -o option does not exist.

• The configuration file that you attempted to access with the -i option contains errors.

38 CL_EBUSY

Object busy

You attempted to remove a cable from the last cluster interconnect path to an active cluster node. Or, you attempted to remove a node from a cluster configuration from which you have not removed references.

39 CL_EEXIST

Object exists

The device, device group, cluster interconnect component, node, cluster, resource, resource type, or resource group that you specified already exists.

41 CL_ETYPE

Unknown type

The type that you specified with the -t or -p option does not exist.

Examples

---

Example 1 Displaying System Resources That Are Configured for an Object Type




The following command displays the system resources that are applicable to an object type, in this case a disk.

# cltelemetryattribute list -t disk rbyte.rate wbyte.rate write.rate read.rate

---

---

Example 2 Enabling Telemetry Attributes for an Object Type




The following command enables data collection for the specified telemetry attributes on all disks in the cluster.

# cltelemetryattribute enable -t disk rbyte.rate wbyte.rate

---

---

Example 3 Setting a Threshold for a Telemetry Attribute of an Object Type




The following command sets a threshold for the telemetry attribute wbyte.rate on disk d4 in the cluster. The default value of rearm is set to the value of value. Consequently, when the number of bytes that are written to disk d4 exceeds or falls below 100, the Sun Cluster software issues a fatal notification.

# cltelemetryattribute set-threshold -t disk -b d4 \ -p severity=fatal,direction=rising,value=100 wbyte.rate

---

---

Example 4 Showing the Non-Verbose List of Configured Telemetry Attributes




The following command shows the non-verbose list of telemetry attributes that are configured on all the disks in a cluster.

# cltelemetryattribute show -t disk === Telemetry Attributes === Telemetry Attribute: read.rate Unit: read/s Enabled Object Types: disk Telemetry Attribute: write.rate Unit: writes/s Enabled Object Types: disk Telemetry Attribute: wbyte.rate Unit: KBytes/s Enabled Object Types: disk Telemetry Attribute: rbyte.rate Unit: KBytes/s Enabled Object Types: disk

---

---

Example 5 Showing the Verbose List of Configuration of Telemetry Attributes




The following command shows the verbose list of telemetry attributes that are configured on all the disks in the cluster.

# cltelemetryattribute show -v -t disk === Telemetry Attributes === Telemetry Attribute: read.rate Unit: read/s Enabled Object Types: disk Telemetry Attribute: write.rate Unit: writes/s Enabled Object Types: disk Telemetry Attribute: wbyte.rate Unit: KBytes/s Enabled Object Types: disk Telemetry Attribute: rbyte.rate Unit: KBytes/s Enabled Object Types: disk % cltelemetryattribute show -v -t disk === Telemetry Attributes === Telemetry Attribute: read.rate Unit: read/s Enabled Object Types: disk Telemetry Attribute: write.rate Unit: writes/s Enabled Object Types: disk --- Object Instances of Type "disk" --- Object Instance: d4 Thresholds: <Direction, Severity, Value, Rearm> Threshold 1: <rising, fatal, 1000, 500> Telemetry Attribute: wbyte.rate Unit: KBytes/s Enabled Object Types: disk Telemetry Attribute: rbyte.rate Unit: KBytes/s Enabled Object Types: disk

---

---

Example 6 Showing the Status of Telemetry Attributes




The following command shows the status of telemetry attributes that are configured on all the disks in the cluster.

# cltelemetryattribute status === Telemetry Attributes Thresholds === Attribute Obj-Instance Obt-Type Node Threshold Status Status --------- ------------ -------- ------- --------------------------- ------- mem.used phys-schost-1 node 16-v2-4 <rising, fatal, 1000, 1000> warning

---

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWsczu
Interface Stability	Evolving

See Also

cluster(1CL), Intro(1CL), sctelemetry(1M), su(1M), attributes(5), rbac(5), SUNW.SCTelemetry(5), clconfiguration(5CL)

Notes

The superuser can run all forms of this command.

All users can run this command with the -? (help) or -V (version) option.

To run the cltelemetryattribute command with other subcommands, users other than superuser require RBAC authorizations. See the following table.

Subcommand	RBAC Authorization
disable	solaris.cluster.modify
enable	solaris.cluster.modify
export	solaris.cluster.read
list	solaris.cluster.read
print	solaris.cluster.read
set-threshold	solaris.cluster.modify
show	solaris.cluster.read
status	solaris.cluster.read

Sun Cluster 3.2  Last Revised 6 August 2009

Name | Synopsis | Description | SUBCOMMANDS | Options | Operands | Exit Status | Examples | Attributes | See Also | Notes