Periodic Stats Logger Plugin

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.

This plugin logs server statistics to the specified log file at the specified interval. Statistics can be logged either in JSON format or in a comma-separated format. This is primarily used for profiling server performance. Unless the log-interval property is set too small, this has a negligible impact on performance.

Parent Component Relations from This Component Properties dsconfig Usage

Parent Component

The Periodic Stats Logger Plugin component inherits from the Stats Plugin

Relations from This Component

The following components have a direct composition relation from Periodic Stats Logger Plugins:

The following components have a direct aggregation relation from Periodic Stats Logger Plugins:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
 description  entry-cache-info
 enabled  host-info
 local-db-backend-info  included-ldap-application
 replication-info  collection-interval
 log-interval  ldap-changelog-info
 suppress-if-idle  gauge-info
 header-prefix-per-column
 empty-instead-of-zero
 lines-between-header
 included-ldap-stat
 included-resource-stat
 histogram-format
 histogram-op-type
 per-application-ldap-stats
 status-summary-info
 log-file-format
 log-file
 log-file-permissions
 append
 rotation-policy
 rotation-listener
 retention-policy
 logging-error-behavior

Basic Properties

description

Description
A description for this Plugin
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 plug-in is enabled for use.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

local-db-backend-info

Description
Specifies the level of detail to include about the Local DB Backends.
Default Value
none
Allowed Values
none - No details are included about the Local DB Backends.

basic - Only basic information is included for each Local DB Backend.

extended - Extended information is included for each Local DB Backend.

verbose - Verbose information is included for each Local DB Backend.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

replication-info

Description
Specifies the level of detail to include about replication.
Default Value
none
Allowed Values
none - No details are included about replication.

basic - Only basic information is included about replication.

extended - Extended information is included about replication.

verbose - Verbose information is included about replication.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

log-interval

Description
The duration between statistics collection and logging. A new line is logged to the output for each interval. Setting this value too small can have an impact on performance.
Default Value
5 seconds
Allowed Values
A duration. Lower limit is 10 milliseconds.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

suppress-if-idle

Description
If the server is idle during the specified interval, then do not log any output if this property is set to true. The server is idle if during the interval, no new connections were established, no operations were processed, and no operations are pending.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

header-prefix-per-column

Description
This property controls whether the header prefix, which applies to a group of columns, appears at the start of each column header or only the first column in a group. Columns associated with the same monitor entry are grouped together in the output. If this property is set to true, then each column header will include the full prefix. This makes it easier to automatically parse the output. If set to false, then only the first column for each group of columns will include the header prefix. This makes the column header more compact.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

empty-instead-of-zero

Description
This property controls whether a value in the output is shown as empty if the value is zero. If the value of a column is zero, then it can alternatively be shown as empty. This can make it easier to visually spot non-zero values, but it can also increase the complexity of automatically parsing the output. Even if this is set to true, some columns might show up as zero.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

lines-between-header

Description
The number of lines to log between logging the header line that summarizes the columns in the table.
Default Value
50
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

included-ldap-stat

Description
Specifies the types of statistics related to LDAP connections and operation processing that should be included in the output. Some more detailed LDAP statistics including the processing time histogram are controlled by other properties of this object.
Default Value
None
Allowed Values
active-operations - The count of active operations that are in progress when information about the interval is logged.

num-connections - The count of currently established connections and newly established connections.

op-count-and-latency - The number of completed operations, operations per second, and average latency for each LDAP operation type. Use the per-application-ldap-stats setting to further control this.

work-queue - The average and maximum number of operations pending in the work queue and the average and maximum percent busy-ness of the worker threads.

ldap-protocol - Statistics related to LDAP protocol processing, including the number of bytes/messages sent and received as well as the number of search requests and search result entries returned.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

included-resource-stat

Description
Specifies whether statistics related to resource utilization such as JVM memory.
Default Value
None
Allowed Values
memory-utilization - Statistics related to memory consumers, garbage collection, and the amount of JVM memory used.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

histogram-format

Description
The format of the data in the processing time histogram.
Default Value
count
Allowed Values
count - Each column reports the count of values within the specified histogram bucket.

aggregate-percentage - Each column reports the aggregate percentage of operations that completed in less than the histogram bucket duration.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

histogram-op-type

Description
Specifies the operation type(s) to use when outputting the response time histogram data. The order of the operations here determines the order of the columns in the output. Use the per-application-ldap-stats setting to further control this.
Default Value
None
Allowed Values
all - The processing time histogram data output includes the distribution for the total of all operations.

add - The processing time histogram data output includes the distribution for add operations.

bind - The processing time histogram data output includes the distribution for bind operations.

compare - The processing time histogram data output includes the distribution for compare operations.

delete - The processing time histogram data output includes the distribution for delete operations.

extended - The processing time histogram data output includes the distribution for extended operations.

modify - The processing time histogram data output includes the distribution for modify operations.

modify-dn - The processing time histogram data output includes the distribution for modify-dn operations.

search - The processing time histogram data output includes the distribution for search operations.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

per-application-ldap-stats

Description
Controls whether per application LDAP statistics are included in the output for selected LDAP operation statistics. When statistics such as LDAP operation count and response time histogram are enabled, they can be included on an aggregate level and/or per application. The included-ldap-application property can restrict which applications are included in the output.
Changes to other configuration objects are necessary to enable tracking of statistics on a per-application basis. The tracked-application Global Configuration setting must be configured, and the separate-monitor-entry-per-tracked-application setting on the Processing Time Histogram Plugin configuration object must be set to expose per-application monitoring information under cn=monitor. Consult the product documentation for more details on configuring the Directory Server to track LDAP statistics on a per application basis.
Default Value
aggregate-only
Allowed Values
aggregate-only - Statistics will only be included for LDAP operations aggregated across all applications.

per-application-only - Statistics will only be included on a per application basis.

per-application-and-aggregate - Statistics will be included both on an aggregate and per application basis.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

status-summary-info

Description
Specifies the level of detail to include about the status summary monitor entry.
Default Value
none
Allowed Values
none - No details are included from the status summary monitor entry.

basic - Only basic information is included from the status summary monitor entry.

verbose - Verbose information is included from the status summary monitor entry.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

log-file-format

Description
Specifies the format to use when logging server statistics.
Default Value
csv
Allowed Values
csv - Statistics are logged in comma-separated format.

json - Statistics are logged in JSON format.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

log-file

Description
The file name to use for the log files generated by the Periodic Stats Logger Plugin. The path to the file can be specified either as relative to the server root or as an absolute path.
Default Value
None
Allowed Values
A filesystem path
Multi-Valued
No
Required
Yes
Admin Action Required
The Periodic Stats Logger Plugin must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server

log-file-permissions

Description
The UNIX permissions of the log files created by this Periodic Stats Logger Plugin.
Default Value
600
Allowed Values
A valid UNIX mode string. The mode string must contain three digits between zero and seven.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

append

Description
Specifies whether to append to existing log files.
Default Value
true
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

rotation-policy

Description
The rotation policy to use for the Periodic Stats Logger Plugin . When multiple policies are used, rotation will occur if any policy's conditions are met.
Default Value
No rotation policy is used and log rotation will not occur.
Allowed Values
The DN of any Log Rotation Policy.
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action

rotation-listener

Description
A listener that should be notified whenever a log file is rotated out of service.
Default Value
None
Allowed Values
The DN of any Log File Rotation Listener. If this Periodic Stats Logger Plugin is enabled, then the associated log file rotation listener must also be enabled.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

retention-policy

Description
The retention policy to use for the Periodic Stats Logger Plugin . When multiple policies are used, log files are cleaned when any of the policy's conditions are met.
Default Value
No retention policy is used and log files are never cleaned.
Allowed Values
The DN of any Log Retention Policy.
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action

logging-error-behavior

Description
Specifies the behavior that the server should exhibit if an error occurs during logging processing.
Default Value
standard-error
Allowed Values
standard-error - Write a message to standard error in the event of a logging failure.

lockdown-mode - Place the server in lockdown mode in the event of a logging failure.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


Advanced Properties

entry-cache-info (Advanced Property)

Description
Specifies the level of detail to include for each entry cache.
Default Value
none
Allowed Values
none - No details are included about the entry cache.

basic - Only basic information is included for the entry cache.

extended - Verbose information is included for the entry cache.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

host-info (Advanced Property)

Description
Specifies the level of detail to include about the host system resource utilization including CPU, memory, disk and network activity. The server can capture performance information about the host system including CPU, network and disk utilization values. If the monitor providers that capture this information are enabled, the performance data can be captured by the Data Metrics Server. Providing host system performance data gives a more robust understanding of application performance problems, as well as a useful tool for capacity planning.
Default Value
None
Allowed Values
cpu - Information is included about the CPU and memory utilization. This data is produced by Host System Cpu Memory Monitor Provider.

disk - Information is included about the disk utilization of selected disks. Disks to be reported are configured in Host System Disk Monitor Provider.

network - Information is included about network utilization of selected interfaces. Networks to be reported are configured in Host System Network Monitor Provider.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

included-ldap-application (Advanced Property)

Description
If statistics should not be included for all applications, this property names the subset of applications that should be included. If per-application-ldap-stats is set to per-application-only or per-application-and-aggregate, then this property can be used to restrict the output to only a subset of applications. By default all tracked applications are included. Consult the product documentation for instructions on configuring the Directory Server to track LDAP statistics on a per application basis.
Default Value
If per-application LDAP stats is enabled, then stats will be included for all applications.
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

collection-interval (Advanced Property)

Description
Some of the calculated statistics, such as the average and maximum queue sizes, can use multiple samples within a log interval. This value controls how often samples are gathered. It should be a multiple of the log-interval.
Default Value
100 milliseconds
Allowed Values
A duration. Lower limit is 10 milliseconds.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

ldap-changelog-info (Advanced Property)

Description
Specifies the level of detail to include for the LDAP changelog.
Default Value
none
Allowed Values
none - No details are included about the LDAP changelog.

basic - Only basic information is included for the LDAP changelog.

extended - Extended information is included for the LDAP changelog.

verbose - Verbose information is included for the LDAP changelog.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

gauge-info (Advanced Property)

Description
Specifies the level of detail to include for Gauges.
Default Value
none
Allowed Values
none - No details are included about Gauges.

basic - Only basic information is included for Gauges. This includes the current value and severity.

extended - Extended information is included for Gauges. In addition to the basic information, the duration at the current severity is included.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Plugins:

dsconfig list-plugins
     [--property {propertyName}] ...

To view the configuration for an existing Plugin:

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

To update the configuration for an existing Plugin:

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

To create a new Periodic Stats Logger Plugin:

dsconfig create-plugin
     --plugin-name {name}
     --type {type}
     --set enabled:{propertyValue}
     --set log-file:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Plugin:

dsconfig delete-plugin
     --plugin-name {name}