TraceProcessor version 1.0.0 is now available on NuGet with the following package ID:
Microsoft.Windows.EventTracing.Processing.All
This release contains bug fixes, API finalization and minor enhancements since version 0.3.0. Most of these changes were released recently in version 0.4.0. (A full changelog is below). Basic usage is still the same as in version 0.1.0 and version 0.2.0.
With version 1.0.0, we have stabilized the API, and following semantic versioning, no breaking changes (source or binary) will be made within the 1.x.y versions of these packages.
Note that there are a few parts of the API that are in preview and under active development; they may change in future releases; namely, the following types:
- IEventConsumer
- IScheduledConsumer
- ICompletable
- ConsumerSchedule
- ExtendedDataItem
- ExtendedDataItemReadOnlySpan
- ICompletableTwoPassEventConsumer
- IFilteredEventConsumer
- IFilteredTwoPassEventConsumer
- ITwoPassEventConsumer
- TraceEventCallback
- UnparsedGenericEvent
As before, if you find these packages useful, we would love to hear from you, and we welcome your feedback. For questions using this package, you can post on StackOverflow with the tag .net-traceprocessing, and issues can also be filed on the eventtracing-processing project on GitHub.
The full changelog for version 1.0.0 is as follows:
Breaking Changes (previously included in v0.4.0)
- On IWindowsTracePreprocessorEvent, ProviderId has been renamed PreprocessorProviderId.
- Throughout the API, duration properties are now of type TraceDuration or TimeSpan rather than Duration. TraceDuration has been used where the time represents the length trace events, and TimeSpan has been used otherwise. (TraceDuration implicitly converts to Duration.)
- UserData has been renamed to TraceEvent.Data and UserDataReader has been renamed to EventDataReader.
- IThreadStack has been split into IThreadStack and IStackSnapshot. Stacks without thread and timestamp data are now just IThreadStack, and pattern matching and stringification are now supported for these stacks, including heap snapshot stacks. Full IStackSnapshot instances (which inherit from IThreadStack) work as IThreadStack did previously.
- Struct properties that convert to another type now consistently omit any prefix. For example, the property is named TraceDuration.TimeSpan rather than TraceDuration.ToTimeSpan.
- IStackFrame has been replaced with the StackFrame structure for better memory usage.
- Numeric types are consistently represented as int or long for consistency with .NET.
- The timestamp context extension methods Create(Timestamp or nanoseconds) and CreateTraceDuration(Timestamp or nanoseconds) have been replaced with CreateApproximate/CreateApproximateTraceDuration. Where possible, these methods create a TraceTimestamp or TraceDuration with an approximate .Value rather than having .IsPartial set to true.
- StackId properties on IHeapAllocation are nullable to reflect missing data cases explicitly.
New Data Exposed (previously included in v0.4.0)
- IImage now provides FileOffset.
- An extension method on IImage, GetProcessAddress, supports turning a relative virtual address (RVA) into a process address that can be used to look up symbols.
- StackFrame now provides a RelativeVirtualAddress property.
- IWindowsTracePreprocessorEvent now has a PreprocessorProviderName property. This property requires a new version of the toolkit to function, which has not yet been released in an non-preview Windows SDK.
- IGenericEventField now provides a DateTimeType.
- IGenericEventField now supports a Type of TimeSpan (.AsTimeSpan and .AsTimeSpanList) for ETW timestamps.
Bug Fixes (previously included in v0.4.0)
- All TraceTimestamps from the same trace can now be compared, even if one is Partial and the other is not.
Other (new in v1.0.0)
- Console output and error produced during trace processing can be redirected via an extension method trace.Process(Stream, Stream).