3.2.4.9 ITraceDataCollector

  • Article

The ITraceDataCollector interface is used to collect trace events from trace data providers.

The following properties MUST be implemented by the objects that implement the ITraceDataCollector interface.

Property

Read/write

Description

BufferSize

RW

Specifies the suggested buffer size, in kilobytes (KB), for each event tracing session buffer. The minimum value of the BufferSize property is 1 kilobyte. The maximum value is 1,024 KB. The default value is 8 KB.

BuffersLost

R

Specifies the number of buffers that could not be written to the log file. Any unsigned long is a valid value for this property. This property is only updated when the IDataCollectorSet::Start or IDataCollectorSet::Query methods are called.<22>

BuffersWritten

R

If running, specifies the number of buffers written to the log file. Any unsigned long is a valid value for this property.

ClockType

RW

Retrieves or sets the clock resolution to use when logging the time stamp for each event.

EventsLost

R

If running, specifies the number of events that were lost due to the lack of buffers to write to. Any unsigned long is a valid value for this property. This property is only updated when the IDataCollectorSet::Start or IDataCollectorSet::Query methods are called.<23>

ExtendedModes

RW

Retrieves or sets the log file modes that are not already set by this or other objects. The valid values for ExtendedModes are specified in section 2.2.9.

FlushTimer

RW

Specifies the time, in seconds, to wait before flushing buffers either to a log file or by delivering the buffers to an event consuming the application in real-time. If zero, the buffers are flushed as soon as they are filled. If nonzero, all buffers containing at least one event are flushed every time the number of seconds specified in this property elapse. Any unsigned long is a valid value for this property.

FreeBuffers

R

If running, specifies the number of buffers that are allocated but unused in the event tracing session's buffer pool. Any unsigned long is a valid value for the FreeBuffers property. This property is only updated when the IDataCollectorSet::Start or IDataCollectorSet::Query methods are called.<24>

Guid

RW

Specifies the PLA-UID of the session. If the supplied PLA-UID maps to a Security Descriptor, the session will run using that Security Descriptor. If no PLA-UID is supplied, a PLA-UID is generated. The PLA-UID is used for internal state tracking and does not correspond to any of the DCOM GUID subtypes. The valid range for this property is from 0000-0000-0000-0000-0000-0000-0000-0001 to FFFF-FFFF-FFFF-FFFF-FFFF-FFFF-FFFF-FFFF. Any PLA-UID other than 0000-0000-0000-0000-0000-0000-0000-0000 is a valid value for this property. The Guid in this context refers to the COM interface property which is used as a PLA-UID and does not comply with the semantics of GUID specified in [C706].

IsKernelTrace

R

Specifies whether this trace data collector includes kernel event trace data providers.

MaximumBuffers

RW

Specifies the suggested maximum number of buffers to allocate for the event tracing session's buffer pool. The value of the MaximumBuffers property has to be greater than or equal to the value of the MinimumBuffers property. Any unsigned long is a valid number of maximum buffers to suggest, but there is no guarantee that the suggestion will be followed. If the MaximumBuffers property is set to zero, it implies that the user is requesting that no more than zero buffers be used. As with any other possible value for the MaximumBuffers property, the suggestion might or might not be followed depending on whether the protocol implementation supports the requested value. No error will occur if the suggestion is not followed, unless MaximumBuffers was set to a lower value than MinimumBuffers, and it is not possible to detect if the suggestion is followed. The protocol does not provide any mechanism to discover the actual number of buffers being used.

MinimumBuffers

RW

Specifies the suggested minimum number of buffers to allocate for the event tracing session's buffer pool. The value of the MinimumBuffers property has to be less than or equal to the value of the MaximumBuffers property. Any unsigned long is a valid number of minimum buffers to suggest, but there is no guarantee that the suggestion will be followed. If the MinimumBuffers property is set to zero, it implies that the user is requesting that as few as zero buffers be used. As with any other possible value for the MinimumBuffers property, the suggestion might or might not be followed depending on whether the protocol implementation supports the requested value. No error will occur if the suggestion is not followed and it is not possible to detect if the suggestion is followed. The protocol does not provide any mechanism to discover the actual number of buffers being used.

NumberOfBuffers

RW

Specifies the suggested number of buffers to use for logging. Any unsigned long is a valid number of buffers to suggest, though there is no guarantee that the suggestion will be followed. If the NumberOfBuffers property is set to zero, it implies that the user is requesting that zero buffers be used. As with any other possible value for the NumberOfBuffers property, the suggestion might or might not be followed depending on whether the protocol implementation supports the requested value. No error will occur if the suggestion is not followed and it is not possible to detect if the suggestion is followed. The protocol does not provide any mechanism to discover the actual number of buffers being used.

PreallocateFile

RW

Specifies whether or not PLA MUST allocate the IDataCollectorSet::SegmentMaxSize on disk prior to the start of the trace data collector. However, if IDataCollectorSet::SegmentMaxSize is set to zero, then this property is ignored.

ProcessMode

RW

 Specifies whether or not a process-private logger MUST be used when the ITraceDataCollector is executing on the server. When events are logged using ETW, they are temporarily directed to buffers before they are written to a file or delivered to a real-time monitoring application. If this property is set to TRUE, then when the ITraceDataCollector begins executing on the server, the buffers will not be allocated from kernel memory, but from process memory. If this property is set to FALSE, then the buffers will be allocated from kernel memory.

If this property is set to TRUE, and the ITraceDataProviderCollection is empty or if any one of the specified trace providers is a kernel-mode provider, then the IDataCollectorSet::Start method will fail and an error code will be returned.

 The ITraceDataCollector specifies which providers to enable to this process-private logger. The buffers will be allocated in the process-space when the ITraceDataCollector begins executing. However, nothing will be written to these buffers unless the provider, which is also specified in the ITraceDataCollector, registers with ETW on the server and begins using the ETW API to log events. If this property is set to TRUE, and the provider registers multiple times with ETW from different processes, then there will be different trace files that are generated, one for each process. The file name is specified in the ITraceDataCollector, and to this file name is appended the extension, etl, and the process ID. If the process-private logger were running in a process with a process ID of 4, and the file name specified in the ITraceDataCollector is MyFile, then the file name that the events would be written to would be MyFile.etl_4. This is not the case if this property is set to FALSE, since the different provider instances from the different processes will all log to the buffers that are allocated in kernel memory, and these buffers are associated with a single trace file. As a result, no process ID is appended after the file extension etl.

 If a process-private logger is used, the process in which the buffers are allocated has the ability to modify the contents of the buffers. However, because the buffers are in the process, they are only visible to that process. While a process hosting a private session can edit the contents of a buffer after an event is written to it, only that process can view those buffers and consequently see those edits.

 If a process-private logger is not used, the buffers are allocated in the kernel. In this case, all processes can potentially view the contents of buffers, but no process has the ability to edit them.

RealTimeBuffersLost

R

If running, specifies the number of buffers that could not be delivered in real time to the consumer. RealTimeBuffers are lost when the backup file for storing events cannot be read or written to by the Event Tracing for infrastructure. In these situations, the buffers are not recoverable. It is not the case that the buffers are arriving late; instead, they are not arriving at all. Any unsigned long is a valid value for RealTimeBuffersLost. This property is only updated when the IDataCollectorSet::Start or IDataCollectorSet::Query methods are called.<25>

SessionId

R

 This property refers to the session identifier of the ETW trace session. When an ITraceDataCollector executes, it starts an ETW trace session; this session is marked with a numeric identifier. There can be up to 64 different sessions. Each of these sessions is marked by a different numeric SessionId, which is specified in this property. Therefore, this property can have the value of 0x0000000000000000 to 0x000000000000003F. The lower 2 bytes have the session IDs that are possible (0x0000 to 0x003F) while the upper 6 bytes MUST be ignored. This property is only updated when the IDataCollectorSet::Start or IDataCollectorSet::Query methods are called.<26>

SessionName

RW

Specifies the name of the session to be created to collect event trace data.

SessionThreadId

R

If running, specifies the ID of the thread performing the logging of the session. This property is only updated when the IDataCollectorSet::Start or IDataCollectorSet::Query methods are called.<27>

StreamMode

RW

Specifies the logging mode of the trace session.

TraceDataProviders

R (returned object is writable)

List of providers to be enabled for this trace session.

A data collector can be represented as an XML file, which can be used to serialize (using Xml (Get) 3.2.4.5.21) and deserialize (using SetXml 3.2.4.5.22) it. The format of the XML that defines a trace data collector is as follows (note that the full specification of the data collector set XML is in section 3.2.4.19): 

 <TraceDataCollector>
 <!-- elements for DataCollectorType -->    
 <BufferSize/>
     <BuffersLost/>  
     <BuffersWritten/>  
     <ClockType/>
     <EventsLost/>  
     <ExtendedMode/>
     <FlushTimer/>
     <FreeBuffers/>  
     <Guid/>
     <IsKernelTrace/>
     <MaximumBuffers/>
     <MinimumBuffers/>
     <PreallocateFile/>
     <ProcessMode/>
     <RealTimeBuffersLost/>  
     <SessionId/>  
     <SessionName/>
     <SessionThreadId/>  
     <StreamMode/>
     <TraceDataProvider>  <!-- Specify for each provider -->
         <AllKeywords/>
         <AnyKeywords/>
         <DisplayName/>
         <FilterData/>
         <FilterType/>
         <Guid/>
         <Level/>
         <Properties/>
     </TraceDataProvider>
 </TraceDataCollector>
  
 

The XML given above does not show the property elements inherited from IDataCollector that also need to be specified.

Opnums 35, 37, 41, 47, 62, 64, and 68 are not used across the network. These opnums are reserved and MUST NOT be reused by non-Microsoft implementations.

Methods in RPC Opnum Order

Method

Description

BufferSize (Get)

Retrieves the BufferSize property.

Opnum: 32

BufferSize (Put)

Sets the BufferSize property.

Opnum: 33

BuffersLost (Get)

Retrieves the BufferLost property.

Opnum: 34

Opnum35NotUsedOnWire

Reserved for local use.

Opnum: 35

BuffersWritten (Get)

Retrieves the BuffersWritten property.

Opnum: 36

Opnum37NotUsedOnWire

Reserved for local use.

Opnum: 37

ClockType (Get)

Retrieves the ClockType property.

Opnum: 38

ClockType (Put)

Sets the ClockType property.

Opnum: 39

EventsLost (Get)

Retrieves the EventsLost property.

Opnum: 40

Opnum41NotUsedOnWire

Reserved for local use.

Opnum: 41

ExtendedModes (Get)

Retrieves the ExtendedModes property.

Opnum: 42

ExtendedModes (Put)

Sets the ExtendedModes property.

Opnum: 43

FlushTimer (Get)

Retrieves the FlushTimer property.

Opnum: 44

FlushTimer (Put)

Sets the FlushTimer property.

Opnum: 45

FreeBuffers (Get)

Retrieves the FreeBuffers property.

Opnum: 46

Opnum47NotUsedOnWire

Reserved for local use.

Opnum: 47

Guid (Get)

Retrieves the Guid property.

Opnum: 48

Guid (Put)

Sets the Guid property.

Opnum: 49

IsKernelTrace (Get)

Retrieves the IsKernelTrace property.

Opnum: 50

MaximumBuffers (Get)

Retrieves the MaximumBuffers property.

Opnum: 51

MaximumBuffers (Put)

Sets the MaximumBuffers property.

Opnum: 52

MinimumBuffers (Get)

Retrieves the MinimumBuffers property.

Opnum: 53

MinimumBuffers (Put)

Sets the MinimumBuffers property.

Opnum: 54

NumberOfBuffers (Get)

Retrieves the NumberOfBuffers property.

Opnum: 55

NumberOfBuffers (Put)

Sets the NumberOfBuffers property.

Opnum: 56

PreallocateFile (Get)

Retrieves the PreallocateFile property.

Opnum: 57

PreallocateFile (Put)

Sets the PreallocateFile property.

Opnum: 58

ProcessMode (Get)

Retrieves the ProcessMode property.

Opnum: 59

ProcessMode (Put)

Sets the ProcessMode property.

Opnum: 60

RealTimeBuffersLost (Get)

Retrieves the RealTimeBuffersLost property.

Opnum: 61

Opnum62NotUsedOnWire

Reserved for local use.

Opnum: 62

SessionId (Get)

Retrieves the SessionId property.

Opnum: 63

Opnum64NotUsedOnWire

Reserved for local use.

Opnum: 64

SessionName (Get)

Retrieves the SessionName.

Opnum: 65

SessionName (Put)

Sets the SessionName

Opnum: 66

SessionThreadId (Get)

Retrieves the SessionThreadId property.

Opnum: 67

Opnum68NotUsedOnWire

Reserved for local use.

Opnum: 68

StreamMode (Get)

Retrieves the StreamMode property.

Opnum: 69

StreamMode (Put)

Retrieves the StreamMode property.

Opnum: 70

TraceDataProviders (Get)

Retrieves the TraceDataProviders property.

Opnum: 71

Opnums 0, 1, and 2 are reserved for the IUnknown interface. Opnums 3, 4, 5, and 6 are reserved for the IDispatch interface. Opnums 7–31 are used by IDataCollector.