Update and improve EventSource documentation #7093
Conversation
* reduces focus on ETW * Explains difference between self describing and manifest event formats * adds more complex examples * explains conventions for a well designed EventSource * remove references to 4.5 and 4.6 to reduce reading complexity * remove note about IDisposable
josalem
requested review from
a team,
Anipik,
ViktorHofer and
tarekgh
as code owners
|
Tagging subscribers to this area: @tarekgh, @tommcdon, @pjanotti Issue Details
Part of dotnet/diagnostics#515
|
|
Does it matter that the "Snippet 5000" check keeps failing? As far as I can tell, all the code snippets will cause this check to fail. I can't seem to spot a project file for any of them or one in a parent project that would associate them all together. Any guidance on that? |
|
Docs Build status updates of commit f94b69e:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Diagnostics.Tracing/EventSource.xml | View | Details | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtrace/cs/program.cs | ✅Succeeded | View | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtracelarge/cs/program.cs | ✅Succeeded | View | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtracesmall/cs/program.cs | ✅Succeeded | View |
xml/System.Diagnostics.Tracing/EventSource.xml
- Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Tracing.EventSourceSettings.EtwManifestEventFormat'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Diagnostics.Tracing.EventSource.ctor(string)'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Diagnostics.Tracing.EventSource.ctor(string, EventSourceSettings)'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'Syste.Diagnostics.Tracing.EventSource.Write'.
For more details, please refer to the build report.
If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.
Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.
Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the docs.microsoft.com contributor guides
- Post your question in the Docs support channel
|
Docs Build status updates of commit 7e97cfe:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Diagnostics.Tracing/EventSource.xml | View | Details | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtrace/cs/program.cs | ✅Succeeded | View | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtracelarge/cs/program.cs | ✅Succeeded | View | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtracesmall/cs/program.cs | ✅Succeeded | View |
xml/System.Diagnostics.Tracing/EventSource.xml
- Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Tracing.EventSourceSettings.EtwManifestEventFormat'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Diagnostics.Tracing.EventSource.ctor(string)'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Diagnostics.Tracing.EventSource.ctor(string, EventSourceSettings)'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'Syste.Diagnostics.Tracing.EventSource.Write'.
For more details, please refer to the build report.
If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.
Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.
Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the docs.microsoft.com contributor guides
- Post your question in the Docs support channel
|
Is there any way to |
Here are some examples for class, property, method, and constructor. <see cref="T:System.Globalization.CultureInfo" />
<see cref="P:System.Globalization.CultureInfo.Name" />
<see cref="M:System.Globalization.DateTimeFormatInfo.GetEraName(System.Int32)" />
<see cref="Overload:System.Globalization.CultureInfo.#ctor" /> |
|
Docs Build status updates of commit cbf84de:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Diagnostics.Tracing/EventSource.xml | View | Details | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtrace/cs/program.cs | ✅Succeeded | View | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtracelarge/cs/program.cs | ✅Succeeded | View | |
| samples/snippets/csharp/VS_Snippets_CLR/etwtracesmall/cs/program.cs | ✅Succeeded | View |
xml/System.Diagnostics.Tracing/EventSource.xml
- Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Diagnostics.Tracing.EventSource.ctor(string)'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'System.Diagnostics.Tracing.EventSource.ctor(string, EventSourceSettings)'. - Line 0, Column 0: [Warning-xref-not-found]
Cross reference not found: 'Syste.Diagnostics.Tracing.EventSource.Write'.
For more details, please refer to the build report.
If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.
Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.
Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the docs.microsoft.com contributor guides
- Post your question in the Docs support channel
Yes, please add a simple project file similar to https://github.com/dotnet/dotnet-api-docs/blob/main/snippets/System.Text/Rune/csharp/RuneSamples.csproj. This is a requirement that we added in the last month, which is why most of the snippets don't have one yet. |
Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
|
Docs Build status updates of commit 528c95c: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
samples/snippets/csharp/VS_Snippets_CLR/etwtracelarge/cs/program.cs
Outdated
Show resolved
Hide resolved
|
Docs Build status updates of commit 0ade23d: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
Docs Build status updates of commit 77b00ce: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
Before I merge this, is there any way to change the order that the sections of the doc are rendered in? The preview starts with the examples and advanced usage sections despite those being lower in the markdown. It would make more sense for the remarks and conventions sections to be higher up. |
| if (IsEnabled()) | ||
| { | ||
| EventSource.EventData* descrs = stackalloc EventSource.EventData[3]; | ||
| descrs[0] = new EventData { DataPointer = (IntPtr)(&arg1), Size = 4 }; |
There was a problem hiding this comment.
Is this a safe thing to do in a sample? Here you are getting them from args only on primitives, which makes it OK. Do we have good guidance around fields of classes for things like strings and other ref types?
There was a problem hiding this comment.
Event methods on EventSource must call WriteEvent and their parameters must match. An exception will be thrown if the event method's parameter list doesn't match the parameter list of the WriteEvent overload used. This code is adding an overload of WriteEvent that knows how to quickly write a payload of int, short, long which isn't a pre-written overload.
The EventData struct can only contain types that are capable of being represented with EventSource metadata:
// A Valid type to log to an EventSource include
// * Primitive data types
// * IEnumerable<T> of valid types T (this include arrays) (* New for V4.6)
// * Explicitly Opted in class or struct with public property Getters over Valid types. (* New for V4.6)
EventSource derives its metadata from the parameter list of the event method which must match the call to WriteEvent.
In other words, you can only do this optimization with strings and primitive types. You could theoretically write something like this though:
public class MyType
{
public string Foo { get; set; }
public int Bar { get; set; }
public long Baz { get; set; }
}
public abstract class UtilSource : EventSource
{
protected UtilSource() : base () { }
protected UtilSource(bool throwOnEventWriteErrors) : base(throwOnEventWriteErrors) { }
protected unsafe void WriteEvent(int eventId, string arg1, int arg2, long arg3)
{
if (IsEnabled())
{
fixed (char* _arg1 = arg1 ?? string.Empty)
{
EventSource.EventData* descrs = stackalloc EventSource.EventData[3];
descrs[0] = new EventData { DataPointer = (IntPtr)(_arg1), Size = ((arg1?.Length ?? 0) + 1) * 2 };
descrs[1] = new EventData { DataPointer = (IntPtr)(&arg2), Size = 4 };
descrs[2] = new EventData { DataPointer = (IntPtr)(&arg3), Size = 8 };
WriteEventCore(eventId, descrs);
}
}
}
}
public sealed MySource : UtilSource
{
public static MySource Log = new();
[NonEvent]
public void LogThing(MyType thing) => DumpMyType(thing.Foo, thing.Bar, thing.Baz);
[Event(1)]
public void DumpMyType(string arg1, int arg2, long arg3) => WriteEvent(1, arg1, arg2, arg3);
}There was a problem hiding this comment.
Mostly what I meant: should the sample show to save pointers for things that are not safe to assume pinned (strings and other things adhering to the third point of "opted in", including value types that live in the heap like boxed and embedded types). Exactly like the example you have or something like CounterPayload since this is an advanced scenario type of thing.
There was a problem hiding this comment.
You can't really do this optimization with anything reference typed besides strings and you need to have the fixed scope surround your call to WriteEventCore or you will run into issues.
The "opted in" option is a reference to types decorated with EventDataAttribute which only applies to the Write<T> API which can't be optimized like this.
Oh that is strange what it did. What about making Conventions, Self-describing (tracelogging) vs. manifest event formats, Examples, and Advanced usage all H3 headings? e.g. |
|
@gewarren, is there a way to manually trigger the OpenPublishing.Build job? It seems to be stuck. |
Yes, close/reopen the PR. I'll do it now. |
|
Docs Build status updates of commit 304e7e9: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
Hmmm still seems to be shuffling the sections. |
That didn't do the trick. @mimisasouvanh Any suggestions here about how to change the ordering of the Markdown headings? |
|
I'm okay merging it with the current arrangement, but it hampers readability to start with examples rather than remarks. |
7 participants
Part of dotnet/diagnostics#515