Skip to content

Support TraceLogging formatting hints#2443

Open
chwarr wants to merge 1 commit into
microsoft:mainfrom
chwarr:tdh-formatting-hint
Open

Support TraceLogging formatting hints#2443
chwarr wants to merge 1 commit into
microsoft:mainfrom
chwarr:tdh-formatting-hint

Conversation

@chwarr

@chwarr chwarr commented Jul 17, 2026

Copy link
Copy Markdown
Member

Trace Data Helper lets you add display hints to fields in events. For example, there are hints to indicate that an integer value should hex formatted on display or that the value is a HRESULT. The commonly used C++ TraceLogging library supports these hints via its TraceLogging Wrapper macros.

Add support for pretty printing the following _TDH_OUT_TYPE values:

  • TDH_OUTTYPE_HEXINT8 - hex, width of the underlying type
  • TDH_OUTTYPE_HEXINT16 - hex, width of the underlying type
  • TDH_OUTTYPE_HEXINT32 - hex, width of the underlying type
  • TDH_OUTTYPE_HEXINT64 - hex, width of the underlying type
  • TDH_OUTTYPE_PID - decimal number without digit seperators
  • TDH_OUTTYPE_TID - decimal number without digit seperators
  • TDH_OUTTYPE_PORT - decimal number without digit seperators, converted from network byte order
  • TDH_OUTTYPE_IPV4 - dotted quad
  • TDH_OUTTYPE_IPV6 - colon-seperated, elision of runs of zeros
  • TDH_OUTTYPE_SOCKETADDRESS - "address:port" for AF_INET and AF_INET6
  • TDH_OUTTYPE_ERRORCODE - hex, no padding
  • TDH_OUTTYPE_WIN32ERROR - hex, no padding
  • TDH_OUTTYPE_NTSTATUS - hex, always 8 digits wide
  • TDH_OUTTYPE_HRESULT - hex, always 8 digits wide
  • TDH_OUTTYPE_CODE_POINTER - lowercase hex, minimum of 8 digits wide

Fixes #2436.

Given TraceLogging code like this:

TraceLoggingWrite(
    g_hMyProvider,
    "MyEvent",
    TraceLoggingUInt32(value1ToLog),
    TraceLoggingHexUInt32(value2ToLog));

In PerfView today, this would be rendered as

    value1ToLog="1" value2ToLog="32,769"

Now, it is rendered as

    value1ToLog="1" value2ToLog="0x00008001"

Visually, before:

screenshot of events before this change: no hex formatting

and after:

screenshot of events after this change: values are hex formatted, IP addresses are pretty-printed

For things like flags these format hints can make it easier to read values at a glance. There are also common values that are represented in hex, like PCI IDs.

When PerfView already had support for formatting a value, its existing formating style was followed. Otherwise, I matched WPA's formatting.

Changes made:

  • Changed TraceEvent's representation of the output type from a ushort to the new TdhOutputType enum.
  • Add TdhFormtter.cs that knows how to format a value with a given formatting hint. A formatting hint was chosen so that the PayloadFetch object didn't need to remember both its TdhInputType and its TdhOutputType.
  • Reved the FastSerializable format to include the new formatting hint.
  • Introduced a new FormatUtils helper for shared formatting code between TraceEvent.cs and DynamicTraceEventParser.cs
  • Unit tests for the new formatting logic added.
  • Updated the baseline files to capture the changes in formatting.

Trace Data Helper lets you add display hints to fields in events. For
example, there are hints to indicate that an integer value should hex
formatted on display or that the value is a HRESULT. The commonly used
[C++ TraceLogging library][0] supports these hints via its [TraceLogging
Wrapper macros][1].

Add support for pretty printing the following _TDH_OUT_TYPE values:

* TDH_OUTTYPE_HEXINT8 - hex, width of the underlying type
* TDH_OUTTYPE_HEXINT16 - hex, width of the underlying type
* TDH_OUTTYPE_HEXINT32 - hex, width of the underlying type
* TDH_OUTTYPE_HEXINT64 - hex, width of the underlying type
* TDH_OUTTYPE_PID - decimal number without digit seperators
* TDH_OUTTYPE_TID - decimal number without digit seperators
* TDH_OUTTYPE_PORT - decimal number without digit seperators, converted
  from network byte order
* TDH_OUTTYPE_IPV4 - dotted quad
* TDH_OUTTYPE_IPV6 - colon-seperated, elision of runs of zeros
* TDH_OUTTYPE_SOCKETADDRESS - "address:port" for AF_INET and AF_INET6
* TDH_OUTTYPE_ERRORCODE - hex, no padding
* TDH_OUTTYPE_WIN32ERROR - hex, no padding
* TDH_OUTTYPE_NTSTATUS - hex, always 8 digits wide
* TDH_OUTTYPE_HRESULT - hex, always 8 digits wide
* TDH_OUTTYPE_CODE_POINTER - lowercase hex, minimum of 8 digits wide

Fixes microsoft#2436.

Given TraceLogging code like this:

```
TraceLoggingWrite(
    g_hMyProvider,
    "MyEvent",
    TraceLoggingUInt32(value1ToLog),
    TraceLoggingHexUInt32(value2ToLog));
```

In PerfView today, this would be rendered as

```
    value1ToLog="1" value2ToLog="32,769"
```

Now, it is rendered as

```
    value1ToLog="1" value2ToLog="0x00008001"
```

For things like flags these format hints can make it easier to read
values at a glance. There are also common values that are represented in
hex, like PCI IDs.

When PerfView already had support for formatting a value, its existing
formating style was followed. Otherwise, I matched WPA's formatting.

Changes made:

* Changed TraceEvent's representation of the output type from a ushort
  to the new TdhOutputType enum.
* Add TdhFormtter.cs that knows how to format a value with a given
  formatting hint. A formatting hint was chosen so that the PayloadFetch
  object didn't need to remember both its TdhInputType and its
  TdhOutputType.
* Reved the FastSerializable format to include the new formatting hint.
* Introduced a new FormatUtils helper for shared formatting code between
  TraceEvent.cs and DynamicTraceEventParser.cs
* Unit tests for the new formatting logic added.
* Updated the baseline files to capture the changes in formatting.

[0]: https://learn.microsoft.com/windows/win32/tracelogging/trace-logging-portal
[1]: https://learn.microsoft.com/windows/win32/tracelogging/tracelogging-wrapper-macros
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support TraceLogging formatting hints like TraceLoggingHexUInt32

1 participant