Microsoft.LinuxTracepoints.Provider
0.1.3.21
dotnet add package Microsoft.LinuxTracepoints.Provider --version 0.1.3.21
NuGet\Install-Package Microsoft.LinuxTracepoints.Provider -Version 0.1.3.21
<PackageReference Include="Microsoft.LinuxTracepoints.Provider" Version="0.1.3.21" />
paket add Microsoft.LinuxTracepoints.Provider --version 0.1.3.21
#r "nuget: Microsoft.LinuxTracepoints.Provider, 0.1.3.21"
// Install Microsoft.LinuxTracepoints.Provider as a Cake Addin
#addin nuget:?package=Microsoft.LinuxTracepoints.Provider&version=0.1.3.21
// Install Microsoft.LinuxTracepoints.Provider as a Cake Tool
#tool nuget:?package=Microsoft.LinuxTracepoints.Provider&version=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 5ReadOnlySpan<T>
eventData args to write an event to your tracepoint. If no tracepoint collection session is collecting data from your tracepoint, theWrite
method will immediately returnEBADF
. Otherwise, theWrite
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 fromWrite
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 byRegister
, 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, usetracepoint = provider.Find(level, keyword)
to look up a tracepoint that was previously registered withprovider.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(...)
orprovider.Find(...)
operations will throwObjectDisposedException
, but operations on individual tracepoints will be safe no-ops (tracepoint.IsEnabled
will return false andbuilder.Write(tracepoint)
will do immediately returnEBADF
).
- After the provider has been disposed, any
// 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.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- Microsoft.LinuxTracepoints.Types (>= 0.1.3.21)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.1.3.21 | 81 | 5/20/2024 |