Go to main content

Reference for Oracle Solaris Cluster 4.4

Exit Print View

Updated: August 2018
 
 

clta (8CL)

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 Oracle Solaris 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(8) 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 Oracle Solaris 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, Oracle Solaris 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 the root role require solaris.cluster.modify authorization to use this subcommand. See the rbac(7) 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 Oracle Solaris 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, Oracle Solaris Cluster software collects data for that attribute for all object instances of that type on all nodes.

Users other than the root role require solaris.cluster.modify authorization to use this subcommand. See the rbac(7) 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 the root role require solaris.cluster.read authorization to use this subcommand. See the rbac(7) 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 the root role require solaris.cluster.read authorization to use this subcommand. See the rbac(7) 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 the root role require solaris.cluster.read authorization to use this subcommand. See the rbac(7) 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 the root role require solaris.cluster.modify authorization to use this subcommand. See the rbac(7) 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 the root role require solaris.cluster.read authorization to use this subcommand. See the rbac(7) 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 the root role require solaris.cluster.read authorization to use this subcommand. See the rbac(7) 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 Oracle Solaris 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 Oracle Solaris 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 Oracle Solaris 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 Oracle Solaris 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(7CL) 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 Oracle Solaris 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(7CL) 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 the Oracle Solaris Cluster Manager browser interface.

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 Oracle Solaris 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
Object Description and Telemetry Attributes
disk
(A disk) rbyte.rate, wbyte.rate, read.rate, write.rate
filesystem
(A file system) block.used, inode.used
ipaddr
(An IP address) ipacket.rate, opacket.rate
netif
(A network interface) ipacket.rate, opacket.rate, rbyte.rate, wbyte.rate
node
(A cluster node) cpu.idle, cpu.iowait, cpu.used, loadavg.1mn, loadavg.5mn, loadavg.15mn, mem.used, mem.free, swap.used, swap.free
resourcegroup
(A resource group) cpu.used, mem.used, swap.used
zone
(A 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, Oracle Solaris 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 Oracle Solaris 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 Oracle Solaris 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(8CL) 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 the root role or authorization to issue the command. See the rbac(7) man page 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: (1) The object does not exist. (2) A directory in the path to the configuration file that you attempted to create with the –o option does not exist. (3)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, resource group, or private string that you specified already exists.

41 CL_ETYPE

Invalid 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 Oracle Solaris 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(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
ha-cluster/system/core
Interface Stability
Evolving

See Also

clconfiguration(7CL), SUNW.SCTelemetry(7), attributes(7), rbac(7), Intro(8CL), cluster(8CL), sctelemetry(8), su(8)

Notes

The root role 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 the root role require authorizations. See the following table.

Subcommand
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