Microsoft.LinuxTracepoints.Decode
0.1.3.21
Prefix Reserved
dotnet add package Microsoft.LinuxTracepoints.Decode --version 0.1.3.21
NuGet\Install-Package Microsoft.LinuxTracepoints.Decode -Version 0.1.3.21
<PackageReference Include="Microsoft.LinuxTracepoints.Decode" Version="0.1.3.21" />
paket add Microsoft.LinuxTracepoints.Decode --version 0.1.3.21
#r "nuget: Microsoft.LinuxTracepoints.Decode, 0.1.3.21"
// Install Microsoft.LinuxTracepoints.Decode as a Cake Addin
#addin nuget:?package=Microsoft.LinuxTracepoints.Decode&version=0.1.3.21
// Install Microsoft.LinuxTracepoints.Decode as a Cake Tool
#tool nuget:?package=Microsoft.LinuxTracepoints.Decode&version=0.1.3.21
Microsoft.LinuxTracepoints.Decode
.NET library for parsing perf.data
files and decoding tracepoint events. This
includes decoding of perf.data
files, parsing of tracefs format
files, formatting
of tracepoint event fields, and decoding of tracepoints that use the EventHeader
decoding system.
Decoding procedure
For an example, see DecodeSample.
Create a file reader:
var reader = new PerfDataFileReader()
.If you will be decoding events that use the
EventHeader
decoding system, create an enumerator to use for decoding them:var eventHeaderEnumerator = reader.GetEventHeaderEnumerator()
.Call reader.OpenFile(perfDataFileName, sortOrder) to open the
perf.data
file and read the file header.- The
sortOrder
parameter specifies whether the reader should return events in the order they occur in the file (PerfDataFileEventOrder.File
, less resource-intensive) or in timestamp order (PerfDataFileEventOrder.Time
).
- The
Call
reader.ReadEvent(out eventBytes)
to read the header and bytes of the next event.Use
eventBytes.Header.Type
to determine the type of event.If
Type != Sample
, this is a non-sample event that contains information about the trace or about the system on which the trace was collected. This library provides no support for decoding these events. Refer tolinux/uapi/linux/perf_event.h
for the format of these events.- Some of these events may have associated metadata, e.g. timestamp, CPU, pid, tid. This
library does provide support for accessing the metadata by calling
reader.GetNonSampleEventInfo(eventBytes, out nonSampleEventInfo)
.
- Some of these events may have associated metadata, e.g. timestamp, CPU, pid, tid. This
library does provide support for accessing the metadata by calling
If
Type == Sample
, this is a sample event, e.g. a tracepoint event.Use
reader.GetSampleEventInfo(eventBytes, out sampleEventInfo)
to look up metadata for the event. If metadata lookup succeeds andsampleEventInfo.Format
is notnull
, you can use this library to decode the event.If
sampleEventInfo.Format.DecodingStyle
isTraceEventFormat
, decode the event usingsampleEventInfo.Format.Fields
. UsesampleEventInfo.Format.Fields[i].GetFieldValue(sampleEventInfo)
to get aPerfItemValue
for the field at indexi
. ThePerfItemValue
has the field's type information and aReadOnlySpan<byte>
with the field's value. It also has helper methods for accessing the field's value as a .NET type or as a string. (The firstFormat.CommonFieldCount
fields are usually not interesting and are typically skipped.)If
sampleEventInfo.Format.DecodingStyle
isEventHeader
, decode the event usingeventHeaderEnumerator
. Start enumeration by callingeventHeaderEnumerator.StartEvent(sampleEventInfo)
. You can then get EventHeader-specific information about the event fromeventHeaderEnumerator.GetEventInfo()
, and you can iterate through the fields of the event usingeventHeaderEnumerator.MoveNext()
.
Classes and structs
EventHeaderEnumerator
class - provides access to information and field values of an event that uses theEventHeader
decoding format. This can be used in combination with thePerfDataFileReader
class to read and decode events from aperf.data
file, or with some other source of event data.EventHeaderEventInfo
struct - provides information about anEventHeader
event, such as the tracepoint name, event name, severity level, activity ID, etc.EventHeaderItemInfo
struct - provides information about a field in anEventHeader
event, such as the field name, field type, and field value.PerfByteReader
struct - helper for reading values from a data source that may be big-endian or little-endian, e.g. events from aperf.data
file.PerfConvert
static class - provides methods for converting tracepoint event field data to .NET types.- Helpers for formatting fields as text (new string with
ToString()
, append toStringBuilder
, or format toSpan<char>
). - Helpers for converting UNIX
time_32
andtime_64
timestamps to .NETDateTime
values.
- Helpers for formatting fields as text (new string with
PerfDataFileReader
class - parses aperf.data
file into headers and events (optionally sorted by timestamp), provides access to event metadata like timestamp or CPU, tracks tracefsformat
decoding information for each event.PerfEventBytes
struct - bytes of a single event from aperf.data
file.PerfEventDesc
class - stores theperf_event_attr
, tracepoint name, and tracefsformat
information for a set of events.PerfEventFormat
class - parses a tracefsformat
file and provides access to the decoding information for tracepoint events.PerfFieldFormat
class - parses a field format string from a tracefsformat
file and provides access to the field name, type, and size.PerfNonSampleEventInfo
struct - provides information about a non-sample event, such as the event bytes, session information, cpu, time, pid, tracepoint name, format, and timestamp.PerfSampleEventInfo
struct - provides information about a sample event, such as the event bytes, session information, cpu, time, pid, tracepoint name, format, timestamp, raw, and format.PerfSessionInfo
class - provides information about a trace decoding session such as the byte order and the clock source.PerfTimeSpec
struct - represents a timestamp as atime64_t
plus nanoseconds. Semantics equivalent tostruct timespec
fromtime.h
.PerfItemValue
struct - represents the value of a field of a tracepoint event. Includes type information. Provides byte-order-aware helpers for accessing the value as a .NET type (e.g.GetU32
,GetF64
,GetGuid
). Provides helpers for formatting the value as astring
or appending it to aStringBuilder
.
Project
This component is a part of the LinuxTracepoints-Net project. Feedback and contributions are welcome.
Changelog
0.1.3 (2024-05-20)
- Fix error when using
GetSampleEventInfo
orGetNonSampleEventInfo
with C# language 11 or later. - Formatting functions fall back to system/tracepoint name from format info if
the system/tracepoint name is not available from the
EVENT_DESC
header (e.g.AppendJsonEventInfoTo
,AppendJsonEventIdentityTo
,ToString
). Provide helpers to make it easier for clients to have the same fallback behavior.
0.1.2 (2024-05-06)
- Fix invalid TID returned from
GetNonSampleEventInfo
. - Fix
PerfTimeSpec.ToString()
to properly include subsecond values. - Renamed
PerfValue
toPerfItemValue
. - Refactored some of the
PerfItemValue
fields into a separatePerfItemType
struct. SeveralperfItemValue.<property>
members are now accessed asperfItemValue.Type.<property>
: ElementCount, FieldTag, TypeSize, Encoding, ArrayFlags, EncodingAndArrayFlags, IsArrayOrElement, Format, StructFieldCount. PerfSampleEventInfo.Format
is now non-nullable. In cases where it was previously null, it now holds the Empty format (format.IsEmpty is true).EventHeaderEnumerator
now has aGetItemType()
method. This returns a subset of the information returned fromGetItemInfo()
and can be used as an optimization when only the item type information is needed.PerfConvert
string methods have been refactored to ensure that callers correctly handle control characters (space, newline, etc.) when formatting strings (the new methods have a required parameter to indicate how control characters should be formatted - as-is, as-space, or as-escape-sequence).StringAppend
is nowStringAppendWithControlChars
, andStringLatin1Append
is nowStringLatin1AppendWithControlChars
. Default control character handling is replace-with-space for basic formatting and replace-with-JSON-escape-sequence for JSON formatting.PerfConvert
exposes several new methods:ReadGuidBigEndian
,Char16AppendWithControlChars
, etc.PerfDataFileReader
exposes new propertySessionInfo
.PerfDataFileReader
exposes new methodHeaderString
.- Added
AsString
extension method forPerfEventAttrType
. PerfTimeSpec
now implementsIComparable
,IEquatable
, and overloads the comparison operators.PerfTimeSpec
can now be constructed from aDateTime
.PerfTimeSpec
exposes anAddNanoseconds
method.
0.1.1 (2024-04-22)
- Initial release.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. 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. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- 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.