Microsoft.LinuxTracepoints.Provider 0.1.3.21

Microsoft.LinuxTracepoints.Provider

.NET library for logging Linux user_events Tracepoints with optional EventHeader encoding.

Requires TargetFramework net6.0 or later.

See ProviderSample for example usage.

Usage for basic Tracepoint events

• At component initialization, create tracepoint = new PerfTracepoint("MyTracepointName int Field1; int Field2") to create a tracepoint. Use the tracepoint command format described in the user_events documentation.

• Check the tracepoint.IsEnabled property to efficiently determine whether any tracepoint collection session is collecting data from your tracepoint. This allows you to skip preparing data and calling Write when nobody is collecting your event.

• Call tracepoint.Write(eventData...) with 0 to 5 ReadOnlySpan<T> eventData args to write an event to your tracepoint. If no tracepoint collection session is collecting data from your tracepoint, the Write method will immediately return EBADF. Otherwise, the Write method will concatenate the values of the eventData args and write an event with the specified data.

• Call tracepoint.Dispose() to unregister your tracepoint.

• For debugging or diagnostic purposes, check the tracepoint.RegisterResult property to determine the errno returned during tracepoint registration, and check the errno returned from Write to detect any issues with writing the event.

Note that if the tracepoint is unregistered (i.e. if registration failed or if the tracepoint is disposed), the IsEnabled property and Write method are safe no-ops.

// First field is a 32-bit int.
// Second field is a variable-length string of 8-bit chars, which is encoded as a rel_loc field.
// Full syntax of the tracepoint registration string is defined in
// https://docs.kernel.org/trace/user_events.html#command-format
var complexTracepoint = new PerfTracepoint("MyTracepointWithTwoFields int Field1; __rel_loc char[] Field2");

// You can safely call Write(...) even when nobody is collecting the tracepoint, but
// usually it's better to check IsEnabled first. That way you don't waste time collecting
// data and passing parameters to Write when it is just going to immediately return.
if (complexTracepoint.IsEnabled)
{
    // Prepare the parameters that you will need to include in your event.
    int field1 = 25;
    ReadOnlySpan<byte> field2 = "SomeChars\0"u8; // Note that the char[] field type expects nul-terminated 8-bit string.

    // Variable-length fields must be packed as a rel_loc.
    // The field slot has a 32-bit integer that is the RelLoc value.
    // High 16 bits of RelLoc are "size of data".
    // Low 16 bits of RelLoc are "offset from end of slot to start of data".
    // The actual data goes after all field slots.
    // In this case, since this is the last field slot, the offset from the end
    // of the slot to the start of the field data is 0.
    UInt32 field2RelLoc = 0u | ((UInt32)field2.Length << 16);
    complexTracepoint.Write(
        (ReadOnlySpan<int>)MemoryMarshal.CreateSpan(ref field1, 1), // In .NET 7 or later, simplify as: new ReadOnlySpan<int>(ref field1).
        (ReadOnlySpan<UInt32>)MemoryMarshal.CreateSpan(ref field2RelLoc, 1),
        field2);
}

// Unregister tracepoints during component cleanup.
complexTracepoint.Dispose();

Usage for EventHeader-encoded events

• At component initialization, create provider = new EventHeaderDynamicProvider("MyCompany_MyOrg_MyComponent"). The provider will manage tracepoints for your component.

• For best behavior, at component initialization, call provider.Register(level, keyword) for each level/keyword combination that will be used by your component.

  • Registering all necessary combinations at startup rather than on-first-use helps event consumers see which level/keyword combinations might be generated by your component, making it easier for them to collect all of the combinations they need to collect.

  • You might want to cache the tracepoints returned by Register if you want to avoid the overhead of looking them up later.

• When you need to generate an event with a particular level/keyword combination:

  • Obtain the tracepoint corresponding to the provider + level + keyword of the event you want to write.

    • If you called Register at component startup and saved the tracepoints returned by Register, use your own data structure to find the appropriate tracepoint. (Optimal performance and optimal behavior, but requires your own data structure to track tracepoints.)

    • If you called Register at component startup but did not save the tracepoints, use tracepoint = provider.Find(level, keyword) to look up a tracepoint that was previously registered with provider.Register(level, keyword). (Optimal behavior, small overhead for looking up the tracepoint.)

    • If you did not register all needed tracepoints at component startup (i.e. if you are registering tracepoints on first use instead of at component startup), use tracepoint = provider.FindOrRegister(level, keyword) to get the tracepoint. (Sub-optimal behavior since tracepoint consumers won't be able to reliably see what tracepoints your component might potentially see, but may be necessary in some scenarios.)

  • Check tracepoint.IsEnabled to determine whether any consumer is collecting the tracepoint's data. If it returns false, there is no need to write the event so you can skip the remaining steps.

  • Create a builder = new EventHeaderDynamicBuilder() for building the event (or use a previously-allocated builder to minimize overhead/garbage).

  • Call builder.Reset("MyEventName") to start building your event.

  • Call builder methods as appropriate to add fields to the event or to configure event attributes like tag, opcode, id, or version.

  • Call builder.Write(tracepoint) to write the builder's event to the tracepoint.

  • Call builder.Dispose() to return the builder's temporary buffers to the array pool.

• At component cleanup, call provider.Dispose() to unregister all tracepoints.

  • After the provider has been disposed, any provider.Register(...) or provider.Find(...) operations will throw ObjectDisposedException, but operations on individual tracepoints will be safe no-ops (tracepoint.IsEnabled will return false and builder.Write(tracepoint) will do immediately return EBADF).

// At component startup, construct an EventHeaderDynamicProvider for your provider name.
var provider = new EventHeaderDynamicProvider("MyProviderName");

// Recommended: At component startup, register all level + keyword combinations that
// your component will need. For best performance, cache the returned tracepoint
// (alternative is to look it up later via `provider.Find`).
var myProviderVerboseK1 = provider.Register(EventLevel.Verbose, 1);

// When you want to write an event, check whether the event's tracepoint is enabled.
// If it's not enabled, there's no need to write the event.
if (myProviderVerboseK1.IsEnabled)
{
    // Create a builder, or reuse a previously-existing builder.
    // For best performance, Dispose() of the builder when you're done with it.
    using (var builder = new EventHeaderDynamicBuilder())
    {
        builder.Reset("MyEventName")
            .AddInt32("Field1", 25)
            .AddString16("Field2", "SomeStringValue")
            .Write(myProviderVerboseK1);
    }
}

// At component cleanup, unregister all of the tracepoints in the provider.
provider.Dispose();

Changelog

0.1.3 (2024-05-20)

• Initial release.