Loupe - Log - Monitor - Resolve
Loupe / Developer's Guide / For .NET Core / 6 / 8 / Logging / Using with Other Log Systems / Using Microsoft.Extensions.Logging with Loupe / Developer's Reference - Microsoft.Extensions.Logging Optimizing for Loupe
In This Topic
    Developer's Reference - Microsoft.Extensions.Logging Optimizing for Loupe
    In This Topic

    Loupe provides a great experience out-of-the-box with Microsoft.Extensions.Logging (MEL) however there are a few steps you can take to provide the best experience.

     Separate Caption & Description for Errors & Warnings

    Loupe supports a distinct Caption & Description text field for a message while MEL uses only a single message field.  In this scenario, Loupe looks for the first Carriage Return (\r) or Line Feed (\f) and treats the message up to that as the caption and everything after that as the description.

    This is particularly important for Critical, Error, and Warning messages as the caption is part of how Loupe groups log messages together into events. So, if a log messages use insertion stings it's important to be cautious about doing that before the first CRLF so the message isn't overly unique.

    For example, don't insert any of these things before the first CRLF:

    • Timestamp or Date (Note: Loupe adds the message timestamp automatically)
    • IP Address
    • URL
    • File Name
    • File Size or Position

    Any of these can be put in the description without issue. 

    Some things make sense to be put in the first line because they definitely should be considered part of the event - like an exception type.

    Example Optimized Messages
    Copy Code
    logger.LogCritical(ex,
        "Unable to keep running this application due to an {Exception}\r\n" +
        "Now that we're on the second line, here's more information we can share " +
        "that won't cause an overly-unique message: " +
        "{Order}, {OrderQuantity:N0}, {OrderTimestamp:g}", ex.GetType().Name,
        firstVal, secondVal, thirdVal);
    logger.LogError(ex,
        "Unable to complete the action we were performing due to an {Exception}\r\n" +
        "Errors are for when the current activity can't complete successfully but the " +
        "application can continue to process requests.", ex.GetType().Name);
    logger.LogWarning(ex,
        "It is very suspicious that we caught an {Exception}\r\n" +
        "Since we think we can handle this and continue with the current activity " +
        "(perhaps by doing a retry) we won't record it as an error.",
        ex.GetType().Name);
    
    logger.LogInformation(
        "For an Informational message or lower we don't need to worry about putting " +
        "items in the caption: {Order}, {OrderQuantity:N0}, {OrderTimestamp:g}\r\n" +
        "You can still can have a description field where you go wild with additional " +
        "detail but it's often useful to put distinct information in the caption " +
        "to help in finding the right activity.",
        firstVal, secondVal, thirdVal);
    
     Use Semantic Logging for Building Log Messages

    Traditionally, log messages were built up using format strings or interpolated strings.  MEL (and some other third-party log systems) support Semantic Logging which leverage the name used in the template message to both construct a message by merging the data with the template and record name/value pairs of data for analysis.

    For example, in the following message the data is both inserted and recorded as name/value pairs (displayed in the Details tab in Loupe):

    logger.LogInformation("This message will have three formatted values inserted as semantic logging: " +
                          "{Order}, {OrderQuantity:N0}, {OrderTimestamp:g}",
        firstVal, secondVal, thirdVal);
    

    Semantic logging uses the order the the declaration in the template string to pick the correct argument passed at the end of the message, so in this example "Order" is recorded with the value firstVal, "OrderQuantity" with secondVal, etc. 

    Semantic logging still supports template formatting hints - in the above example, N0 is specified for formatting the OrderQuantity and "g" is specified for formatting the OrderTimestamp.

    For more information on formatting log messages with MEL, see Developer's Reference - Microsoft.Extensions.Logging Message Formatting.

     Use Semantic Logging to Format Messages

    See Also