IDataCollectorSet interface

Manages the configuration information that is common to all data collector objects in the set; adds and removes data collectors from the set; and starts data collection. This is the primary PLA interface that you use.

To get this interface, call the CoCreateInstance function, passing __uuidof(DataCollectorSet) as the class identifier and __uuidof(IDataCollectorSet) as the interface identifier.

Members

The IDataCollectorSet interface inherits from the IDispatch interface. IDataCollectorSet also has these types of members:

Methods

The IDataCollectorSet interface has these methods.

MethodDescription
Commit

Saves, updates, or validates the data collector set. You can also use this method to flush a trace session.

Delete

Deletes the persisted copy of the data collector set if the set is not running.

GetValue

Retrieves a user-defined value.

Query

Retrieves the specified data collector set from the hard disk and overwrites this object with the contents of the set.

SetCredentials

Specifies the user account under which the data collector set runs.

SetValue

Sets a user-defined value.

SetXml

Sets the property values of those properties included in the XML.

Start

Manually starts the data collector set.

Stop

Manually stops the data collector set.

 

Properties

The IDataCollectorSet interface has these properties.

PropertyDescription

DataCollectors

Retrieves the list of data collectors in this set.

DataManager

Retrieves the data manager associated with this data collector set.

Description

Retrieves or sets the description of the data collector set.

DescriptionUnresolved

Retrieves the description of the data collector set in its original form.

DisplayName

Retrieves or sets the display name of the data collector set.

DisplayNameUnresolved

Retrieves the display name of the data collector set in its original form.

Duration

Retrieves and sets the duration that the data collector set runs.

Keywords

Retrieves or sets keywords that describe the data collector set.

LatestOutputLocation

Retrieves or sets the fully decorated folder name that PLA used the last time logs were written.

Name

Retrieves the unique name used to identify the data collector set.

OutputLocation

Retrieves the decorated folder name if PLA were to create it now.

RootPath

Retrieves or sets the base path where the subdirectories are created.

Schedules

Retrieves the list of schedules that determine when the data collector set runs.

SchedulesEnabled

Retrieves or sets a value that indicates whether the schedules are enabled.

Security

Retrieves or sets access control information that determines who can access this data collector set.

Segment

Retrieves or sets a value that indicates whether PLA creates new logs if the maximum size or segment duration is reached before the data collector set is stopped.

SegmentMaxDuration

Retrieves or sets the duration that the data collector set can run before it begins writing to new log files.

SegmentMaxSize

Retrieves or sets the maximum size of any log file in the data collector set.

SerialNumber

Retrieves or sets the number of times that this data collector set has been started, including segments.

Server

Retrieves the name of the server where the data collector set is run.

Status

Retrieves the status of the data collector set.

StopOnCompletion

Retrieves or sets a value that determines whether the data collector set stops when all the data collectors in the set are in a completed state.

Subdirectory

Retrieves or sets a base subdirectory of the root path where the next instance of the data collector set will write its logs.

SubdirectoryFormat

Retrieves or sets flags that describe how to decorate the subdirectory name.

SubdirectoryFormatPattern

Retrieves or sets a format pattern to use when decorating the folder name.

Task

Retrieves or sets the name of a Task Scheduler job to start each time the data collector set stops, including between segments.

TaskArguments

Retrieves or sets the command-line arguments to pass to the Task Scheduler job specified in the IDataCollectorSet::Task property.

TaskRunAsSelf

Retrieves or sets a value that determines whether the task runs as the data collector set user or as the user specified in the task.

TaskUserTextArguments

Retrieves or sets the command-line arguments that are substituted for the {usertext} substitution variable in the IDataCollectorSet::TaskArguments property.

UserAccount

Retrieves the user account under which the data collector set will run.

Xml

Retrieves an XML string that describes the values of the data collector set properties, including those of the data collectors contained in the set.

 

Remarks

To create the object from a script, use the "Pla.DataCollectorSet" program identifier.

To retrieve an existing data collector set, create an instance of the data collector set object and then call the IDataCollectorSet::Query method to query the properties of a previously persisted data collector set.

To create a set, create an instance of the data collector set object and set the properties as appropriate. You can set the properties individually or pass XML that contains the property values to the IDataCollectorSet::SetXml method.

To add new data collector objects to the set, retrieve the collection from the IDataCollectorSet::DataCollectors property. To persist the data collector set, call the IDataCollectorSet::Commit method.

You can start the data collectors manually using the IDataCollectorSet::Start method or automatically using the IDataCollectorSet::Schedules property. Alternatively, an alert can trigger a collection to run if the IAlertDataCollector::TriggerDataCollectorSet property is set.

If you want to manage the collected data, retrieve an IDataManager interface from the IDataCollectorSet::DataManager property.

The following example shows the XML elements for a data collector set. For details, see the corresponding property.


<DataCollectorSet>
    <DataManager>
        <Enabled/>              <!-- 0 (false), nonzero (true) -->
        <CheckBeforeRunning/>   <!-- 0 (false), nonzero (true) -->
        <MinFreeDisk/>
        <MaxSize/>
        <MaxFolderCount/>
        <ResourcePolicy/>
        <ReportFileName/>
        <RuleTargetFileName/>
        <EventsFileName/>
        <FolderAction>          <!-- Include a <FolderAction> element for -->
            <Actions/>          <!-- each action to take. -->
            <Age/>
            <SendCabTo/>
            <Size/>
        </FolderAction>
    </DataManager>
    <Description/>
    <DescriptionUnresolved/>    <!-- Output only -->
    <DisplayName/>
    <DisplayNameUnresolved/>    <!-- Output only -->
    <Duration/>  
    <Keyword/>                  <!-- Specify for each keyword -->
    <LatestOutputLocation/>     
    <Name/>                     <!-- Output only -->
    <OutputLocation/>           <!-- Output only -->
    <RootPath/>
    <Segment/>
    <SegmentMaxDuration/> 
    <SegmentMaxSize/> 
    <SerialNumber/>
    <Server/>                   <!-- Output only -->
    <Status/>                   <!-- Output only -->
    <Subdirectory/>
    <SubdirectoryFormat/>
    <SubdirectoryFormatPattern/>
    <Task/>
    <TaskArguments/>
    <TaskRunAsSelf/>            <!-- 0 (false), -1 (true) -->
    <TaskUserTextArguments/>
    <Schedule>
        <Days/>
        <EndDate/>              <!-- mm/dd/yyyy -->
        <StartDate/>            <!-- mm/dd/yyyy -->
        <StartTime/>            <!-- hh:mm:ss (use 24-hour clock) -->
    </Schedule>
    <SchedulesEnabled/>         <!-- 0 (false), nonzero (true) -->
    <Security/>                 <!-- Security Descriptor Definition Language -->
    <StopOnCompletion/>         <!-- 0 (false), nonzero (true) -->
    <UserAccount/>              <!-- Output only. Set using SetCredentials --></DataCollectorSet>

If you call IDataCollectorSet::Xml to retrieve the XML for a set and the set includes data collectors, the XML will also contain the XML elements for each data collector in the set.

To use the data collector set elements to initialize the property values of a data collector set, call the SetXml method. The contents of the XML will overwrite the existing contents of the set. The following shows how to include the elements for the alert data collector.


<DataCollectorSet>

    <!-- Data collector set elements go here. -->

    <AlertDataCollector>
        <Alert/>  <!-- Specify an <Alert> element for each alert -->
        <EventLog/>
        <SampleInterval/>
        <Task/>
        <TaskArguments/>
        <TaskRunAsSelf/>            <!-- 0 (false), nonzero (true) -->
        <TaskUserTextArguments/>
        <TriggerDataCollectorSet/>

        <!-- Data collector elements go here. -->
    </AlertDataCollector>
</DataCollectorSet>

You can specify only the elements for the properties that you want to set. If you do not specify a property, PLA provides a default value. When you retrieve the XML for the set, the XML includes all elements, including those from the data collectors contained in the set (for details on data collector properties, see each data collector interface). However, the schedule and folder action elements are not included if they are not defined for the set.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Pla.h

DLL

Pla.dll

See also

IDataCollector

 

 

Show: