ETW: Provider name to GUID resolution via `One-Collect` APIs

[swashtek]

Summary

Add public ETW helpers that resolve provider names to the GUIDs needed by EtwSession::enable_provider.

Today, enable_provider only accepts a Guid, so any consumer starting from a provider name has to implement its own name-to-GUID resolution. That logic differs by provider model:

• Manifest/classic MOF providers must be looked up from the OS provider database.
• TraceLogging / TraceLoggingDynamic providers use the EventSource name-hash convention and can be derived directly from the provider name.

This issue proposes exposing both resolution paths from one_collect so consumers can reuse a single implementation instead of duplicating TDH enumeration code and EventSource hashing logic.

Proposed API

#[derive(Clone, Copy)]
pub struct RegisteredProvider {
    pub guid: Guid,
    pub schema_source: u32,
}

pub fn registered_providers() -> anyhow::Result<HashMap<String, RegisteredProvider>>;

impl Guid {
    pub fn from_eventsource_name(name: &str) -> Guid;
}

pub fn guid_from_tracelogging_name(provider_name: &str) -> anyhow::Result<Guid>;

Scope

In scope

• Add registered_providers() in one_collect::etw to enumerate OS-registered ETW providers via TdhEnumerateProviders and return a case-insensitive name -> RegisteredProvider map.
• Add a public RegisteredProvider type carrying the resolved control guid and schema_source.
• Expose the EventSource/TraceLogging name-hash convention as Guid::from_eventsource_name.
• Add a Windows-facing guid_from_tracelogging_name wrapper in one_collect::etw.
• Refactor existing internal EventSource hashing code to delegate to the new shared implementation.

Out of scope

• A policy layer that decides when to use registered lookup vs. TraceLogging name-hash.
• Global caching across calls.
• Adding EtwSession::enable_provider_by_name.
• Explicit WPP support.

Design notes

• Place this surface in etw, next to EtwSession::enable_provider, rather than in etw::tdh.
• registered_providers() should do a single TdhEnumerateProviders pass and return an owned map.
• Include both manifest (SchemaSource == 0) and classic MOF (SchemaSource == 1) providers.
• Normalize map keys to lowercase for case-insensitive lookup.
• For duplicate provider names, keep the first entry.
• guid_from_tracelogging_name should cover self-describing TraceLogging / TraceLoggingDynamic names and direct {GUID} literals.
• Consumers should try registered_providers() first and only fall back to TraceLogging name-hash resolution when the name is absent from the registered map.

Implementation notes

• Reuse windows-sys TDH types/functions already used in the ETW codepath (TdhEnumerateProviders, PROVIDER_ENUMERATION_INFO, TRACE_PROVIDER_INFO).
• Use a properly aligned buffer for provider enumeration; do not reinterpret an under-aligned Vec<u8>.
• Preserve the existing .NET helper behavior, but route the shared EventSource hash path through Guid::from_eventsource_name so there is a single copy of the namespace/encoding logic.

Motivation

This is primarily needed by downstream ETW consumers that are configured by provider name rather than GUID. In particular, the otel-arrow ETW receiver currently carries both:

• its own TdhEnumerateProviders FFI for registered provider lookup, and
• a duplicate copy of the EventSource namespace/hash logic.

Publishing this API from one_collect would let downstream consumers delete that duplicated logic and keep only their configuration policy.

Acceptance criteria

• Consumers can resolve manifest/classic MOF provider names through registered_providers().
• Consumers can resolve TraceLogging / TraceLoggingDynamic names through Guid::from_eventsource_name / guid_from_tracelogging_name.
• Internal duplicated EventSource hash logic is consolidated behind the new public API.
• The API is released in a published one_collect version so downstream consumers can adopt it.

[brianrob]

Thanks for posting this detailed write-up, @swashtek. A few questions/comments:

• For registered_providers() would it make sense to use an enumeration pattern so that callers don't need load a full HashMap of the all registered providers? We do this in other places where we expect a larger data set (e.g. symbol resolution) to avoid having to pull the entire dataset into memory at once. This would also make it easier to stop enumerating once the desired data is found.
• Would you please clarify the difference between from_eventsource_name and guid_from_tracelogging_name?
• I tihnk that from_eventsource_name probably belongs as a function outside of the Guid struct since a Guid is a primitive and not specific to EventSources.

[swashtek]

Thanks for posting this detailed write-up, @swashtek. A few questions/comments:

• For registered_providers() would it make sense to use an enumeration pattern so that callers don't need load a full HashMap of the all registered providers? We do this in other places where we expect a larger data set (e.g. symbol resolution) to avoid having to pull the entire dataset into memory at once. This would also make it easier to stop enumerating once the desired data is found.
• Would you please clarify the difference between from_eventsource_name and guid_from_tracelogging_name?
• I tihnk that from_eventsource_name probably belongs as a function outside of the Guid struct since a Guid is a primitive and not specific to EventSources.

@brianrob Thank you for the feedback, this is super helpful feedback.

1. Good point on memory/early-stop behavior when all configured providers are found. I can switch it to a visitor to match for_each_ *.
   The caller can decide when to stop, so no HashMap has materialized.

pub fn for_each_registered_provider(
    f: impl FnMut(&str, RegisteredProvider) -> ControlFlow<()>,
) -> anyhow::Result<()>;

2. Guid::from_eventsource_name(name) -> Guid is a cross-platform, pure name-hash (uppercase → UTF-16BE → v5 over the fixed EventSource namespace). Infallible, no {GUID} handling.
   guid_from_tracelogging_name(name) -> Result<Guid> is a Windows/ETW-facing wrapper whose only additions are

   1. accept a literal {GUID} string and parse it verbatim
   2. otherwise delegate to from_eventsource_name. It returns Result solely because the {GUID} parse can fail.

   So, the wrapper is combination of pure hash, {GUID} - literal parsing and a home in the Windows etw module.
   The value-add is thin entry point for windows, which ties into your third point.

3. Agreed, it landed on Guid because it needed a cross-platform support, if it goes in etw, it will be windows specific.
   from_eventsource_name belongs outside of Guid and reachable from both Linux .Net helper and the Windows ETW wrapper.
   Guid::v5_from_name(namespace, name can stay on Guid since it is generic and reusable primitive.

   What do you think about above or we drop it if the Guid convenience isn't worth a separate function.

[utpilla]

Thanks @swashtek, this looks good. Two things from the consumer side:

Enumeration API: +1 to the visitor over returning a collection, and keeping the single TdhEnumerateProviders pass. For our use case, the receiver matches its configured names inside the closure, and can build a HashMap there if it wants, so no full map is forced.

Hash function: I'd collapse this to a single method instead of two. The only thing guid_from_tracelogging_name adds over from_eventsource_name is parsing a {GUID} literal, but that's a GUID-parse concern bolted onto a name-hash, and deciding "is this a literal or a name?" is trivial caller-side operation. So, one pure name-hash function covers everyone (the ETW receiver only needs that one; we handle GUIDs on a separate config field). Keep Guid::v5_from_name as the generic primitive underneath it and put the single name-hash as a shared cross-platform free function (off Guid, reachable from both the Linux .NET helper and the Windows ETW code).

On naming, something neutral that reads as "hash, not lookup", e.g. guid_from_provider_name_hash (the tracelogging crate calls the same thing Guid::from_name). I'd avoid resolve_* since the DB-vs-hash resolution stays in the consumer.

[swashtek]

@utpilla Thank you so much for the feedback.
I agree with the suggestions and semantics. I will start making changes as per the issue.

[brianrob]

This sounds good. I do feel better about the naming Guid::v5_from_name - that more closely aligns with what I'd expect to be on the Guid type. Thanks!