Prerequisites

To log information directly using the Loupe API you need to add the Loupe API Package to your application

<dependency>
    <groupId>com.onloupe</groupId>
    <artifactId>loupe-api</artifactId>
    <version><-- desired version --></version>
</dependency>

Better Logging

If you aren't trying to quickly convert from Trace to using the Loupe Log API directly the best interface is a set of direct methods broken out by severity:

Loupe.critical / Loupe.error / Loupe.warning / Loupe.information / Loupe.verbose: These methods provide multiple variations to fit specific data scenarios.
Loupe.criticalDetail / Loupe.errorDetail / Loupe.warningDetail / Loupe.informationDetail / Loupe.verboseDetail: These methods mirror the ones above but provide an additional XML Detail field that can store structured data for display in Loupe Desktop.
Loupe.recordException and Loupe.reportException offer specific features designed for top level exception handling and other scenarios where you don't want to write a custom tailored exception handler message but are catching an exception.

Logging Direct to Loupe	Copy Code
public void betterLogSample() { Loupe.critical("Period.Delimited.Category", "This is a critical problem", "We are writing a test message with multiple insertion strings: %s %d %s", "string", 124, LocalDateTime.now()); Loupe.warning("Period.Delimited.Category", "This might be a problem problem", "You don't have to provide insertion strings if you don't want to"); // Any of the different severities can include details of an exception. Don't // bother // dumping it in the message area; it'll all be showing in the Loupe Desktop // under the Exception. Exception ex = new IllegalArgumentException("This is an example invalid operation exception"); Loupe.error(ex, null, "Your Application.Exceptions", "We had an odd exception but managed to recover", "Here's a description of what we were doing. We don't need to provide exception data."); // If you think the application might crash immediately after you call to record // the message // you might want to make just this message synchronous. Loupe.critical(LogWriteMode.WAIT_FOR_COMMIT, "Your.Category", "We had a problem and may crash", "Just like our first method above we can now provide extended detail with insertion strings"); Loupe.verbose("Your.Category", "This is our lowest severity message", "Verbose is like a debug or success message - below all other severities."); }

Logging Direct to Loupe

Copy Code

public void betterLogSample() {
    Loupe.critical("Period.Delimited.Category", "This is a critical problem",
            "We are writing a test message with multiple insertion strings: %s %d %s", "string", 124,
            LocalDateTime.now());
    Loupe.warning("Period.Delimited.Category", "This might be a problem problem",
            "You don't have to provide insertion strings if you don't want to");
    
    // Any of the different severities can include details of an exception. Don't
    // bother
    // dumping it in the message area; it'll all be showing in the Loupe Desktop
    // under the Exception.
    Exception ex = new IllegalArgumentException("This is an example invalid operation exception");
    Loupe.error(ex, null, "Your Application.Exceptions", "We had an odd exception but managed to recover",
            "Here's a description of what we were doing.  We don't need to provide exception data.");
    
    // If you think the application might crash immediately after you call to record
    // the message
    // you might want to make just this message synchronous.
    Loupe.critical(LogWriteMode.WAIT_FOR_COMMIT, "Your.Category", "We had a problem and may crash",
            "Just like our first method above we can now provide extended detail with insertion strings");
    Loupe.verbose("Your.Category", "This is our lowest severity message",
            "Verbose is like a debug or success message - below all other severities.");
}

Using your own Central Log Class

If you already have a central logging class you can gateway calls into Loupe by using the Write methods.

Advanced Logging Direct to Loupe	Copy Code
private void logDirectAdvancedSample() { // One special case is for important messages that you need committed to disk // before continuing // such as when logging during an unhandled exception. There is a performance // penalty, so this option // is not set by default. Exception ex = new IllegalArgumentException("This is an example invalid operation exception"); Log.write(LogMessageSeverity.CRITICAL, LogWriteMode.WAIT_FOR_COMMIT, ex, "Your.Category", "This log message is a special case", "It will not return until the log message is committed to disk"); // and the variation with passing exceptions and additional parameters to insert // are also supported. // see the documentation for Log.Write for other overloads. }

Advanced Logging Direct to Loupe

Copy Code

private void logDirectAdvancedSample() {
    // One special case is for important messages that you need committed to disk
    // before continuing
    // such as when logging during an unhandled exception. There is a performance
    // penalty, so this option
    // is not set by default.
    Exception ex = new IllegalArgumentException("This is an example invalid operation exception");
    Log.write(LogMessageSeverity.CRITICAL, LogWriteMode.WAIT_FOR_COMMIT, ex, "Your.Category",
            "This log message is a special case", "It will not return until the log message is committed to disk");
    // and the variation with passing exceptions and additional parameters to insert
    // are also supported.
    // see the documentation for Log.Write for other overloads.
}

For the most advanced functionality (used primarily when bridging data from a foreign log system into Loupe, such as Log4j2 and Logback) you can use the WriteMessage methods. These require the most work but delegate the most capability to your code.

Developer's Guide

Log Class

Send Feedback