Macro tracelogging::define_provider

define_provider!() { /* proc-macro */ }

Creates a static symbol representing an ETW provider.

define_provider!(PROVIDER_SYMBOL, "ProviderName", options...);

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 be Guid::from_name(provider_name). Most providers should use the automatically-generated id so most providers do not need to specify the id 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.