#etw #tracelogging #trace #logging #windows

no-std tracelogging_dynamic

TraceLoggingDynamic for Rust

1 unstable release

Uses new Rust 2021

0.1.0 Sep 13, 2022

#149 in Debugging

MIT license

210KB
2.5K SLoC

TraceLogging Dynamic for Rust

The tracelogging_dynamic crate provides a way to log TraceLogging events when the event schema is not known at compile-time.

This implementation is less user-friendly and has higher runtime costs than the implementation in the tracelogging crate. This implementation should only be used when the set of events to log cannot be deteremined ahead of time. For example, this might be useful when implementing a middle-layer library that provides generic logging facilities to a dynamic upper layer.

use tracelogging_dynamic as tld;

// Pinning is required because the register() method sets up a callback with ETW.
let mut provider = Box::pin(tld::Provider::new());

// Register the provider with name "MyCompany.MyComponent". If you don't register (or
// if register fails) then enabled() will always return false and write() will be a
// no-op.
unsafe {
    provider.as_mut().register("MyCompany.MyComponent", &tld::Provider::options());
}

// If provider is not enabled for a given level + keyword, the write() call will do
// nothing. Check enabled(level, keyword) before building the event so we don't waste
// time on an event that nobody will receive.
let my_event_level = tld::Level::Verbose; // Severity level.
let my_event_keyword = 0x123; // User-defined category bits.
if provider.enabled(my_event_level, my_event_keyword) {
    let field1_value = "FieldValue";
    let field2_value = b'A';
    // Create and write an event with two fields:
    tld::EventBuilder::new()
        // Most events specify 0 for event tag.
        .reset("MyEventName", my_event_level, my_event_keyword, 0)
        // Most fields use Default for event format and 0 for field tag.
        .add_str8("FieldName1", field1_value, tld::OutType::Default, 0)
        .add_u8("FieldName2", field2_value, tld::OutType::String, 0)
        // If activity_id is None, event uses the current thread's activity.
        // If related_id is None, event will not have a related activity.
        .write(&provider, None, None);
}

Configuration

This crate supports the following configurable features:

  • etw: Use Windows ETW APIs to log events. If not enabled, all logging operations will be no-ops. Enabled by default.

In addition, this crate will log events only if compiled for a Windows operating system. If compiled for a non-Windows operating system, all logging operations will be no-ops.

Dependencies