dotnet / dotnet/docs

Add a walkthrough for using DiagnosticSourceEventSource

Open
#37,644 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
15h 21m
Merged PRs (30d)
370

Description

Details on how to write `DiagnosticSources` information out of process with `DiagnosticSourceEventSource` is sparse in the current documentation and is mostly contained outside, [DiagnosticSource User's Guide](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md) and in the source file, [DiagnosticSourceEventSource.cs](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/DiagnosticSourceEventSource.cs).

Although primarily this information will be useful for sophisticated diagnostic tools targeting .NET applications, it will be good to have this information. A good location for this document could be under [DiagnosticSource and DiagnosticListener](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/diagnosticsource-diagnosticlistener), using a similar walkthrough approach. There are some standalone examples of `DiagnosticSourceEventSource` use on library tests ([DiagnosticSourceEventSourceTests.cs](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/tests/NativeAotTests/DiagnosticSourceEventSourceTests.cs), [DiagnosticSourceEventSourceBridgeTests.cs](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/tests/DiagnosticSourceEventSourceBridgeTests.cs)) that can be used for this purpose but unfortunately those are in-proc examples and doesn't quite match the targeted an out-of-proc listener meant with using `DiagnosticSourceEventSource`. Ideally, the walkthrough should use `TraceEvent` library when consuming the data.

Trimmed and native AOT applications have constraints in using `DiagnosticSourceEventSource` that the documentation should warn. Discovering the interesting payload data is usually an iterative process starting with the top level type and going down the type heriarchy using the transform specification. Trimmed applications, which includes native AOT applications, are very likely to have the required types and type members trimmed away and the user expereince is likely not going to be ideal. As such, using DiagnosticSourceEventSource in trimmed and native AOT applications are not recommended.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.