ssid - Statistics Store Identifier
The Oracle Solaris Statistics Store uses statistics identifiers known as ssids, ssids name system resources, statistics and events. SSIDs also specify arithmetic and statistical operations on statistics and formatting of event output.
ssids are used by the sstore(1) command and the libsstore(3LIB) library calls. ssids can be defined through metadata, as described in the ssid-metadata(7) man page.
An ssid is a string where only //: is a reserved sequence to separate the components of the ssid. Each component can have its own character restrictions.
A //:class and //:res component pair is required to identify a system resource. The following example identifies CPU 0:
//:class.cpu//:res.id/0
The //:stat component identifies a statistic. The following SSID represents the usage of CPU 0:
//:class.cpu//:res.id/0//:stat.usage
Some statistics can be viewed either as an aggregate or by selected partitions, which are described in the //:part section. For example, CPU usage can be broken down by mode (kernel, user, and so on):
//:class.cpu//:res.id/0//:stat.usage//:part.mode
An event is a time-specific change to a resource or class. The following SSID describes a fault of CPU 0:
//:class.cpu//:res.id/0//:event.fault
A variety of operations are available for statistics. For example:
//:class.cpu//:res.id/0//:stat.usage//:part.mode//:op.rate
A pre-defined set of formatting operations is available for events.
//:class.cpu//:res.id/0//:event.fault//:fmt.summary
Relationships between system resources can be represented as topology in an ssid.
Slices and wildcard notation can be used to match multiple items in an ssid. * is a simple wildcard character. The following examples show the matching of CPUs in an ssid:
//:class.cpu//:res.id/*
//:class.cpu//:res.id///:s.[0:5]
Each component of an SSID has metadata with information such as description and data type. Use the info subcommand of sstore(1) to retrieve this information.
Collections are references to groups of statistics and events.
SSIDs can have the following components:
The system on which a statistic is produced. The default is //:system.name/localhost. Currently, only //:system.name/localhost is supported.
A system resource is identified by a combination of class, the resource type, and the resource name. A class defines how resources can be named within that class. A single resource might be available through multiple names within the same class. For example, both of the following names refer to the same device.
//:class.disk//:res.dev/zvblk0
//:class.disk//:res.name/zvblk0
Resource names in SSIDs typically are the same as resource names used in administrative commands.
In addition, note that some resources can appear in multiple classes under different names, formally known as aliases. For example, a disk can appear in both //:class.disk and //:class.dev. However, not all aliases for a given resource are always available.
Class names can contain only alphanumeric characters (lowercase strongly encouraged) and the hyphen character (-), and must start with an alphanumeric character. Resource names have no restrictions.
As a best practice, use a unique company name when you add a class. //:class.solaris/ and //:class.s/ are explicitly reserved. //:class.site is available for administrative use.
The current list of classes on a specific system can be viewed with the following command:
$ sstore list //:class.*
Resources within a class can be viewed with the following command:
$ sstore list //:class.cpu//:res.*
Relationships between resources are represented in the ssid namespace as topology links. Regardless of topology, you can reference any resource in the system by the last class and resource in the ssid. Resources are never named solely by their topology.
While you do not need to know system topology to name a resource, there are many situations in which exploring and representing topology are useful. You represent topologies by allowing a class/resource pair after other related resources, as in the following example:
//:class.chip//:res.id/0//:class.cpu//:res.id/0 //:class.chip//:res.id/0//:class.cpu//:res.id/1
This explains that chip 0 contains cpus 0 and 1.
A topology is only valid at a specific point in time as topologies change. You may query the topology at a point of time in the past by exploring the namespace at that time range.
Both resources and classes can have statistics. A statistic is any piece of information about the resource or class. There is a common set of supported statistic types such as counters (preferred) and scalars. See sstore(7) for more information about metadata in general and statistic types in particular.
//:class.link/phys//:res.name/net0//:stat.in-bytes
You can partition only statistics. Partitions provide a dynamic view of entities that constitute that statistic. Partitions can be defined as static or dynamic. A static partition includes a full enumeration (in metadata) of the exact names of the entities in that partition. One such static partition is the mode partition of CPU usage shown as follows:
//:class.cpu//:stat.usage//:part.mode
A dynamic partition returns a different list of entities depending on when you query it. In general, you should define partitions as complete. Combining all entities in a partition should yield 100% of the statistic. You can discover partitions on a statistic by using the sstore list command as follows:
$ sstore list //:class.cpu//:stat.usage//:part.*
Events are time-specific information about changes to a resource or class. Currently, events are captured for faults and administrative actions on various resources.
For example, administrative actions, faults, and alerts for all CPUs are respectively as follows:
//:class.cpu//:res.id/*//:event.adm-action
//:class.cpu//:res.id/*//:event.fault
//:class.cpu//:res.id/*//:event.alert
A pre-defined set of mathematical and statistical operations is allowed on statistics. The operations available for any specific statistic or event are constrained by its type and metadata.
The full list of operations is documented in ssid-op(7) and can be shown by the following command:
//:class.cpu//:stat.usage//:part.mode//:op.rate
A pre-defined set of formatting operations is allowed for events. The full list of formatting operations is documented in ssid-op(7) and can be shown by the following command:
//:class.cpu//:res.id/0//:event.fault//:fmt.summary
For more information, see the ssid-collection.json(5) man page
You can use the * as a simple wildcarding mechanism. For example, you can match all classes as follows:
//:class.*
The * can appear at any time and matches to the next //: separator. For example, you can match all classes as follows:
//:clas*
You can also match a list of resources, statistics, partitions, and other entities in the namespace using slices. This can be very helpful when you are using operations.
You can use slices to match CPUs with ID 0-5 as shown in the following example:
//:class.cpu//:res.id///:s.[0:5]
sstore(1), ssid-collection.json(5), ssid-metadata(7), ssid-op(7), sstoreadm(1)