Struct tracelogging::Provider

pub struct Provider { /* private fields */ }

A connection to ETW for writing TraceLogging (manifest-free) events.

Overview

1. Use define_provider! to create a static provider variable.
2. Call Provider::register() during component initialization to open the connection to ETW.
3. Use write_event! as needed to write events.
4. Call Provider::unregister() during component cleanup to close the connection to ETW.

Implementations

impl Provider

pub fn current_thread_activity_id() -> Guid

Returns the current thread’s thread-local activity id. (Calls EventActivityIdControl with control code EVENT_ACTIVITY_CTRL_GET_ID.)

The thread-local activity id will be used if write_event! is called with no activity_id option.

pub fn set_current_thread_activity_id(value: &Guid) -> Guid

Sets the current thread’s thread-local activity id. Returns the previous value. (Calls EventActivityIdControl with control code EVENT_ACTIVITY_CTRL_GET_SET_ID.)

The thread-local activity id will be used if write_event! is called with no activity_id option.

Important: thread-local activity id should follow scoping rules. If you set the thread-local activity id in a scope, you should restore the previous value before exiting the scope.

pub fn create_activity_id() -> Guid

Generates and returns a new 128-bit value suitable for use as an activity id. (Calls EventActivityIdControl with control code EVENT_ACTIVITY_CREATE_ID.)

The returned value is not a true GUID/UUID since it is not globally-unique. The returned value is locally-unique: it is guaranteed to be different from all other values generated by create_activity_id() on the current machine in the current boot session.

Activity ids need to be unique within the trace but do not need to be globally-unique, so your activity ids can use either a real GUID/UUID or a locally-unique id generated by create_activity_id(). Use create_activity_id() for locally-unique activity ids or use [Guid::new] for globally-unique activity ids.

pub fn guid_from_name(name: &str) -> Guid

Returns a GUID generated from a case-insensitive hash of the specified trace provider name. The hash uses the same algorithm as many other ETW tools and APIs. Given the same name, it will always generate the same GUID. (Same as Guid::from_name.)

The result can (and usually should) be used as the provider id.

Note: Do not use guid_from_name to generate activity ids.

use tracelogging as tlg;
assert_eq!(
   tlg::Provider::guid_from_name("MyProvider"),
   tlg::Guid::from_u128(&0xb3864c38_4273_58c5_545b_8b3608343471));

pub const fn raw_meta(&self) -> &[u8]

Advanced: Returns this provider’s encoded metadata bytes.

pub fn name(&self) -> &str

Returns this provider’s name.

pub const fn id(&self) -> &Guid

Returns this provider’s id (GUID).

pub const fn enabled(&self, level: Level, keyword: u64) -> bool

Returns true if any ETW logging session is listening to this provider for events with the specified level and keyword.

Note: write_event! already checks enabled(). You only need to make your own call to enabled() if you want to skip something other than write_event!.

pub fn unregister(&self) -> u32

If this provider is not registered, does nothing and returns 0. Otherwise, unregisters the provider.

Returns 0 for success or a Win32 error from EventUnregister for failure. The return value is for diagnostic purposes only and should generally be ignored in retail builds.

Preconditions

• For a given provider object, a call on one thread to the provider’s register or unregister method must not occur at the same time as a call to the provider’s register or unregister method on any other thread. Verified at runtime, failure = panic.

pub unsafe fn register(&self) -> u32

Register the provider.

Preconditions

• Provider must not already be registered. Verified at runtime, failure = panic.
• For a given provider object, a call on one thread to the provider’s register or unregister method must not occur at the same time as a call to the provider’s register or unregister method on any other thread. Verified at runtime, failure = panic.

Safety

• If creating a DLL or creating a provider that might run as part of a DLL, all registered providers must be unregistered before the DLL unloads.

  If a provider variable is registered by a DLL and the DLL unloads while the provider is still registered, the process may subsequently crash. This occurs because register enables an ETW callback into the calling DLL and unregister ensures that the callback is disabled. If the module unloads without disabling the callback, the process will crash the next time that ETW tries to invoke the callback.

  The provider cannot unregister itself because the provider is static and Rust does not drop static objects.

  You’ll typically register the provider during DLL_PROCESS_ATTACH and unregister during DLL_PROCESS_DETACH.

pub unsafe fn register_with_callback(
    &self,
    callback_fn: ProviderEnableCallback,
    callback_context: usize
) -> u32

Register the provider with a custom provider enable callback.

Preconditions

• Provider must not already be registered. Verified at runtime, failure = panic.
• For a given provider object, a call on one thread to the provider’s register or unregister method must not occur at the same time as a call to the provider’s register or unregister method on any other thread. Verified at runtime, failure = panic.

Safety

• If creating a DLL or creating a provider that might run as part of a DLL, all registered providers must be unregistered before the DLL unloads.

  If a provider variable is registered by a DLL and the DLL unloads while the provider is still registered, the process may subsequently crash. This occurs because register enables an ETW callback into the calling DLL and unregister ensures that the callback is disabled. If the module unloads without disabling the callback, the process will crash the next time that ETW tries to invoke the callback.

  The provider cannot unregister itself because the provider is static and Rust does not drop static objects.

  You’ll typically register the provider during DLL_PROCESS_ATTACH and unregister during DLL_PROCESS_DETACH.

Trait Implementations

impl Debug for Provider

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.