IDataCollectorSet interface (pla.h)
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.
Inheritance
The IDataCollectorSet interface inherits from the IDispatch interface. IDataCollectorSet also has these types of members:
Methods
The IDataCollectorSet interface has these methods.
| IDataCollectorSet::Commit Saves, updates, or validates the data collector set. You can also use this method to flush a trace session. |
| IDataCollectorSet::Delete Deletes the persisted copy of the data collector set if the set is not running. |
| IDataCollectorSet::get_DataCollectors Retrieves the list of data collectors in this set. |
| IDataCollectorSet::get_DataManager Retrieves the data manager associated with this data collector set. |
| IDataCollectorSet::get_Description Retrieves or sets the description of the data collector set. The description will be added to all output files as metadata and inserted into Performance Data Helper logs as a comment. (Get) |
| IDataCollectorSet::get_DescriptionUnresolved Retrieves the description of the data collector set in its original form. |
| IDataCollectorSet::get_DisplayName Retrieves or sets the display name of the data collector set. (Get) |
| IDataCollectorSet::get_DisplayNameUnresolved Retrieves the display name of the data collector set in its original form. |
| IDataCollectorSet::get_Duration Retrieves and sets the duration that the data collector set runs. (Get) |
| IDataCollectorSet::get_Keywords Retrieves or sets keywords that describe the data collector set. The list of keywords is added to the output files as metadata. (Get) |
| IDataCollectorSet::get_LatestOutputLocation Retrieves or sets the fully decorated folder name that PLA used the last time logs were written. (IDataCollectorSet.get_LatestOutputLocation) |
| IDataCollectorSet::get_Name Retrieves the unique name used to identify the data collector set. |
| IDataCollectorSet::get_OutputLocation Retrieves the decorated folder name if PLA were to create it now. |
| IDataCollectorSet::get_RootPath Retrieves or sets the base path where the subdirectories are created. (Get) |
| IDataCollectorSet::get_Schedules Retrieves the list of schedules that determine when the data collector set runs. |
| IDataCollectorSet::get_SchedulesEnabled Retrieves or sets a value that indicates whether the schedules are enabled. (Get) |
| IDataCollectorSet::get_Security Retrieves or sets access control information that determines who can access this data collector set. (Get) |
| IDataCollectorSet::get_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. (Get) |
| IDataCollectorSet::get_SegmentMaxDuration Retrieves or sets the duration that the data collector set can run before it begins writing to new log files. (Get) |
| IDataCollectorSet::get_SegmentMaxSize Retrieves or sets the maximum size of any log file in the data collector set. (Get) |
| IDataCollectorSet::get_SerialNumber Retrieves or sets the number of times that this data collector set has been started, including segments. (Get) |
| IDataCollectorSet::get_Server Retrieves the name of the server where the data collector set is run. |
| IDataCollectorSet::get_Status Retrieves the status of the data collector set. |
| IDataCollectorSet::get_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. (Get) |
| IDataCollectorSet::get_Subdirectory Retrieves or sets a base subdirectory of the root path where the next instance of the data collector set will write its logs. (Get) |
| IDataCollectorSet::get_SubdirectoryFormat Retrieves or sets flags that describe how to decorate the subdirectory name. (Get) |
| IDataCollectorSet::get_SubdirectoryFormatPattern Retrieves or sets a format pattern to use when decorating the folder name. (Get) |
| IDataCollectorSet::get_Task Retrieves or sets the name of a Task Scheduler job to start each time the data collector set stops, including between segments. (Get) |
| IDataCollectorSet::get_TaskArguments Retrieves or sets the command-line arguments to pass to the Task Scheduler job specified in the IDataCollectorSet::Task property. (Get) |
| IDataCollectorSet::get_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. (IDataCollectorSet.get_TaskRunAsSelf) |
| IDataCollectorSet::get_TaskUserTextArguments Retrieves or sets the command-line arguments that are substituted for the {usertext} substitution variable in the IDataCollectorSet::TaskArguments property. (Get) |
| IDataCollectorSet::get_UserAccount Retrieves the user account under which the data collector set will run. |
| IDataCollectorSet::get_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. |
| IDataCollectorSet::GetValue Retrieves a user-defined value. |
| IDataCollectorSet::put_Description Retrieves or sets the description of the data collector set. The description will be added to all output files as metadata and inserted into Performance Data Helper logs as a comment. (Put) |
| IDataCollectorSet::put_DisplayName Retrieves or sets the display name of the data collector set. (Put) |
| IDataCollectorSet::put_Duration Retrieves and sets the duration that the data collector set runs. (Put) |
| IDataCollectorSet::put_Keywords Retrieves or sets keywords that describe the data collector set. The list of keywords is added to the output files as metadata. (Put) |
| IDataCollectorSet::put_LatestOutputLocation Retrieves or sets the fully decorated folder name that PLA used the last time logs were written. (IDataCollectorSet.put_LatestOutputLocation) |
| IDataCollectorSet::put_RootPath Retrieves or sets the base path where the subdirectories are created. (Put) |
| IDataCollectorSet::put_SchedulesEnabled Retrieves or sets a value that indicates whether the schedules are enabled. (Put) |
| IDataCollectorSet::put_Security Retrieves or sets access control information that determines who can access this data collector set. (Put) |
| IDataCollectorSet::put_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. (Put) |
| IDataCollectorSet::put_SegmentMaxDuration Retrieves or sets the duration that the data collector set can run before it begins writing to new log files. (Put) |
| IDataCollectorSet::put_SegmentMaxSize Retrieves or sets the maximum size of any log file in the data collector set. (Put) |
| IDataCollectorSet::put_SerialNumber Retrieves or sets the number of times that this data collector set has been started, including segments. (Put) |
| IDataCollectorSet::put_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. (Put) |
| IDataCollectorSet::put_Subdirectory Retrieves or sets a base subdirectory of the root path where the next instance of the data collector set will write its logs. (Put) |
| IDataCollectorSet::put_SubdirectoryFormat Retrieves or sets flags that describe how to decorate the subdirectory name. (Put) |
| IDataCollectorSet::put_SubdirectoryFormatPattern Retrieves or sets a format pattern to use when decorating the folder name. (Put) |
| IDataCollectorSet::put_Task Retrieves or sets the name of a Task Scheduler job to start each time the data collector set stops, including between segments. (Put) |
| IDataCollectorSet::put_TaskArguments Retrieves or sets the command-line arguments to pass to the Task Scheduler job specified in the IDataCollectorSet::Task property. (Put) |
| IDataCollectorSet::put_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. (IDataCollectorSet.put_TaskRunAsSelf) |
| IDataCollectorSet::put_TaskUserTextArguments Retrieves or sets the command-line arguments that are substituted for the {usertext} substitution variable in the IDataCollectorSet::TaskArguments property. (Put) |
| IDataCollectorSet::Query Retrieves the specified data collector set. |
| IDataCollectorSet::SetCredentials Specifies the user account under which the data collector set runs. |
| IDataCollectorSet::SetValue Sets a user-defined value. |
| IDataCollectorSet::SetXml Sets the property values of those properties included in the XML. (IDataCollectorSet.SetXml) |
| IDataCollectorSet::Start Manually starts the data collector set. |
| IDataCollectorSet::Stop Manually stops the data collector 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
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | pla.h |