Crate eventheader_dynamic

source ·
Expand description

§Dynamic EventHeader-encoded Linux Tracepoints

eventheader_dynamic provides a flexible way to log EventHeader-encoded events to Linux user_events. The events can be generated and collected on Linux 6.4 or later (requires the user_events kernel feature to be enabled, the tracefs or debugfs filesystem to be mounted, and appropriate permissions configured for the /sys/kernel/.../tracing/user_events_data file).

This “dynamic” implementation is more flexible than the implementation in the eventheader crate. For example, it supports runtime-defined schema and can easily log arrays of strings. However, it is harder to use, it has higher runtime costs, and it depends on the alloc crate. This dynamic implementation is intended for use only when the set of events cannot be determined at compile-time. For example, eventheader_dynamic might be used to implement a middle-layer library providing tracing support to a scripting language like JavaScript or Python. In other cases, use the eventheader crate instead of this crate.

§Overview

  • Create a Provider object with the name of the provider to be used.
  • Use the provider to register an EventSet for each level/keyword combination needed.
  • Use EventSet::enabled to determine whether the event set is enabled.
  • If the event set is enabled, use an EventBuilder to build the event (setting event properties and adding event fields) then write the event to the EventSet.
  • The provider will automatically unregister when it is dropped. You can manually call Provider::unregister if you want to unregister sooner or if the provider is stored within a static variable.

§Example

use eventheader_dynamic as ehd;

// Create a provider to use for all "MyCompany_MyComponent" events.
let mut provider = ehd::Provider::new("MyCompany_MyComponent", &ehd::Provider::new_options());

// Create an event_set to use for all "MyCompany_MyComponent" events with severity
// level Verbose and event category bits 0x1f.
let event_l5k1f = provider.register_set(ehd::Level::Verbose, 0x1f);

// If nobody is listening for events from this event set, the write method will do nothing.
// It is more efficient to only build and write the event if the event set is enabled.
if event_l5k1f.enabled() {
    let field1_value = "FieldValue";
    let field2_value = b'A';

    // Build and write an event with two fields:
    ehd::EventBuilder::new()
        // Most events specify 0 for event tag.
        .reset("MyEventName", 0)
        // Most fields use 0 for field tag.
        .add_str("FieldName1", field1_value, ehd::FieldFormat::Default, 0)
        .add_value("FieldName2", field2_value, ehd::FieldFormat::String8, 0)
        // activity_id is None indicating event is not part of an activity.
        // related_id is None indicating event does not specify a parent activity.
        .write(&event_l5k1f, None, None);
}

§Notes

The EventBuilder object is reusable. You may get a small performance benefit by reusing an EventBuilder object for multiple events rather than using a new EventBuilder for each event.

Events are limited in size (event size = headers + metadata + data). The kernel will ignore any event that is larger than 64KB.

All event sets registered with a provider will become unregistered when the provider is dropped or when you call provider.unregister().

Each event set maps to one tracepoint name, e.g. if the provider name is “MyCompany_MyComponent”, level is Verbose, and category bits are 0x1f, the event set will correspond to a tracepoint named “MyCompany_MyComponent_L5K1f”.

Collect events to a file using a tool such as perf, e.g. perf record -e user_events:MyCompany_MyComponent_L5K1f.

Decode events using a tool such as decode-perf.

Modules§

Macros§

Structs§

  • EventBuilder
    EventBuilder is a builder for events to be written through a Provider.
  • EventSet
    Tracks the status of a set of events that have the same provider, level, and keyword.
  • FieldEncoding
    Values for the encoding byte of a field definition.
  • FieldFormat
    Values for the format byte of a field definition.
  • Level
    Indicates the severity of an event. Use Verbose if unsure.
  • Opcode
    Values for [EventHeader::opcode] indicating special semantics to be used by the event decoder for grouping and organizing events, e.g. for activities.
  • Provider
    Represents a connection for writing dynamic Linux tracepoints.
  • ProviderOptions
    Builder for provider configuration. Used when registering a provider.

Enums§

  • NativeImplementation
    Possible configurations under which this crate can be compiled: LinuxUserEvents or Other.

Constants§