Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### 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`(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 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 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 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 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 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`(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 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`(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 Oracle Solaris 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 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 | 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, 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`(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, resource group, or private string 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 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`(5) for descriptions of the following attributes:

ATTRIBUTE TYPE | ATTRIBUTE VALUE
--- | ---
Availability | `ha-cluster/system/core`
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`

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |