Struct tracelogging::Provider
source · [−]pub struct Provider { /* private fields */ }
Expand description
A connection to ETW for writing TraceLogging (manifest-free) events.
Overview
- Use
define_provider!
to create a static provider variable. - Call
Provider::register()
during component initialization to open the connection to ETW. - Use
write_event!
as needed to write events. - Call
Provider::unregister()
during component cleanup to close the connection to ETW.
Implementations
sourceimpl Provider
impl Provider
sourcepub fn current_thread_activity_id() -> Guid
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.
sourcepub fn set_current_thread_activity_id(value: &Guid) -> Guid
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.
sourcepub fn create_activity_id() -> Guid
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.
sourcepub fn guid_from_name(name: &str) -> Guid
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));
sourcepub const fn raw_meta(&self) -> &[u8]
pub const fn raw_meta(&self) -> &[u8]
Advanced: Returns this provider’s encoded metadata bytes.
sourcepub const fn enabled(&self, level: Level, keyword: u64) -> bool
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!
.
sourcepub fn unregister(&self) -> u32
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
orunregister
method must not occur at the same time as a call to the provider’sregister
orunregister
method on any other thread. Verified at runtime, failure = panic.
sourcepub unsafe fn register(&self) -> u32
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
orunregister
method must not occur at the same time as a call to the provider’sregister
orunregister
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 andunregister
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 duringDLL_PROCESS_DETACH
.
sourcepub unsafe fn register_with_callback(
&self,
callback_fn: ProviderEnableCallback,
callback_context: usize
) -> u32
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
orunregister
method must not occur at the same time as a call to the provider’sregister
orunregister
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 andunregister
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 duringDLL_PROCESS_DETACH
.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Provider
impl Send for Provider
impl Sync for Provider
impl !Unpin for Provider
impl UnwindSafe for Provider
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more