Custom Logged Stats

Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.

A custom Custom Logged Stats object enables additional statistics to be included in the output of a Periodic Stats Logger.

Each Custom Logged Stats object is tied to a single monitor entry type, defined by the objectclass of the entry. One or more attributes in each monitor entry can be monitored. You have a lot of control over how the values of the monitored attributes are treated. They can be treated as raw values, counters, or continuous values--with the average, minimum, or maximum values reported. The value to report can be extracted from the monitor attribute using regular expressions and/or by dividing the value by a fixed amount or another attribute in the monitor entry.

All of these configuration settings apply to each monitored attribute. To have multiple attributes in the same entry treated differently, you must create multiple Custom Logged Stats. The server will group columns for the same monitor entry together.

Relations to This Component Properties dsconfig Usage

Relations to This Component

The following components have a direct composition relation to Custom Logged Stats:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  regex-pattern
 enabled  regex-replacement
 monitor-objectclass  divide-value-by
 include-filter  divide-value-by-attribute
 attribute-to-log  decimal-format
 column-name  non-zero-implies-not-idle
 statistic-type
 header-prefix
 header-prefix-attribute

Basic Properties

description

Description
A description for this Custom Logged Stats
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enabled

Description
Indicates whether the Custom Logged Stats object is enabled. If it is not enabled, then the attributes monitored here will not appear in the output.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

monitor-objectclass

Description
The objectclass name of the monitor entries to examine for generating these statistics.
Default Value
None
Allowed Values
The objectclass name of the monitor entries to examine for generating these statistics.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

include-filter

Description
An optional LDAP filter that can be used restrict which monitor entries are used to produce the output. If an LDAP filter is specified, then only monitor entries that match the filter will be included in the statistics output.
Default Value
None
Allowed Values
A valid LDAP search filter
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

attribute-to-log

Description
Specifies the attributes on the monitor entries that should be included in the output. The full column name, which appears in the header, is built from the header-prefix, the header-prefix-attribute, and the column name, which is either determined automatically from the monitor entry attribute name or is specified explicitly in the column-name property. Both the header-prefix, and the header-prefix-attribute column names are optional.
Default Value
None
Allowed Values
The name of the attribute to log.
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action

column-name

Description
Optionally, specifies an explicit name for each column header instead of having these names automatically generated from the monitored attribute name. The full column name, which appears in the header, is built from the header-prefix, the header-prefix-attribute, and the column name, which is either determined automatically from the monitor entry attribute name or is specified explicitly in the column-name property. The column-name, header-prefix, and header-prefix-attribute properties are optional.

The number of items in this property must line up with the attribute-to-log property. That is, the first value in this property will be used as the column name for the first value in the attribute-to-log property.

Default Value
None
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

statistic-type

Description
Specifies the type of statistic to include in the output for each monitored attribute. The statistics listed here will be applied to each attribute listed in the attribute-to-log list. The statistic is computed after all other optional processing such as regular expression manipulation and value scaling.

If a single monitor entry includes attributes of different statistic-types, then multiple Custom Logged Stats objects must be specified.

Default Value
None
Allowed Values
raw - The raw value of the monitor attribute is used to provide the output value. This can be used for attributes that have a continuous value such as free disk space.

counter - The monitored attribute is interpreted as a monotonically increasing counter. The difference between successive measurements of the attribute value is used to provide the output value.

average - Multiple samples of the monitored attribute value are taken during the interval, and the average value of the measurements is output.

minimum - Multiple samples of the monitored attribute value are taken during the interval, and the minimum value of the measurements is output.

maximum - Multiple samples of the monitored attribute value are taken during the interval, and the maximum value of the measurements is output.
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action

header-prefix

Description
An optional prefix that is included in the header before the column name. The full column name, which appears in the header, is built from the header-prefix, the header-prefix-attribute, and the column name, which is either determined automatically from the monitor entry attribute name or is specified explicitly in the column-name property. The column-name, header-prefix, and header-prefix-attribute properties are optional.
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

header-prefix-attribute

Description
An optional attribute from the monitor entry that is included as a prefix before the column name in the column header. The full column name, which appears in the header, is built from the header-prefix, the header-prefix-attribute, and the column name, which is either determined automatically from the monitor entry attribute name or is specified explicitly in the column-name property. The column-name, header-prefix, and header-prefix-attribute properties are optional.

The header-prefix-attribute is typically used to disambiguate columns that are associated with multiple monitor entries that are matched by the monitor-objectclass and include-filter.

Default Value
None
Allowed Values
The name of the header prefix attribute.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


Advanced Properties

regex-pattern (Advanced Property)

Description
An optional regular expression pattern, that when used in conjunction with regex-replacement, can alter the value of the attribute being monitored. This is used to extract a portion of a monitored attribute value or otherwise alter it before it's processed. For example, it could be used to strip off an attribute value that ended in a '%' or to extract a single value from an attribute value that had the form "key1=value1 key2=value2".

The regular expression value passed in here uses the syntax described in the java.util.regex.Pattern javadoc. The regex-replacement value is used to replace all occurrences of the matched regular expression pattern. If the attribute value is stored in attrValue, this regular expression pattern is in regexPattern, and the regex-replacement is stored in regexReplacement, then the updated attribute value is computed logically as follows:

attrValue = Pattern.compile(regexPattern).matcher(attrValue).replaceAll(regexReplacement);

The regular expression pattern and replacement is applied before any other processing on the attribute value such as scaling.

Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

regex-replacement (Advanced Property)

Description
An optional regular expression replacement value, that when used in conjunction with regex-pattern, can alter the value of the attribute being monitored. This is used to replace a matched portion of a monitored attribute value. For example, it could be used to strip off an attribute value that ended in a '%' or to extract a single value from an attribute value that had the form "key1=value1 key2=value2".

The regular expression replacement value passed in here uses the syntax described in the java.util.regex.Matcher#replaceAll javadoc. The regex-replacement value is used to replace all occurrences of the matched regular expression pattern. If the attribute value is stored in attrValue, this regular expression pattern is in regexPattern, and the regex-replacement is stored in regexReplacement, then the updated attribute value is computed logically as follows:

attrValue = Pattern.compile(regexPattern).matcher(attrValue).replaceAll(regexReplacement);

The regular expression pattern and replacement is applied before any other processing on the attribute value such as scaling.

Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

divide-value-by (Advanced Property)

Description
An optional floating point value that can be used to scale the resulting value. This is used to scale the resulting value by a fixed amount. This is typically used to reduce large values to a more manageable length. For instance, free disk space could be represented in GB instead of just bytes. If a value for this property is specified, then it will be applied to the monitored attribute after any regular expression replacement is done and before it is scaled by the divide-value-by-attribute.
Default Value
None
Allowed Values
A floating point value used to scale the result.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

divide-value-by-attribute (Advanced Property)

Description
An optional property that can scale the resulting value by another attribute in the monitored entry. This is used to scale the resulting value by another attribute that is part of the same monitored entry. One example use case of this is to calculate the percentage busy of the server worker threads by dividing the number of busy threads by the total number of threads. If a value for this property is specified, then it will be applied after the value is scaled by divide-value-by if that property is specified.
Default Value
None
Allowed Values
The name of the attribute to divide by.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

decimal-format (Advanced Property)

Description
This provides a way to format the monitored attribute value in the output to control the precision for instance. The value specified here is used to construct a java.text.DecimalFormat object, which is used to format the monitored attribute value. See the Javadoc for the DecimalFormat class to understand the syntax of the format. For example, #.## provides two digits after the decimal place (assuming the digits are non-zero).
Default Value
#.##
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

non-zero-implies-not-idle (Advanced Property)

Description
If this property is set to true, then the value of any of the monitored attributes here can contribute to whether an interval is considered "idle" by the Periodic Stats Logger. This setting only has an effect if the corresponding Periodic Stats Logger has suppress-if-idle set to true. In this case, statistics for an interval are not included if the server is considered "idle". If this property is set to true, all of the statistics for an interval are included in the output if it has a non-zero value.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Custom Logged Stats:

dsconfig list-custom-logged-stats
     [--property {propertyName}] ...

To view the configuration for an existing Custom Logged Stats:

dsconfig get-custom-logged-stats-prop
     --stats-name {name}
     --plugin-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Custom Logged Stats:

dsconfig set-custom-logged-stats-prop
     --stats-name {name}
     --plugin-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new Custom Logged Stats:

dsconfig create-custom-logged-stats
     --stats-name {name}
     --plugin-name {name}
     --set monitor-objectclass:{propertyValue}
     --set attribute-to-log:{propertyValue}
     --set statistic-type:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Custom Logged Stats:

dsconfig delete-custom-logged-stats
     --stats-name {name}
     --plugin-name {name}