UseFonlowHubTraceListener

Use Fonlow.HubTraceListener

Fonlow.HubTraceListener is derived from Essential.Diagnostics.TraceListenerBase, thus it inherits all good features of structured diagnostic logging. The formatted trace messages will be sent to Trace Hub along with other structured info, and then will be displayed in the Web UI or the TraceHub Console.

If you are building a program, you may use NuGet package Fonlow.HubTraceListener.

If you want existing .NET applications to upload traces to TraceHub, just copy the list of files below to the program directory.

File List:

• .NET Framework 4.5
• Fonlow.HubTraceListener.dll
• Fonlow.TraceHub.Common
• Essential.Diagnostics.dll
• Microsoft.AspNet.SignalR.Client.dll
• Newtonsoft.Json.dll

To enable your .NET service applications to write traces to Trace Hub, after copying respective files listed above to the bin directory or the application directory, simply add the following or alike to app.config:

  <system.diagnostics>
    <sharedListeners>
      <add name="hubListener" type="Fonlow.Diagnostics.HubTraceListener, Fonlow.HubTraceListener" 
           template="{Message}{Data}" 
           hubUrl="http://Your.TraceHub.Service" apiUser="api" apiPassword="Aaaaaa*8" instanceId="testListener" />
    </sharedListeners>
    <switches>
      <add name="TraceLevelSwitch" value="Verbose" />
    </switches>
    <sources>
    </sources>
    <trace autoflush="true">
      <listeners>
        <clear />
        <add name="hubListener" />
      </listeners>
    </trace>
  </system.diagnostics>

In addition to attributes of Essential.Diagnostics.TraceListenerBase, here's a list of additional attributes:

1. hubUrl: The URL of your TraceHub Web service.
2. apiUser: A user associated with role "API" in the authentication of Trace Hub. For TraceHub Slim or alike, the apiUser must be "anonymous".
3. apiPassword: Password of apiUser. And this is not used with TraceHub Slim.
4. apiKey: Not yet used. The support for API key will be implemented soon.
5. instanceId: Your custom identification for an instance of the service. This is optional, since ApplicationName could be good enough if you don't have multiple instances of the same service.

Remarks:

HubConnection is working lazy with TraceHub, that is, only when the listener sends the first trace message to TraceHub, the connection is established. Thus, in TraceHub Web UI, when you press the Clients button, you may not see see the existence of the listener if the listener had never send a trace message since TraceHub is started. This is by design, since TraceHub is not a system monitor like Microsoft AI.

The Template Attribute

The template attribute is an addition to derived classes of Essential.Diagnostics.TraceListenerBase, not available in derived classes of System.Diagnostics.

If you don't define a template attribute, the default one may be like "{TimeUTC} [{ThreadId}] {EventType} {Source} {Id}: {Message}", depending on each implementation of the TraceListenerBase derived classes. However, such formatted message may be looking redundant because TraceHub and TraceHub Console will display time and event type in addition to the formatted message from the source applications.

Among all the available parameters of template, the follow parameters should not be included in the formatting of the trace message:

• DateTime
• LocalDateTime
• EventType
• Id
• Source

HubTraceListener will upload these info in a DTO to TraceHub.

Nevertheless, if you would inject other derived classes of Essential.Diagnostics.TraceListenerBase such as RollingFileTraceListener to your service appplications, please feel free to use whatever parameters available for the template attribute.

Extending TraceHub

While TraceHub is designed not to persist traces, however is designed to interface with trace listeners which may persist traces.

TraceHub will typically display EventType, Local Time / UTC Time and Origin (InstanceId) in the Web page.

TraceHub Console will display a trace line as "{Source} {EventType}: {Id}: {DateTimeUTC} [Origin]: {Message}".

Derived classes of System.Diagnostics.TraceListener will typically emit formatted message like "{Source} {EventType}: {Id}: {Message}". And the message reformatted by TraceHub Console is like "{DateTimeUTC} [Origin]: {Message}". So when you inject a trace listener to TraceHub Console, the listener will typically emit "{Source} {EventType}: {Id}: {DateTimeUTC} [Origin]: {Message}".

Remarks:

When you inject a derived class of Essential.Diagnostics.TraceListenerBase into TraceHub Console, you shall not define the template attribute. Generally the formatting of structural info of trace should be defined in the template attribute of HubTraceListener injected to the source applications.

Troubleshooting

The beauty of using a trace listener injected through app.config is, the trace listener can pick up error traces before the first line of application codes is run during startup. However, negotiating for the initial connection with Trace Hub in another computer takes time. HuTraceListner can buffer up to 100,000 trace messages, and will send them out as soon as the connection with the Hub is available.

Connection lost with Trace Hub

By default, the SignalR connection object in HubTraceListener will retry up to 7 times to reconnect. If all retries failed, the connection object will be in the disconnected state permanently. HubListener is smart enough to retry every 20 seconds with a new SignalR connection object.

What if the program crashed before being able to upload traces?

Surely the in-process buffer of traces will be lost. It is reasonable to additionally have a file base trace listener like RollingFileTraceListener to keep a copy if the logging is critical for diagnosing. And a pending issue is created in the roadmap of TraceHub for retrieving log files without using logon to server or using FTP.