Export (0) Print
Expand All
Expand Minimize

EventWriteEx function

Use this function to write an event.

Syntax


ULONG EventWriteEx(
  _In_      REGHANDLE RegHandle,
  _In_      PCEVENT_DESCRIPTOR EventDescriptor,
  _In_      ULONG64 Filter,
  _In_      ULONG Flags,
  _In_opt_  LPCGUID ActivityId,
  _In_      LPCGUID RelatedActivityId,
  _In_      ULONG UserDataCount,
  _In_opt_  PEVENT_DATA_DESCRIPTOR UserData
);

Parameters

RegHandle [in]

Registration handle of the provider. The handle comes from EventRegister.

EventDescriptor [in]

A descriptor that contains the metadata that identifies the event to write. For details, see EVENT_DESCRIPTOR.

Filter [in]

The instance identifiers that identify the session to which the event will not written. Use a bitwise OR to specify multiple identifiers. Set to zero if you do not support filters or if the event is being written to all sessions (no filters failed). For information on getting the identifier for a session, see the FilterData parameter of your EnableCallback callback.

Flags [in]

Reserved. Must be zero.

ActivityId [in, optional]

GUID that uniquely identifies this activity. If NULL, ETW gets the identifier from the thread local storage. For details on getting this identifier, see EventActivityIdControl.

RelatedActivityId [in]

Activity identifier from the previous component. Use this parameter to link your component's events to the previous component's events. To get the activity identifier that was set for the previous component, see the descriptions for the ControlCode parameter of the EventActivityIdControl function.

UserDataCount [in]

Number of EVENT_DATA_DESCRIPTOR structures in UserData. The maximum number is 128.

UserData [in, optional]

The event data to write. Allocate a block of memory that contains one or more EVENT_DATA_DESCRIPTOR structures. Set this parameter to NULL if UserDataCount is zero. The data must be in the order specified in the manifest.

Return value

Returns ERROR_SUCCESS if successful or one of the following values on error.

Return codeDescription
ERROR_INVALID_PARAMETER

One or more of the parameters is not valid.

ERROR_INVALID_HANDLE

The registration handle of the provider is not valid.

ERROR_ARITHMETIC_OVERFLOW

The event size is larger than the allowed maximum (64k - header).

ERROR_MORE_DATA

The session buffer size is too small for the event.

ERROR_NOT_ENOUGH_MEMORY

Occurs when filled buffers are trying to flush to disk, but disk IOs are not happening fast enough. This happens when the disk is slow and event traffic is heavy. Eventually, there are no more free (empty) buffers and the event is dropped.

STATUS_LOG_FILE_FULL

The real-time playback file is full. Events are not logged to the session until a real-time consumer consumes the events from the playback file. Do not stop logging events based on this error code.

 

Remarks

Event data written with this function requires a manifest. Since the manifest is embedded in the provider, the provider must be available for a consumer to consume the data written by the provider.

Use the ActivityId and RelatedActivityId parameters when several components want to relate their events in an end-to-end tracing scenario. For example, components A, B, and C perform work on a related activity and want to link their events so that a consumer can consume all the events related to that activity. ETW uses thread local storage to make available to the next component the previous component's activity identifier. The component retrieves from the local storage the previous component's identifier and sets the related activity identifier to it. The consumer can then use the related activity identifier to walk the chain of the events from one component to the next.

If each component defined their own activity identifier, the components can make the following calls to link the events:

  • Call the EventActivityIdControl function using the EVENT_ACTIVITY_CTRL_GET_SET_ID control code. The function uses your identifier to set the activity identifier in the thread local storage and returns the activity identifier for the previous component, if set.
  • Set the RelatedActivityId parameter of this function to the ActivityId value that the EventActivityIdControl function returned. Note that for the first component, the related identifier will be all zeros (GUID_NULL).
  • Set the ActivityId of this function to NULL to use the activity identifier that you set in thread local storage.

A provider can define filters that a session uses to filter events based on event data. With level and keywords, ETW determines whether the event is written to the session but with filters, the provider uses the filter data to determine whether it writes the event to the session. For example, if your provider generates process events, you could define a data filter that filters process events based on the process identifier. If the identifier of the process did not match the identifier that the session passed as filter data, you would set (perform a bitwise OR) the Filter parameter to the session's instance identifier to prevent the event from being written to that session.

Examples

For an example that uses EventWrite, see Writing Manifest-based Events.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Evntprov.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

EventWrite
EventWriteString
EventWriteTransfer

 

 

Community Additions

ADD
Show:
© 2015 Microsoft