Macro define_provider 

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

Creates a static symbol representing a tracepoint provider.

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

Options:

• group_name("providergroupname")

Overview

The define_provider! macro creates a symbol representing a group of tracepoints in your component. The symbol is a static Provider variable that can be used with write_event! to send eventheader-encoded events to user_events.

The PROVIDER_SYMBOL generated by define_provider! must be treated as a token, not a variable. When invoking write_event! or provider_enabled!, use the original symbol, not a reference or alias.

Note that provider symbol is not pub so it is not visible outside the module. To share the symbol with multiple modules, put the define_provider in the parent module, e.g. in lib.rs.

You can think of define_provider!(MY_PROVIDER, "MyProviderName"); as expanding to code approximately like:

static MY_PROVIDER: eventheader::Provider =
    eventheader::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 eventheader as eh;

eh::define_provider!(MY_PROVIDER, "MyCompany_MyComponent");

// Safety: If this is a shared object, you MUST call MY_PROVIDER.unregister() before unload.
unsafe { MY_PROVIDER.register(); }

let message = "We're low on ice cream.";
eh::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.

  Note that the PROVIDER_SYMBOL must be treated as a token, not as a variable. Using an alias or reference to this symbol with write_event! will not work.

• "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”.

  This string must not contain space, colon, or NUL characters. For best compatibility with the Linux tracing system, it should start with an ASCII letter or an underscore and should contain only ASCII letters, digits, and underscores.

Options

• group_name("name")

  Specifies the name of a provider group that this provider will belong to. Most providers do not join a provider group so most providers do not need to specify the group_id option. The “name” string may contain lowercase ASCII letters and digits.

  Example: group_name("mycompany")

• debug()

  For non-production diagnostics: prints the expanded macro during compilation.

• For compability with the tracelogging crate, certain other options may be accepted and ignored.