From a1c7266fb3cba330e58779943547190be4a2cb52 Mon Sep 17 00:00:00 2001 From: Apoorv Deshmukh Date: Mon, 9 Mar 2026 17:42:16 +0530 Subject: [PATCH 1/3] Add api documentation for logging --- .../Logging/src/Logging.csproj | 38 +- .../Logging/src/SqlClientEventSource.cs | 572 +++++++++++++++++- 2 files changed, 604 insertions(+), 6 deletions(-) diff --git a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj index 9682b33c23..ad8a087417 100644 --- a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj +++ b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj @@ -65,8 +65,12 @@ $(Artifacts)/bin/$(Configuration)/$(AssemblyName) - - $(Artifacts)/doc/$(TargetFramework)/$(AssemblyName).xml + + true @@ -84,7 +88,8 @@ Microsoft Corporation Microsoft Corporation - Microsoft.Data.SqlClient Extensions Logging - ETW EventSource for SqlClient tracing and diagnostics. + Microsoft.Data.SqlClient Extensions Logging - ETW EventSource for SqlClient tracing + and diagnostics. https://github.com/dotnet/SqlClient MIT dotnet.png @@ -109,4 +114,29 @@ - + + + + + + + + + + + + \ No newline at end of file diff --git a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs index 712e5ee72b..86ac7adba5 100644 --- a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs +++ b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs @@ -14,6 +14,24 @@ namespace Microsoft.Data.SqlClient /// /// ETW EventSource for Microsoft.Data.SqlClient tracing and diagnostics. /// + /// + /// + /// This uses the provider name Microsoft.Data.SqlClient.EventSource + /// and can be enabled via ETW tools such as PerfView, dotnet-trace, or programmatically through + /// instances. + /// + /// + /// Events are organized into keyword groups (see ) that can be enabled + /// independently to control the verbosity and scope of tracing. Use the singleton + /// instance to write events and query enablement status. + /// + /// + /// Enable ETW tracing with PerfView: + /// + /// PerfView.exe collect /Providers=*Microsoft.Data.SqlClient.EventSource + /// + /// + /// [EventSource(Name = "Microsoft.Data.SqlClient.EventSource")] public class SqlClientEventSource : EventSource { @@ -250,6 +268,10 @@ public class Keywords /// /// Tasks supported by SqlClient's EventSource implementation. /// + /// + /// Tasks represent logical groups of related start/stop operations and are used by + /// ETW consumers to correlate scope-enter and scope-leave events. + /// public static class Tasks { /// @@ -283,78 +305,91 @@ public static class Tasks /// /// Checks if execution trace events are enabled. /// + /// if execution trace events are enabled; otherwise, . [NonEvent] public bool IsExecutionTraceEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.ExecutionTrace); /// /// Checks if trace events are enabled. /// + /// if trace events are enabled; otherwise, . [NonEvent] public bool IsTraceEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.Trace); /// /// Checks if scope events are enabled. /// + /// if scope events are enabled; otherwise, . [NonEvent] public bool IsScopeEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.Scope); /// /// Checks if notification trace events are enabled. /// + /// if notification trace events are enabled; otherwise, . [NonEvent] public bool IsNotificationTraceEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.NotificationTrace); /// /// Checks if notification scope events are enabled. /// + /// if notification scope events are enabled; otherwise, . [NonEvent] public bool IsNotificationScopeEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.NotificationScope); /// /// Checks if pooler trace events are enabled. /// + /// if pooler trace events are enabled; otherwise, . [NonEvent] public bool IsPoolerTraceEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.PoolerTrace); /// /// Checks if pooler scope events are enabled. /// + /// if pooler scope events are enabled; otherwise, . [NonEvent] public bool IsPoolerScopeEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.PoolerScope); /// /// Checks if advanced trace events are enabled. /// + /// if advanced trace events are enabled; otherwise, . [NonEvent] public bool IsAdvancedTraceOn() => Log.IsEnabled(EventLevel.Verbose, Keywords.AdvancedTrace); /// /// Checks if advanced trace binary events are enabled. /// + /// if advanced trace binary events are enabled; otherwise, . [NonEvent] public bool IsAdvancedTraceBinOn() => Log.IsEnabled(EventLevel.Verbose, Keywords.AdvancedTraceBin); /// /// Checks if correlation trace events are enabled. /// + /// if correlation trace events are enabled; otherwise, . [NonEvent] public bool IsCorrelationEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.CorrelationTrace); /// /// Checks if state dump events are enabled. /// + /// if state dump events are enabled; otherwise, . [NonEvent] public bool IsStateDumpEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.StateDump); /// /// Checks if SNI trace events are enabled. /// + /// if SNI trace events are enabled; otherwise, . [NonEvent] public bool IsSNITraceEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.SNITrace); /// /// Checks if SNI scope events are enabled. /// + /// if SNI scope events are enabled; otherwise, . [NonEvent] public bool IsSNIScopeEnabled() => Log.IsEnabled(EventLevel.Informational, Keywords.SNIScope); #endregion @@ -371,6 +406,11 @@ private string GetFormattedMessage(string className, string memberName, string e /// /// Writes a formatted trace event with two arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void TraceEvent(string message, T0 args0, T1 args1) { @@ -380,6 +420,13 @@ public void TraceEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted trace event with three arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void TraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -389,6 +436,15 @@ public void TraceEvent(string message, T0 args0, T1 args1, T2 args2) /// /// Writes a formatted trace event with four arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void TraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -400,6 +456,7 @@ public void TraceEvent(string message, T0 args0, T1 args1, T2 ar /// /// Writes a trace event if trace is enabled. /// + /// The trace message. [NonEvent] public void TryTraceEvent(string message) { @@ -412,6 +469,9 @@ public void TryTraceEvent(string message) /// /// Writes a formatted trace event with one argument if trace is enabled. /// + /// The type of the first argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0) { @@ -424,6 +484,11 @@ public void TryTraceEvent(string message, T0 args0) /// /// Writes a formatted trace event with two arguments if trace is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0, T1 args1) { @@ -436,6 +501,13 @@ public void TryTraceEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted trace event with three arguments if trace is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -448,6 +520,15 @@ public void TryTraceEvent(string message, T0 args0, T1 args1, T2 arg /// /// Writes a formatted trace event with four arguments if trace is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -460,6 +541,17 @@ public void TryTraceEvent(string message, T0 args0, T1 args1, T2 /// /// Writes a formatted trace event with five arguments if trace is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4) { @@ -472,6 +564,19 @@ public void TryTraceEvent(string message, T0 args0, T1 args1 /// /// Writes a formatted trace event with six arguments if trace is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5) { @@ -484,6 +589,21 @@ public void TryTraceEvent(string message, T0 args0, T1 a /// /// Writes a formatted trace event with seven arguments if trace is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// The type of the seventh argument. + /// A composite format string for the trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. + /// The seventh argument to format into the message. [NonEvent] public void TryTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5, T6 arg6) { @@ -500,6 +620,9 @@ public void TryTraceEvent(string message, T0 args0, /// /// Enters a scope and writes a scope event if scope tracing is enabled. /// + /// The name of the class entering the scope. + /// The name of the member entering the scope (auto-populated by the compiler). + /// The scope identifier, or 0 if scope tracing is not enabled. [NonEvent] public long TryScopeEnterEvent(string className, [CallerMemberName] string memberName = "") { @@ -515,6 +638,10 @@ public long TryScopeEnterEvent(string className, [CallerMemberName] string membe /// /// Enters a scope with one formatted argument if scope tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the scope message. + /// The first argument to format into the message. + /// The scope identifier, or 0 if scope tracing is not enabled. [NonEvent] public long TryScopeEnterEvent(string message, T0 args0) { @@ -528,6 +655,12 @@ public long TryScopeEnterEvent(string message, T0 args0) /// /// Enters a scope with two formatted arguments if scope tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The scope identifier, or 0 if scope tracing is not enabled. [NonEvent] public long TryScopeEnterEvent(string message, T0 args0, T1 args1) { @@ -541,6 +674,14 @@ public long TryScopeEnterEvent(string message, T0 args0, T1 args1) /// /// Enters a scope with three formatted arguments if scope tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The scope identifier, or 0 if scope tracing is not enabled. [NonEvent] public long TryScopeEnterEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -554,6 +695,16 @@ public long TryScopeEnterEvent(string message, T0 args0, T1 args1, T /// /// Enters a scope with four formatted arguments if scope tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The scope identifier, or 0 if scope tracing is not enabled. [NonEvent] public long TryScopeEnterEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -567,6 +718,7 @@ public long TryScopeEnterEvent(string message, T0 args0, T1 args /// /// Leaves a scope if scope tracing is enabled. /// + /// The scope identifier returned by a previous scope enter call. [NonEvent] public void TryScopeLeaveEvent(long scopeId) { @@ -581,6 +733,12 @@ public void TryScopeLeaveEvent(long scopeId) /// /// Writes a BeginExecute trace event if execution tracing is enabled. /// + /// The object identifier of the command. + /// The data source (server) name. + /// The database name. + /// The SQL command text being executed. + /// The client connection identifier. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TryBeginExecuteEvent(int objectId, string dataSource, string database, string commandText, Guid? connectionId, [CallerMemberName] string memberName = "") { @@ -593,6 +751,11 @@ public void TryBeginExecuteEvent(int objectId, string dataSource, string databas /// /// Writes an EndExecute trace event if execution tracing is enabled. /// + /// The object identifier of the command. + /// The composite state of the command at completion. + /// The SQL exception number, or 0 if no exception occurred. + /// The client connection identifier. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TryEndExecuteEvent(int objectId, int compositeState, int sqlExceptionNumber, Guid? connectionId, [CallerMemberName] string memberName = "") { @@ -609,6 +772,11 @@ public void TryEndExecuteEvent(int objectId, int compositeState, int sqlExceptio /// /// Writes a formatted notification trace event with two arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the notification trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void NotificationTraceEvent(string message, T0 args0, T1 args1) { @@ -620,6 +788,7 @@ public void NotificationTraceEvent(string message, T0 args0, T1 args1) /// /// Writes a notification trace event if notification tracing is enabled. /// + /// The notification trace message. [NonEvent] public void TryNotificationTraceEvent(string message) { @@ -632,6 +801,9 @@ public void TryNotificationTraceEvent(string message) /// /// Writes a formatted notification trace event with one argument if notification tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the notification trace message. + /// The first argument to format into the message. [NonEvent] public void TryNotificationTraceEvent(string message, T0 args0) { @@ -644,6 +816,11 @@ public void TryNotificationTraceEvent(string message, T0 args0) /// /// Writes a formatted notification trace event with two arguments if notification tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the notification trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void TryNotificationTraceEvent(string message, T0 args0, T1 args1) { @@ -656,6 +833,13 @@ public void TryNotificationTraceEvent(string message, T0 args0, T1 args1 /// /// Writes a formatted notification trace event with three arguments if notification tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the notification trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void TryNotificationTraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -668,6 +852,15 @@ public void TryNotificationTraceEvent(string message, T0 args0, T1 a /// /// Writes a formatted notification trace event with four arguments if notification tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the notification trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void TryNotificationTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -684,6 +877,10 @@ public void TryNotificationTraceEvent(string message, T0 args0, /// /// Enters a notification scope with one formatted argument if notification scope tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the notification scope message. + /// The first argument to format into the message. + /// The scope identifier, or 0 if notification scope tracing is not enabled. [NonEvent] public long TryNotificationScopeEnterEvent(string message, T0 args0) { @@ -697,6 +894,12 @@ public long TryNotificationScopeEnterEvent(string message, T0 args0) /// /// Enters a notification scope with two formatted arguments if notification scope tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the notification scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The scope identifier, or 0 if notification scope tracing is not enabled. [NonEvent] public long TryNotificationScopeEnterEvent(string message, T0 args0, T1 args1) { @@ -710,6 +913,14 @@ public long TryNotificationScopeEnterEvent(string message, T0 args0, T1 /// /// Enters a notification scope with three formatted arguments if notification scope tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the notification scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The scope identifier, or 0 if notification scope tracing is not enabled. [NonEvent] public long TryNotificationScopeEnterEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -723,6 +934,16 @@ public long TryNotificationScopeEnterEvent(string message, T0 args0, /// /// Enters a notification scope with four formatted arguments if notification scope tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the notification scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The scope identifier, or 0 if notification scope tracing is not enabled. [NonEvent] public long TryNotificationScopeEnterEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -736,6 +957,7 @@ public long TryNotificationScopeEnterEvent(string message, T0 ar /// /// Leaves a notification scope if notification scope tracing is enabled. /// + /// The scope identifier returned by a previous notification scope enter call. [NonEvent] public void TryNotificationScopeLeaveEvent(long scopeId) { @@ -750,6 +972,7 @@ public void TryNotificationScopeLeaveEvent(long scopeId) /// /// Writes a pooler trace event if pooler tracing is enabled. /// + /// The pooler trace message. [NonEvent] public void TryPoolerTraceEvent(string message) { @@ -762,6 +985,9 @@ public void TryPoolerTraceEvent(string message) /// /// Writes a formatted pooler trace event with one argument if pooler tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the pooler trace message. + /// The first argument to format into the message. [NonEvent] public void TryPoolerTraceEvent(string message, T0 args0) { @@ -774,6 +1000,11 @@ public void TryPoolerTraceEvent(string message, T0 args0) /// /// Writes a formatted pooler trace event with two arguments if pooler tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the pooler trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void TryPoolerTraceEvent(string message, T0 args0, T1 args1) { @@ -786,6 +1017,13 @@ public void TryPoolerTraceEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted pooler trace event with three arguments if pooler tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the pooler trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void TryPoolerTraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -798,6 +1036,15 @@ public void TryPoolerTraceEvent(string message, T0 args0, T1 args1, /// /// Writes a formatted pooler trace event with four arguments if pooler tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the pooler trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void TryPoolerTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -812,6 +1059,10 @@ public void TryPoolerTraceEvent(string message, T0 args0, T1 arg /// /// Enters a pooler scope with one formatted argument if pooler scope tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the pooler scope message. + /// The first argument to format into the message. + /// The scope identifier, or 0 if pooler scope tracing is not enabled. [NonEvent] public long TryPoolerScopeEnterEvent(string message, T0 args0) { @@ -825,6 +1076,7 @@ public long TryPoolerScopeEnterEvent(string message, T0 args0) /// /// Leaves a pooler scope if pooler scope tracing is enabled. /// + /// The scope identifier returned by a previous pooler scope enter call. [NonEvent] public void TryPoolerScopeLeaveEvent(long scopeId) { @@ -841,6 +1093,9 @@ public void TryPoolerScopeLeaveEvent(long scopeId) /// /// Writes a formatted advanced trace event with one argument. /// + /// The type of the first argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. [NonEvent] public void AdvancedTraceEvent(string message, T0 args0) { @@ -850,6 +1105,11 @@ public void AdvancedTraceEvent(string message, T0 args0) /// /// Writes a formatted advanced trace event with two arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void AdvancedTraceEvent(string message, T0 args0, T1 args1) { @@ -859,6 +1119,13 @@ public void AdvancedTraceEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted advanced trace event with three arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void AdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -868,6 +1135,15 @@ public void AdvancedTraceEvent(string message, T0 args0, T1 args1, T /// /// Writes a formatted advanced trace event with four arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void AdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -879,6 +1155,7 @@ public void AdvancedTraceEvent(string message, T0 args0, T1 args /// /// Writes an advanced trace event if advanced tracing is enabled. /// + /// The advanced trace message. [NonEvent] public void TryAdvancedTraceEvent(string message) { @@ -891,6 +1168,9 @@ public void TryAdvancedTraceEvent(string message) /// /// Writes a formatted advanced trace event with one argument if advanced tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0) { @@ -903,6 +1183,11 @@ public void TryAdvancedTraceEvent(string message, T0 args0) /// /// Writes a formatted advanced trace event with two arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1) { @@ -915,6 +1200,13 @@ public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted advanced trace event with three arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -927,6 +1219,15 @@ public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1 /// /// Writes a formatted advanced trace event with four arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -939,6 +1240,17 @@ public void TryAdvancedTraceEvent(string message, T0 args0, T1 a /// /// Writes a formatted advanced trace event with five arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4) { @@ -951,6 +1263,19 @@ public void TryAdvancedTraceEvent(string message, T0 args0, /// /// Writes a formatted advanced trace event with six arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5) { @@ -963,6 +1288,23 @@ public void TryAdvancedTraceEvent(string message, T0 arg /// /// Writes a formatted advanced trace event with eight arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// The type of the seventh argument. + /// The type of the eighth argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. + /// The seventh argument to format into the message. + /// The eighth argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5, T6 args6, T7 args7) { @@ -975,6 +1317,21 @@ public void TryAdvancedTraceEvent(string message /// /// Writes a formatted advanced trace event with seven arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// The type of the seventh argument. + /// A composite format string for the advanced trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. + /// The seventh argument to format into the message. [NonEvent] public void TryAdvancedTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5, T6 args6) { @@ -987,6 +1344,10 @@ public void TryAdvancedTraceEvent(string message, T0 /// /// Enters an advanced scope with one formatted argument if advanced tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the advanced scope message. + /// The first argument to format into the message. + /// The scope identifier, or 0 if advanced tracing is not enabled. [NonEvent] public long TryAdvancedScopeEnterEvent(string message, T0 args0) { @@ -1000,6 +1361,7 @@ public long TryAdvancedScopeEnterEvent(string message, T0 args0) /// /// Leaves an advanced scope if advanced tracing is enabled. /// + /// The scope identifier returned by a previous advanced scope enter call. [NonEvent] public void TryAdvanceScopeLeave(long scopeId) { @@ -1012,6 +1374,13 @@ public void TryAdvanceScopeLeave(long scopeId) /// /// Writes a formatted advanced trace binary event with three arguments if advanced binary tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument (may be for hex formatting). + /// The type of the third argument. + /// A composite format string for the advanced trace binary message. + /// The first argument to format into the message. + /// The second argument to format into the message. If this is a byte[], it is formatted as a hex string. + /// The third argument to format into the message. [NonEvent] public void TryAdvancedTraceBinEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -1031,6 +1400,17 @@ public void TryAdvancedTraceBinEvent(string message, T0 args0, T1 ar /// /// Writes a formatted advanced trace error event with five arguments if advanced tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// A composite format string for the advanced trace error message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. [NonEvent] public void TryAdvancedTraceErrorEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4) { @@ -1048,6 +1428,7 @@ public void TryAdvancedTraceErrorEvent(string message, T0 ar /// /// Writes a correlation trace event if correlation tracing is enabled. /// + /// The correlation trace message. [NonEvent] public void TryCorrelationTraceEvent(string message) { @@ -1060,6 +1441,9 @@ public void TryCorrelationTraceEvent(string message) /// /// Writes a formatted correlation trace event with one argument if correlation tracing is enabled. /// + /// The type of the first argument. + /// A composite format string for the correlation trace message. + /// The first argument to format into the message. [NonEvent] public void TryCorrelationTraceEvent(string message, T0 args0) { @@ -1072,6 +1456,11 @@ public void TryCorrelationTraceEvent(string message, T0 args0) /// /// Writes a formatted correlation trace event with two arguments if correlation tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the correlation trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void TryCorrelationTraceEvent(string message, T0 args0, T1 args1) { @@ -1084,6 +1473,13 @@ public void TryCorrelationTraceEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted correlation trace event with three arguments if correlation tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the correlation trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void TryCorrelationTraceEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -1096,6 +1492,15 @@ public void TryCorrelationTraceEvent(string message, T0 args0, T1 ar /// /// Writes a formatted correlation trace event with four arguments if correlation tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// A composite format string for the correlation trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. [NonEvent] public void TryCorrelationTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3) { @@ -1108,6 +1513,17 @@ public void TryCorrelationTraceEvent(string message, T0 args0, T /// /// Writes a formatted correlation trace event with five arguments if correlation tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// A composite format string for the correlation trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. [NonEvent] public void TryCorrelationTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4) { @@ -1120,6 +1536,19 @@ public void TryCorrelationTraceEvent(string message, T0 args /// /// Writes a formatted correlation trace event with six arguments if correlation tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// A composite format string for the correlation trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. [NonEvent] public void TryCorrelationTraceEvent(string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5) { @@ -1134,6 +1563,11 @@ public void TryCorrelationTraceEvent(string message, T0 /// /// Writes a formatted state dump event with two arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the state dump message. + /// The first argument to format into the message. + /// The second argument to format into the message. [NonEvent] public void StateDumpEvent(string message, T0 args0, T1 args1) { @@ -1143,6 +1577,13 @@ public void StateDumpEvent(string message, T0 args0, T1 args1) /// /// Writes a formatted state dump event with three arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// A composite format string for the state dump message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. [NonEvent] public void StateDumpEvent(string message, T0 args0, T1 args1, T2 args2) { @@ -1154,6 +1595,10 @@ public void StateDumpEvent(string message, T0 args0, T1 args1, T2 ar /// /// Writes an SNI trace event if SNI tracing is enabled. /// + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// The SNI trace message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, [CallerMemberName] string memberName = "") { @@ -1166,6 +1611,12 @@ public void TrySNITraceEvent(string className, string eventType, string message, /// /// Writes a formatted SNI trace event with one argument if SNI tracing is enabled. /// + /// The type of the first argument. + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// A composite format string for the SNI trace message. + /// The first argument to format into the message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, T0 args0, [CallerMemberName] string memberName = "") { @@ -1178,6 +1629,14 @@ public void TrySNITraceEvent(string className, string eventType, string mess /// /// Writes a formatted SNI trace event with two arguments if SNI tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// A composite format string for the SNI trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, T0 args0, T1 args1, [CallerMemberName] string memberName = "") { @@ -1190,6 +1649,16 @@ public void TrySNITraceEvent(string className, string eventType, string /// /// Writes a formatted SNI trace event with three arguments if SNI tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// A composite format string for the SNI trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, T0 args0, T1 args1, T2 args2, [CallerMemberName] string memberName = "") { @@ -1202,6 +1671,18 @@ public void TrySNITraceEvent(string className, string eventType, str /// /// Writes a formatted SNI trace event with four arguments if SNI tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// A composite format string for the SNI trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, T0 args0, T1 args1, T2 args2, T3 args3, [CallerMemberName] string memberName = "") { @@ -1214,6 +1695,20 @@ public void TrySNITraceEvent(string className, string eventType, /// /// Writes a formatted SNI trace event with five arguments if SNI tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// A composite format string for the SNI trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, [CallerMemberName] string memberName = "") { @@ -1226,6 +1721,22 @@ public void TrySNITraceEvent(string className, string eventT /// /// Writes a formatted SNI trace event with six arguments if SNI tracing is enabled. /// + /// The type of the first argument. + /// The type of the second argument. + /// The type of the third argument. + /// The type of the fourth argument. + /// The type of the fifth argument. + /// The type of the sixth argument. + /// The name of the class writing the SNI trace. + /// The event type label (e.g., or ). + /// A composite format string for the SNI trace message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// The third argument to format into the message. + /// The fourth argument to format into the message. + /// The fifth argument to format into the message. + /// The sixth argument to format into the message. + /// The name of the calling member (auto-populated by the compiler). [NonEvent] public void TrySNITraceEvent(string className, string eventType, string message, T0 args0, T1 args1, T2 args2, T3 args3, T4 args4, T5 args5, [CallerMemberName] string memberName = "") { @@ -1240,6 +1751,9 @@ public void TrySNITraceEvent(string className, string ev /// /// Enters an SNI scope if SNI scope tracing is enabled. /// + /// The name of the class entering the SNI scope. + /// The name of the calling member (auto-populated by the compiler). + /// The scope identifier, or 0 if SNI scope tracing is not enabled. [NonEvent] public long TrySNIScopeEnterEvent(string className, [CallerMemberName] string memberName = "") { @@ -1255,6 +1769,7 @@ public long TrySNIScopeEnterEvent(string className, [CallerMemberName] string me /// /// Leaves an SNI scope if SNI scope tracing is enabled. /// + /// The scope identifier returned by a previous SNI scope enter call. [NonEvent] public void TrySNIScopeLeaveEvent(long scopeId) { @@ -1268,24 +1783,33 @@ public void TrySNIScopeLeaveEvent(long scopeId) #endregion #region Write Events - // Do not change the first 4 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format, + // Do not change the first 4 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format, // unless you have checked with them and they are able to change their design. Additional items could be added at the end. /// /// Writes a BeginExecute event. /// + /// The object identifier of the command. + /// The data source (server) name. + /// The database name. + /// The SQL command text being executed. + /// A formatted trace message with additional context. [Event(BeginExecuteEventId, Keywords = Keywords.ExecutionTrace, Task = Tasks.ExecuteCommand, Opcode = EventOpcode.Start)] public void BeginExecute(int objectId, string dataSource, string database, string commandText, string message) { WriteEvent(BeginExecuteEventId, objectId, dataSource, database, commandText, message); } - // Do not change the first 3 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format, + // Do not change the first 3 arguments in this Event writer as OpenTelemetry and ApplicationInsight are relating to the same format, // unless you have checked with them and they are able to change their design. Additional items could be added at the end. /// /// Writes an EndExecute event. /// + /// The object identifier of the command. + /// The composite state of the command at completion. + /// The SQL exception number, or 0 if no exception occurred. + /// A formatted trace message with additional context. [Event(EndExecuteEventId, Keywords = Keywords.ExecutionTrace, Task = Tasks.ExecuteCommand, Opcode = EventOpcode.Stop)] public void EndExecute(int objectId, int compositestate, int sqlExceptionNumber, string message) { @@ -1295,6 +1819,7 @@ public void EndExecute(int objectId, int compositestate, int sqlExceptionNumber, /// /// Writes a Trace event. /// + /// The trace message. [Event(TraceEventId, Level = EventLevel.Informational, Keywords = Keywords.Trace)] public void Trace(string message) => WriteEvent(TraceEventId, message); @@ -1302,6 +1827,8 @@ public void Trace(string message) => /// /// Enters a scope. /// + /// A composite format string containing the scope identifier placeholder. + /// The assigned scope identifier. [Event(ScopeEnterId, Level = EventLevel.Informational, Task = Tasks.Scope, Opcode = EventOpcode.Start, Keywords = Keywords.Scope)] public long ScopeEnter(string message) { @@ -1313,6 +1840,7 @@ public long ScopeEnter(string message) /// /// Leaves a scope. /// + /// The scope exit message. [Event(ScopeExitId, Level = EventLevel.Informational, Task = Tasks.Scope, Opcode = EventOpcode.Stop, Keywords = Keywords.Scope)] public void ScopeLeave(string message) => WriteEvent(ScopeExitId, message); @@ -1320,6 +1848,7 @@ public void ScopeLeave(string message) => /// /// Writes a notification trace event. /// + /// The notification trace message. [Event(NotificationTraceId, Level = EventLevel.Informational, Keywords = Keywords.NotificationTrace)] public void NotificationTrace(string message) => WriteEvent(NotificationTraceId, message); @@ -1327,6 +1856,8 @@ public void NotificationTrace(string message) => /// /// Enters a notification scope. /// + /// A composite format string containing the scope identifier placeholder. + /// The assigned scope identifier. [Event(NotificationScopeEnterId, Level = EventLevel.Informational, Task = Tasks.NotificationScope, Opcode = EventOpcode.Start, Keywords = Keywords.NotificationScope)] public long NotificationScopeEnter(string message) { @@ -1338,6 +1869,7 @@ public long NotificationScopeEnter(string message) /// /// Leaves a notification scope. /// + /// The notification scope exit message. [Event(NotificationScopeExitId, Level = EventLevel.Informational, Task = Tasks.NotificationScope, Opcode = EventOpcode.Stop, Keywords = Keywords.NotificationScope)] public void NotificationScopeLeave(string message) => WriteEvent(NotificationScopeExitId, message); @@ -1345,6 +1877,7 @@ public void NotificationScopeLeave(string message) => /// /// Writes a pooler trace event. /// + /// The pooler trace message. [Event(PoolerTraceId, Level = EventLevel.Informational, Keywords = Keywords.PoolerTrace)] public void PoolerTrace(string message) => WriteEvent(PoolerTraceId, message); @@ -1352,6 +1885,8 @@ public void PoolerTrace(string message) => /// /// Enters a pooler scope. /// + /// A composite format string containing the scope identifier placeholder. + /// The assigned scope identifier. [Event(PoolerScopeEnterId, Level = EventLevel.Informational, Task = Tasks.PoolerScope, Opcode = EventOpcode.Start, Keywords = Keywords.PoolerScope)] public long PoolerScopeEnter(string message) { @@ -1363,6 +1898,7 @@ public long PoolerScopeEnter(string message) /// /// Leaves a pooler scope. /// + /// The pooler scope exit message. [Event(PoolerScopeExitId, Level = EventLevel.Informational, Task = Tasks.PoolerScope, Opcode = EventOpcode.Stop, Keywords = Keywords.PoolerScope)] public void PoolerScopeLeave(string message) => WriteEvent(PoolerScopeExitId, message); @@ -1370,6 +1906,7 @@ public void PoolerScopeLeave(string message) => /// /// Writes an advanced trace event. /// + /// The advanced trace message. [Event(AdvancedTraceId, Level = EventLevel.Verbose, Keywords = Keywords.AdvancedTrace)] public void AdvancedTrace(string message) => WriteEvent(AdvancedTraceId, message); @@ -1377,6 +1914,8 @@ public void AdvancedTrace(string message) => /// /// Enters an advanced scope. /// + /// A composite format string containing the scope identifier placeholder. + /// The assigned scope identifier. [Event(AdvancedScopeEnterId, Level = EventLevel.Verbose, Opcode = EventOpcode.Start, Keywords = Keywords.AdvancedTrace)] public long AdvancedScopeEnter(string message) { @@ -1388,6 +1927,7 @@ public long AdvancedScopeEnter(string message) /// /// Leaves an advanced scope. /// + /// The advanced scope exit message. [Event(AdvancedScopeExitId, Level = EventLevel.Verbose, Opcode = EventOpcode.Stop, Keywords = Keywords.AdvancedTrace)] public void AdvancedScopeLeave(string message) => WriteEvent(AdvancedScopeExitId, message); @@ -1395,6 +1935,7 @@ public void AdvancedScopeLeave(string message) => /// /// Writes an advanced trace binary event. /// + /// The advanced trace binary message. [Event(AdvancedTraceBinId, Level = EventLevel.Verbose, Keywords = Keywords.AdvancedTraceBin)] public void AdvancedTraceBin(string message) => WriteEvent(AdvancedTraceBinId, message); @@ -1402,6 +1943,7 @@ public void AdvancedTraceBin(string message) => /// /// Writes an advanced trace error event. /// + /// The advanced trace error message. [Event(AdvancedTraceErrorId, Level = EventLevel.Error, Keywords = Keywords.AdvancedTrace)] public void AdvancedTraceError(string message) => WriteEvent(AdvancedTraceErrorId, message); @@ -1409,6 +1951,7 @@ public void AdvancedTraceError(string message) => /// /// Writes a correlation trace event. /// + /// The correlation trace message. [Event(CorrelationTraceId, Level = EventLevel.Informational, Keywords = Keywords.CorrelationTrace)] public void CorrelationTrace(string message) => WriteEvent(CorrelationTraceId, message); @@ -1416,6 +1959,7 @@ public void CorrelationTrace(string message) => /// /// Writes a state dump event. /// + /// The state dump message. [Event(StateDumpEventId, Level = EventLevel.Verbose, Keywords = Keywords.StateDump)] public void StateDump(string message) => WriteEvent(StateDumpEventId, message); @@ -1423,6 +1967,7 @@ public void StateDump(string message) => /// /// Writes an SNI trace event. /// + /// The SNI trace message. [Event(SNITraceEventId, Level = EventLevel.Informational, Keywords = Keywords.SNITrace)] public void SNITrace(string message) => WriteEvent(SNITraceEventId, message); @@ -1430,6 +1975,8 @@ public void SNITrace(string message) => /// /// Enters an SNI scope. /// + /// A composite format string containing the scope identifier placeholder. + /// The assigned scope identifier. [Event(SNIScopeEnterId, Level = EventLevel.Informational, Task = Tasks.SNIScope, Opcode = EventOpcode.Start, Keywords = Keywords.SNIScope)] public long SNIScopeEnter(string message) { @@ -1441,6 +1988,7 @@ public long SNIScopeEnter(string message) /// /// Leaves an SNI scope. /// + /// The SNI scope exit message. [Event(SNIScopeExitId, Level = EventLevel.Informational, Task = Tasks.SNIScope, Opcode = EventOpcode.Stop, Keywords = Keywords.SNIScope)] public void SNIScopeLeave(string message) => WriteEvent(SNIScopeExitId, message); @@ -1450,6 +1998,11 @@ public void SNIScopeLeave(string message) => /// /// Constants for event type labels used in formatted event messages. /// + /// + /// These constants are used as the eventType parameter in SNI trace methods + /// such as + /// to categorize events as informational or error level. + /// public static class EventType { /// @@ -1523,21 +2076,36 @@ public void Dispose() /// /// Creates a new event scope with one formatted argument. /// + /// The type of the first argument. + /// A composite format string for the scope message. + /// The first argument to format into the message. + /// A new instance. public static SqlClientEventScope Create(string message, T0 args0) => new SqlClientEventScope(SqlClientEventSource.Log.TryScopeEnterEvent(message, args0)); /// /// Creates a new event scope with two formatted arguments. /// + /// The type of the first argument. + /// The type of the second argument. + /// A composite format string for the scope message. + /// The first argument to format into the message. + /// The second argument to format into the message. + /// A new instance. public static SqlClientEventScope Create(string message, T0 args0, T1 args1) => new SqlClientEventScope(SqlClientEventSource.Log.TryScopeEnterEvent(message, args0, args1)); /// /// Creates a new event scope for a class with the calling member name. /// + /// The name of the class entering the scope. + /// The name of the calling member (auto-populated by the compiler). + /// A new instance. public static SqlClientEventScope Create(string className, [CallerMemberName] string memberName = "") => new SqlClientEventScope(SqlClientEventSource.Log.TryScopeEnterEvent(className, memberName)); /// /// Creates a new event scope with a pre-existing scope identifier. /// + /// The scope identifier to wrap. + /// A new instance. public static SqlClientEventScope Create(long scopeId) => new SqlClientEventScope(scopeId); } } From 2fa363d806ea7802b0dc75bdc07eef889f73e1eb Mon Sep 17 00:00:00 2001 From: Apoorv Deshmukh Date: Mon, 9 Mar 2026 21:49:13 +0530 Subject: [PATCH 2/3] Address review comments --- .../Logging/src/Logging.csproj | 21 ++++++++++++------- .../Logging/src/SqlClientEventSource.cs | 13 +++++++++++- 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj index ba66e7558b..4f346025c8 100644 --- a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj +++ b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/Logging.csproj @@ -89,8 +89,10 @@ Microsoft.Data.SqlClient.Extensions.Logging Microsoft Microsoft Corporation - Microsoft.Data.SqlClient Extensions Logging - ETW EventSource for SqlClient tracing - and diagnostics. + + Microsoft.Data.SqlClient Extensions Logging - ETW EventSource for SqlClient tracing + and diagnostics. + © Microsoft Corporation. All rights reserved. sqlclient microsoft.data.sqlclient extensions logging git @@ -135,14 +137,19 @@ DestinationFolder="$(Artifacts)/doc/$(TargetFramework)/" /> + + + powershell.exe + pwsh + + - + Command="$(PowerShellCmd) -NonInteractive -ExecutionPolicy Unrestricted -Command "$(ToolsDir)intellisense\TrimDocs.ps1 -inputFile '$(DocumentationFile)' -outputFile '$(DocumentationFile)'"" /> \ No newline at end of file diff --git a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs index 86ac7adba5..70ff6f899a 100644 --- a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs +++ b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs @@ -25,12 +25,23 @@ namespace Microsoft.Data.SqlClient /// independently to control the verbosity and scope of tracing. Use the singleton /// instance to write events and query enablement status. /// + /// + /// Note: This API surface is primarily intended for internal use by the + /// Microsoft.Data.SqlClient driver. While public, it may be modified or reduced in future + /// versions without following the standard breaking-change deprecation policy. + /// /// /// Enable ETW tracing with PerfView: /// /// PerfView.exe collect /Providers=*Microsoft.Data.SqlClient.EventSource /// /// + /// + /// Collect traces with dotnet-trace: + /// + /// dotnet-trace collect -p <PID> --providers Microsoft.Data.SqlClient.EventSource:1FFF:5 + /// + /// /// [EventSource(Name = "Microsoft.Data.SqlClient.EventSource")] public class SqlClientEventSource : EventSource @@ -1375,7 +1386,7 @@ public void TryAdvanceScopeLeave(long scopeId) /// Writes a formatted advanced trace binary event with three arguments if advanced binary tracing is enabled. /// /// The type of the first argument. - /// The type of the second argument (may be for hex formatting). + /// The type of the second argument (may be byte[] for hex formatting). /// The type of the third argument. /// A composite format string for the advanced trace binary message. /// The first argument to format into the message. From d9b87414c6a012f021ddc06b0cd6be5516df4f09 Mon Sep 17 00:00:00 2001 From: Apoorv Deshmukh Date: Mon, 9 Mar 2026 22:16:39 +0530 Subject: [PATCH 3/3] Make changes as per doc guidelines --- .../Logging/src/SqlClientEventSource.cs | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs index 70ff6f899a..eec914eba8 100644 --- a/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs +++ b/src/Microsoft.Data.SqlClient.Extensions/Logging/src/SqlClientEventSource.cs @@ -52,7 +52,7 @@ public class SqlClientEventSource : EventSource public static readonly SqlClientEventSource Log = new(); /// - /// A callback that is invoked when the EventSource receives an Enable command. + /// Gets or sets a callback that is invoked when the EventSource receives an Enable command. /// Can be used to hook metrics or other subsystems that need to respond to EventSource enablement. /// public static Action? OnEventSourceEnabled { get; set; } @@ -99,97 +99,97 @@ protected override void OnEventCommand(EventCommandEventArgs command) private const int EndExecuteEventId = 2; /// - /// Defines EventId for Trace() events + /// Defines EventId for Trace() events. /// private const int TraceEventId = 3; /// - /// Defines EventId for ScopeEnter() events + /// Defines EventId for ScopeEnter() events. /// private const int ScopeEnterId = 4; /// - /// Defines EventId for ScopeLeave() events + /// Defines EventId for ScopeLeave() events. /// private const int ScopeExitId = 5; /// - /// Defines EventId for NotificationScopeEnter() events + /// Defines EventId for NotificationScopeEnter() events. /// private const int NotificationScopeEnterId = 6; /// - /// Defines EventId for NotificationScopeLeave() events + /// Defines EventId for NotificationScopeLeave() events. /// private const int NotificationScopeExitId = 7; /// - /// Defines EventId for NotificationScopeTrace() events + /// Defines EventId for NotificationScopeTrace() events. /// private const int NotificationTraceId = 8; /// - /// Defines EventId for PoolerScopeEnter() events + /// Defines EventId for PoolerScopeEnter() events. /// private const int PoolerScopeEnterId = 9; /// - /// Defines EventId for PoolerScopeLeave() events + /// Defines EventId for PoolerScopeLeave() events. /// private const int PoolerScopeExitId = 10; /// - /// Defines EventId for PoolerTrace() events + /// Defines EventId for PoolerTrace() events. /// private const int PoolerTraceId = 11; /// - /// Defines EventId for AdvancedTrace() events + /// Defines EventId for AdvancedTrace() events. /// private const int AdvancedTraceId = 12; /// - /// Defines EventId for AdvancedScopeEnter() events + /// Defines EventId for AdvancedScopeEnter() events. /// private const int AdvancedScopeEnterId = 13; /// - /// Defines EventId for AdvancedScopeLeave() events + /// Defines EventId for AdvancedScopeLeave() events. /// private const int AdvancedScopeExitId = 14; /// - /// Defines EventId for AdvancedTraceBin() events + /// Defines EventId for AdvancedTraceBin() events. /// private const int AdvancedTraceBinId = 15; /// - /// Defines EventId for AdvancedTraceError() events + /// Defines EventId for AdvancedTraceError() events. /// private const int AdvancedTraceErrorId = 16; /// - /// Defines EventId for CorrelationTrace() events + /// Defines EventId for CorrelationTrace() events. /// private const int CorrelationTraceId = 17; /// - /// Defines EventId for StateDump() events + /// Defines EventId for StateDump() events. /// private const int StateDumpEventId = 18; /// - /// Defines EventId for SNITrace() events + /// Defines EventId for SNITrace() events. /// private const int SNITraceEventId = 19; /// - /// Defines EventId for SNIEnterScope() events + /// Defines EventId for SNIEnterScope() events. /// private const int SNIScopeEnterId = 20; /// - /// Defines EventId for SNIExitScope() events + /// Defines EventId for SNIExitScope() events. /// private const int SNIScopeExitId = 21; #endregion