Class CollectSupportDataTask

  • All Implemented Interfaces:
    java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class CollectSupportDataTask
    extends Task
    This class defines a Directory Server task that can be used to invoke the collect-support-data tool to capture a variety of information that may help monitor the state of the server or diagnose potential problems.
    NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

    The properties that are available for use with this type of task include:
    • The path (on the server filesystem) to which the support data archive should be written. If this is not provided, then the server will determine an appropriate output file to use. If this is provided and refers to a file that exists, that file will be overwritten. If this is provided and refers to a directory that exists, then a file will be created in that directory with a server-generated name. If this is provided and refers to a file that does not exist, then its parent directory must exist, and a new file will be created with the specified path.
    • The path (on the server filesystem) to a file containing the passphrase to use to encrypt the contents of the support data archive. If this is not provided, then the support data archive will not be encrypted.
    • A flag that indicates whether to include data that may be expensive to capture in the support data archive. This information will not be included by default.
    • A flag that indicates whether to include a replication state dump (which may be several megabytes in size) in the support data archive. This information will not be included by default.
    • A flag that indicates whether to include binary files in the support data archive. Binary files will not be included by default.
    • A flag that indicates whether to include source code (if available) to any third-party extensions installed in the server. Extension source code will not be included by default.
    • The data security level to use when redacting data to include in the support data archive. If this is not specified, the server will select an appropriate security level.
    • A flag that indicates whether to capture items in sequential mode (which will use less memory, but at the expense of taking longer to complete) rather than in parallel. Support data will be captured in parallel by default.
    • The number and duration between intervals for use when collecting output of tools (like vmstat, iostat, mpstat, etc.) that use sampling over time. If this is not provided, the server will use a default count and interval.
    • The number of times to invoke the jstack utility to obtain a stack trace of threads running in the JVM. If this is not provided, the server will use a default count.
    • The duration (the length of time before the time the task is invoked) for log messages to be included in the support data archive. If this is not provided, the server will automatically select the amount of log content to include.
    • The amount of data in kilobytes to capture from the beginning or end of each log file. If this is not provided, the server will automatically select the amount of log content to include.
    • An optional comment to include in the support data archive.
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String ATTR_COMMENT
      The name of the attribute used to specify a comment to include in the support data archive.
      static java.lang.String ATTR_ENCRYPTION_PASSPHRASE_FILE
      The name of the attribute used to specify the path to a file containing the passphrase to use to encrypt the contents of the support data archive.
      static java.lang.String ATTR_INCLUDE_BINARY_FILES
      The name of the attribute used to indicate whether the support data archive may include binary files that may otherwise have been omitted.
      static java.lang.String ATTR_INCLUDE_EXPENSIVE_DATA
      The name of the attribute used to indicate whether the support data archive should include information that may be expensive to capture.
      static java.lang.String ATTR_INCLUDE_EXTENSION_SOURCE
      The name of the attribute used to indicate whether the support data archive may include the source code (if available) for any third-party extensions installed in the server.
      static java.lang.String ATTR_INCLUDE_REPLICATION_STATE_DUMP
      The name of the attribute used to indicate whether the support data archive should include a replication state dump (which may be several megabytes in size).
      static java.lang.String ATTR_JSTACK_COUNT
      The name of the attribute used to specify the number of times to invoke the jstack utility to capture server thread stack traces.
      static java.lang.String ATTR_LOG_DURATION
      The name of the attribute used to specify the length of time that should be covered by the log data included in the support data archive.
      static java.lang.String ATTR_LOG_END_TIME
      The name of the attribute used to specify the end time for the range of log messages that should be included in the support data archive.
      static java.lang.String ATTR_LOG_FILE_HEAD_COLLECTION_SIZE_KB
      The name of the attribute used to specify the amount of data in kilobytes to capture from the beginning of each log file included in the support data archive.
      static java.lang.String ATTR_LOG_FILE_TAIL_COLLECTION_SIZE_KB
      The name of the attribute used to specify the amount of data in kilobytes to capture from the end of each log file included in the support data archive.
      static java.lang.String ATTR_LOG_START_TIME
      The name of the attribute used to specify the start time for the range of log messages that should be included in the support data archive.
      static java.lang.String ATTR_OUTPUT_PATH
      The name of the attribute used to specify the path to which the support data archive should be written.
      static java.lang.String ATTR_REPORT_COUNT
      The name of the attribute used to specify the number of intervals to capture for tools that capture multiple samples.
      static java.lang.String ATTR_REPORT_INTERVAL_SECONDS
      The name of the attribute used to specify the length of time, in seconds, between samples collected from tools that capture multiple samples.
      static java.lang.String ATTR_RETAIN_PREVIOUS_ARCHIVE_AGE
      The name of the attribute used to specify the minimum age of previous support data archives that should be retained.
      static java.lang.String ATTR_RETAIN_PREVIOUS_ARCHIVE_COUNT
      The name of the attribute used to specify the minimum number of previous support data archives that should be retained.
      static java.lang.String ATTR_SECURITY_LEVEL
      The name of the attribute used to specify the security level to use for information added to the support data archive.
      static java.lang.String ATTR_USE_SEQUENTIAL_MODE
      The name of the attribute used to indicate whether to collect items sequentially rather than in parallel.
      static java.lang.String OC_COLLECT_SUPPORT_DATA_TASK
      The name of the object class used in collect support data task entries.
    • Constructor Detail

      • CollectSupportDataTask

        public CollectSupportDataTask()
        Creates a new collect support data task instance that will use default settings for all properties. This instance may be used to invoke the task, but it can also be used for obtaining general information about this task, including the task name, description, and supported properties.
      • CollectSupportDataTask

        public CollectSupportDataTask​(@NotNull
                                      Entry entry)
                               throws TaskException
        Creates a new collect support data task from the provided entry.
        Parameters:
        entry - The entry to use to create this collect support data task.
        Throws:
        TaskException - If the provided entry cannot be parsed as a collect support data task entry.
      • CollectSupportDataTask

        public CollectSupportDataTask​(@NotNull
                                      java.util.Map<TaskProperty,​java.util.List<java.lang.Object>> properties)
                               throws TaskException
        Creates a new collect support data task from the provided set of task properties.
        Parameters:
        properties - The set of task properties and their corresponding values to use for the task. It must not be null.
        Throws:
        TaskException - If the provided set of properties cannot be used to create a valid collect support data task.
    • Method Detail

      • getTaskName

        @NotNull
        public java.lang.String getTaskName()
        Retrieves a human-readable name for this task.
        Overrides:
        getTaskName in class Task
        Returns:
        A human-readable name for this task.
      • getOutputPath

        @Nullable
        public java.lang.String getOutputPath()
        Retrieves the path on the server filesystem to which the support data archive should be written.
        Returns:
        The path on the server filesystem to which the support data archive should be written, or null if no value has been specified for the property.
      • getEncryptionPassphraseFile

        @Nullable
        public java.lang.String getEncryptionPassphraseFile()
        Retrieves the path on the server filesystem to a file that contains the passphrase to use to encrypt the support data archive.
        Returns:
        The path on the server filesystem to a file that contains the passphrase to use to encrypt the support data archive, or null if no value has been specified for the property, and the support data archive should not be encrypted.
      • getIncludeExpensiveData

        @Nullable
        public java.lang.Boolean getIncludeExpensiveData()
        Retrieves the value of a flag that indicates whether the support data archive may include data that is potentially expensive to collect and could affect the performance or responsiveness of the server.
        Returns:
        The value of a flag that indicates whether the support data archive may include data that is potentially expensive to collect, or null if the property should not be specified when the task is created (in which case the server will use a default behavior of excluding expensive data).
      • getIncludeReplicationStateDump

        @Nullable
        public java.lang.Boolean getIncludeReplicationStateDump()
        Retrieves the value of a flag that indicates whether the support data archive may include a replication state dump, which may be several megabytes in size.
        Returns:
        The value of a flag that indicates whether the support data archive may include a replication state dump, or null if the property should not be specified when the task is created (in which case the server will use a default behavior of excluding the state dump).
      • getIncludeBinaryFiles

        @Nullable
        public java.lang.Boolean getIncludeBinaryFiles()
        Retrieves the value of a flag that indicates whether the support data archive may include binary files.
        Returns:
        The value of a flag that indicates whether the support data archive may include binary files, or null if the property should not be specified when the task is created (in which case the server will use a default behavior of excluding binary files).
      • getIncludeExtensionSource

        @Nullable
        public java.lang.Boolean getIncludeExtensionSource()
        Retrieves the value of a flag that indicates whether the support data archive should include source code (if available) for any third-party extensions installed in the server.
        Returns:
        The value of a flag that indicates whether the support data archive should include source code (if available) for any third-party extensions installed in the server, or null if the property should not be specified when the task is created (in which case the server will use a default behavior of excluding extension source code).
      • getUseSequentialMode

        @Nullable
        public java.lang.Boolean getUseSequentialMode()
        Retrieves the value of a flag that indicates whether the server should collect items for the support data archive in sequential mode rather than in parallel. Collecting data in sequential mode may reduce the amount of memory consumed during the collection process, but it will take longer to complete.
        Returns:
        The value of a flag that indicates whether the server should collect items for the support data archive in sequential mode rather than in parallel, or null if the property should not be specified when the task is created (in which case the server will default to capturing data in parallel).
      • getSecurityLevel

        @Nullable
        public CollectSupportDataSecurityLevel getSecurityLevel()
        Retrieves the security level that should be used to indicate which data should be obscured, redacted, or omitted from the support data archive.
        Returns:
        The security level that should be used when creating the support data archive, or null if the property should not be specified when the task is created (in which case the server will use a default security level).
      • getReportCount

        @Nullable
        public java.lang.Integer getReportCount()
        Retrieves the number of intervals that should be captured from tools that use interval-based sampling (e.g., vmstat, iostat, mpstat, etc.).
        Returns:
        The number of intervals that should be captured from tools that use interval-based sampling, or null if the property should not be specified when the task is created (in which case the server will use a default report count).
      • getReportIntervalSeconds

        @Nullable
        public java.lang.Integer getReportIntervalSeconds()
        Retrieves the interval duration in seconds that should be used for tools that use interval-based sampling (e.g., vmstat, iostat, mpstat, etc.).
        Returns:
        The interval duration in seconds that should be used for tools that use interval-based sampling, or null if the property should not be specified when the task is created (in which case the server will use a default report interval).
      • getJStackCount

        @Nullable
        public java.lang.Integer getJStackCount()
        Retrieves the number of times that the jstack utility should be invoked to obtain stack traces from all threads in the server.
        Returns:
        The number of times that the jstack utility should be invoked to obtain stack traces from all threads in the server, or null if the property should not be specified when the task is created (in which case the server will use a default count).
      • getLogStartTime

        @Nullable
        public java.util.Date getLogStartTime()
        Retrieves the start time for the range of log messages to include in the support data archive.
        Returns:
        The start time for the range of log messages to include in the support data archive, or null if no log start time has been specified.
      • getLogEndTime

        @Nullable
        public java.util.Date getLogEndTime()
        Retrieves the end time for the range of log messages to include in the support data archive.
        Returns:
        The end time for the range of log messages to include in the support data archive, or null if no log end time has been specified.
      • getLogDuration

        @Nullable
        public java.lang.String getLogDuration()
        Retrieves a string representation of the duration (up until the time that the collect support data task is invoked) of log content that should be included in the support data archive.
        Returns:
        A string representation of the duration of log content that should be included in the support data archive, or null if the property should not be specified when the task is created (in which case the server will use a default behavior for selecting the amount of log content to include).
      • getLogFileHeadCollectionSizeKB

        @Nullable
        public java.lang.Integer getLogFileHeadCollectionSizeKB()
        Retrieves the amount of data in kilobytes to capture from the beginning of each log file that should be included in the support data archive.
        Returns:
        The amount of data in kilobytes to capture from the beginning of each log file that should be included in the support data archive, or null if the property should not be specified when the task is created (in which case the server will determine an appropriate amount of log content to include).
      • getLogFileTailCollectionSizeKB

        @Nullable
        public java.lang.Integer getLogFileTailCollectionSizeKB()
        Retrieves the amount of data in kilobytes to capture from the end of each log file that should be included in the support data archive.
        Returns:
        The amount of data in kilobytes to capture from the end of each log file that should be included in the support data archive, or null if the property should not be specified when the task is created (in which case the server will determine an appropriate amount of log content to include).
      • getLogDurationMillis

        @Nullable
        public java.lang.Long getLogDurationMillis()
                                            throws TaskException
        Retrieves a parsed value of the log duration in milliseconds.
        Returns:
        A parsed value of the log duration in milliseconds or null if no log duration is set.
        Throws:
        TaskException - If the log duration value cannot be parsed as a valid duration.
      • getComment

        @Nullable
        public java.lang.String getComment()
        Retrieves an additional comment that should be included in the support data archive.
        Returns:
        An additional comment that should be included in the support data archive, or null if no comment should be included.
      • getRetainPreviousSupportDataArchiveCount

        @Nullable
        public java.lang.Integer getRetainPreviousSupportDataArchiveCount()
        Retrieves the minimum number of existing support data archives that should be retained.
        Returns:
        The minimum number of existing support data archives that should be retained, or null if there is no minimum retain count.
      • getRetainPreviousSupportDataArchiveAge

        @Nullable
        public java.lang.String getRetainPreviousSupportDataArchiveAge()
        Retrieves the minimum age of existing support data archives that should be retained.
        Returns:
        The minimum age of existing support data archives that should be retained, or null if there is no minimum retain age.
      • getRetainPreviousSupportDataArchiveAgeMillis

        @Nullable
        public java.lang.Long getRetainPreviousSupportDataArchiveAgeMillis()
                                                                    throws TaskException
        Retrieves a parsed value of the retain previous support data archive age in milliseconds.
        Returns:
        A parsed value of the retain previous support data archive age in milliseconds or null if no retain age is set.
        Throws:
        TaskException - If the retain age value cannot be parsed as a valid duration.
      • getAdditionalObjectClasses

        @NotNull
        protected java.util.List<java.lang.String> getAdditionalObjectClasses()
        Retrieves a list of the additional object classes (other than the base "top" and "ds-task" classes) that should be included when creating new task entries of this type.
        Overrides:
        getAdditionalObjectClasses in class Task
        Returns:
        A list of the additional object classes that should be included in new task entries of this type, or an empty list if there do not need to be any additional classes.
      • getAdditionalAttributes

        @NotNull
        protected java.util.List<AttributegetAdditionalAttributes()
        Retrieves a list of the additional attributes (other than attributes common to all task types) that should be included when creating new task entries of this type.
        Overrides:
        getAdditionalAttributes in class Task
        Returns:
        A list of the additional attributes that should be included in new task entries of this type, or an empty list if there do not need to be any additional attributes.
      • getTaskSpecificProperties

        @NotNull
        public java.util.List<TaskPropertygetTaskSpecificProperties()
        Retrieves a list of task-specific properties that may be provided when scheduling a task of this type. This method should be overridden by subclasses in order to provide an appropriate set of properties.
        Overrides:
        getTaskSpecificProperties in class Task
        Returns:
        A list of task-specific properties that may be provided when scheduling a task of this type.
      • getTaskPropertyValues

        @NotNull
        public java.util.Map<TaskProperty,​java.util.List<java.lang.Object>> getTaskPropertyValues()
        Retrieves the values of the task properties for this task. The data type of the values will vary based on the data type of the corresponding task property and may be one of the following types: Boolean, Date, Long, or String. Task properties which do not have any values will be included in the map with an empty value list.

        Note that subclasses which have additional task properties should override this method and return a map which contains both the property values from this class (obtained from super.getTaskPropertyValues() and the values of their own task-specific properties.
        Overrides:
        getTaskPropertyValues in class Task
        Returns:
        A map of the task property values for this task.