Macro tracelogging::define_provider
source · define_provider!() { /* proc-macro */ }
Expand description
Creates a static symbol representing an ETW provider.
define_provider!(PROVIDER_SYMBOL, "ProviderName", options...);
id("ProviderGuid")
group_id("ProviderGroupGuid")
Overview
The define_provider
macro creates a symbol representing an ETW (Event Tracing for
Windows) event provider. The symbol is a static Provider
variable that can be
used with write_event!
to send TraceLogging-encoded events to ETW.
The PROVIDER_SYMBOL
generated by define_provider!
should be treated as a token,
not a variable. When invoking write_event!
, use the original symbol, not a
reference or alias.
You can think of define_provider!(MY_PROVIDER, "MyProviderName");
as expanding
to code approximately like:
static MY_PROVIDER: tracelogging::Provider =
tracelogging::Provider::new("MyProviderName");
Note: The provider starts out unregistered. You must call
MY_PROVIDER.register();
to open the provider before using it. With the exception
of Provider::register, all operations on an unregistered provider are no-ops (they
will do nothing and return immediately).
Example
use tracelogging as tlg;
tlg::define_provider!(MY_PROVIDER, "MyCompany.MyComponent");
// Safety: If this is a DLL, you MUST call MY_PROVIDER.unregister() before unload.
unsafe { MY_PROVIDER.register(); }
let message = "We're low on ice cream.";
tlg::write_event!(
MY_PROVIDER,
"MyWarningEvent",
level(Warning),
str8("MyFieldName", message),
);
MY_PROVIDER.unregister();
Syntax
define_provider!(PROVIDER_SYMBOL, "ProviderName", options...);
Required parameters
-
PROVIDER_SYMBOL
The token that will be used to refer to the provider. This is used with
write_event!
and with Provider methods like Provider::register. -
"ProviderName"
A string literal that specifies a short human-readable name for the provider. This string will be included in the events and will be a primary attribute for event identification. It needs to be unique so that it does not conflict with names used by other providers. It should follow a namespace convention like “CompanyName.ComponentName”.
Options
-
id("GUID")
Specifies the ETW provider id, also known as the ETW Control GUID. If the
id
option is not specified, the provider’s id will beGuid::from_name(provider_name)
. Most providers should use the automatically-generated id so most providers do not need to specify theid
option.Example:
id("80c257fb-c6bc-4538-a4c4-c7b863d46a8c")
-
group_id("GUID")
Specifies the ETW provider group id. Most providers do not join a provider group so most providers do not need to specify the
group_id
option.Example:
group_id("f73b8292-f610-4fa7-ba62-708353d162c4")
-
debug()
For non-production diagnostics: prints the expanded macro during compilation.