Skip to content

Commit b35654a

Browse files
mairawmairaw
authored
move long summary to remarks (#3506)
1 parent babd58a commit b35654a

File tree

1 file changed

+73
-64
lines changed

1 file changed

+73
-64
lines changed

‎xml/Microsoft.Extensions.Logging.EventSource/LoggingEventSource.xml

Lines changed: 73 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -19,70 +19,79 @@
1919
</Attribute>
2020
</Attributes>
2121
<Docs>
22-
<summary>
23-
The LoggingEventSource is the bridge from all ILogger based logging to EventSource/EventListener logging.
24-
25-
You turn this logging on by enabling the EventSource called
26-
27-
Microsoft-Extensions-Logging
28-
29-
When you enabled the EventSource, the EventLevel you set is translated in the obvious way to the level
30-
associated with the ILogger (thus Debug = verbose, Informational = Informational ... Critical == Critical)
31-
32-
This allows you to filter by event level in a straightforward way.
33-
34-
For finer control you can specify a EventSource Argument called
35-
36-
FilterSpecs
37-
38-
The FilterSpecs argument is a semicolon separated list of specifications. Where each specification is
39-
40-
SPEC = // empty spec, same as *
41-
| NAME // Just a name the level is the default level
42-
| NAME : LEVEL // specifies level for a particular logger (can have a * suffix).
43-
44-
Where Name is the name of a ILoggger (case matters), Name can have a * which acts as a wildcard
45-
AS A SUFFIX. Thus Net* will match any loggers that start with the 'Net'.
46-
47-
The LEVEL is a number or a LogLevel string. 0=Trace, 1=Debug, 2=Information, 3=Warning, 4=Error, Critical=5
48-
This specifies the level for the associated pattern. If the number is not specified, (first form
49-
of the specification) it is the default level for the EventSource.
50-
51-
First match is used if a particular name matches more than one pattern.
52-
53-
In addition the level and FilterSpec argument, you can also set EventSource Keywords. See the Keywords
54-
definition below, but basically you get to decide if you wish to have
55-
56-
* Keywords.Message - You get the event with the data in parsed form.
57-
* Keywords.JsonMessage - you get an event with the data in parse form but as a JSON blob (not broken up by argument ...)
58-
* Keywords.FormattedMessage - you get an event with the data formatted as a string
59-
60-
It is expected that you will turn only one of these keywords on at a time, but you can turn them all on (and get
61-
the same data logged three different ways.
62-
63-
Example Usage
64-
65-
This example shows how to use an EventListener to get ILogging information
66-
67-
class MyEventListener : EventListener {
68-
protected override void OnEventSourceCreated(EventSource eventSource) {
69-
if (eventSource.Name == "Microsoft-Extensions-Logging") {
70-
// initialize a string, string dictionary of arguments to pass to the EventSource.
71-
// Turn on loggers matching App* to Information, everything else (*) is the default level (which is EventLevel.Error)
72-
var args = new Dictionary&lt;string, string&gt;() { { "FilterSpecs", "App*:Information;*" } };
73-
// Set the default level (verbosity) to Error, and only ask for the formatted messages in this case.
74-
EnableEvents(eventSource, EventLevel.Error, LoggingEventSource.Keywords.FormattedMessage, args);
75-
}
76-
}
77-
protected override void OnEventWritten(EventWrittenEventArgs eventData) {
78-
// Look for the formatted message event, which has the following argument layout (as defined in the LoggingEventSource.
79-
// FormattedMessage(LogLevel Level, int FactoryID, string LoggerName, string EventId, string FormattedMessage);
80-
if (eventData.EventName == "FormattedMessage")
81-
Console.WriteLine("Logger {0}: {1}", eventData.Payload[2], eventData.Payload[4]);
82-
}
83-
}
84-
</summary>
85-
<remarks>To be added.</remarks>
22+
<summary>The LoggingEventSource is the bridge from all ILogger based logging to EventSource/EventListener logging.</summary>
23+
<remarks>
24+
<format type="text/markdown"><![CDATA[
25+
26+
## Remarks
27+
28+
You turn this logging on by enabling the EventSource called `Microsoft-Extensions-Logging`.
29+
30+
When you enabled the EventSource, the EventLevel you set is translated in the obvious way to the level
31+
associated with the ILogger (thus Debug = verbose, Informational = Informational ... Critical == Critical)
32+
33+
This allows you to filter by event level in a straightforward way.
34+
35+
For finer control you can specify a EventSource Argument called `FilterSpecs`.
36+
37+
The `FilterSpecs` argument is a semicolon separated list of specifications. Where each specification is
38+
39+
```
40+
SPEC = // empty spec, same as *
41+
| NAME // Just a name the level is the default level
42+
| NAME : LEVEL // specifies level for a particular logger (can have a * suffix).
43+
```
44+
45+
Where Name is the name of a ILoggger (case matters), Name can have a \* which acts as a wildcard
46+
AS A SUFFIX. Thus, Net\* will match any loggers that start with the 'Net'.
47+
48+
The LEVEL is a number or a LogLevel string. 0=Trace, 1=Debug, 2=Information, 3=Warning, 4=Error, Critical=5
49+
This specifies the level for the associated pattern. If the number is not specified, (first form
50+
of the specification) it is the default level for the EventSource.
51+
52+
First match is used if a particular name matches more than one pattern.
53+
54+
In addition to the level and FilterSpec argument, you can also set EventSource Keywords. See the Keywords
55+
definition below, but basically you get to decide if you wish to have
56+
57+
* Keywords.Message - You get the event with the data in parsed form.
58+
* Keywords.JsonMessage - you get an event with the data in parse form but as a JSON blob (not broken up by argument ...)
59+
* Keywords.FormattedMessage - you get an event with the data formatted as a string
60+
61+
It is expected that you will turn only one of these keywords on at a time, but you can turn them all on and get
62+
the same data logged three different ways.
63+
64+
## Examples
65+
66+
The following example shows how to use an EventListener to get ILogging information:
67+
68+
```csharp
69+
class MyEventListener : EventListener
70+
{
71+
protected override void OnEventSourceCreated(EventSource eventSource)
72+
{
73+
if (eventSource.Name == "Microsoft-Extensions-Logging")
74+
{
75+
// initialize a string, string dictionary of arguments to pass to the EventSource.
76+
// Turn on loggers matching App* to Information, everything else (*) is the default level (which is EventLevel.Error)
77+
var args = new Dictionary&lt;string, string&gt;() { { "FilterSpecs", "App*:Information;*" } };
78+
// Set the default level (verbosity) to Error, and only ask for the formatted messages in this case.
79+
EnableEvents(eventSource, EventLevel.Error, LoggingEventSource.Keywords.FormattedMessage, args);
80+
}
81+
}
82+
83+
protected override void OnEventWritten(EventWrittenEventArgs eventData)
84+
{
85+
// Look for the formatted message event, which has the following argument layout (as defined in the LoggingEventSource.
86+
// FormattedMessage(LogLevel Level, int FactoryID, string LoggerName, string EventId, string FormattedMessage);
87+
if (eventData.EventName == "FormattedMessage")
88+
Console.WriteLine("Logger {0}: {1}", eventData.Payload[2], eventData.Payload[4]);
89+
}
90+
}
91+
```
92+
93+
]]></format>
94+
</remarks>
8695
</Docs>
8796
<Members>
8897
<Member MemberName="OnEventCommand">

0 commit comments

Comments
 (0)