User API for logging

[sergeuz]

This PR adds initial version of the logging API for application-side code.

Basic usage:

#include "application.h"

// Enable logging to primary USB serial
SerialLogHandler logHandler(9600, LOG_LEVEL_ERROR, { // Log only errors by default
    { "app", LOG_LEVEL_ALL } // Log all application messages
});

// Global logger
Logger logger;

void setup() {
    logger.log("My device ID: %s", System.deviceID().c_str()); // Uses default logging level (INFO)

    logger.info("This is info message");
    logger.error("This is error message");

    if (logger.isTraceEnabled()) {
        for (int i = 0; i < 5; ++i) {
            logger.trace("This is trace message");
        }
    }
}

void loop() {
}

Serial output:

0000000044 app: INFO: My device ID: 1b002e000e47343432313031
0000000044 app: INFO: This is info message
0000000087 app: ERROR: This is error message
0000000135 app: TRACE: This is trace message
0000000183 app: TRACE: This is trace message
0000000231 app: TRACE: This is trace message
0000000279 app: TRACE: This is trace message
0000000327 app: TRACE: This is trace message

Advanced usage:

#include "application.h"

SerialLogHandler logHandler(9600, LOG_LEVEL_ERROR, {
    { "app", LOG_LEVEL_INFO },
    { "app.func", LOG_LEVEL_ALL },
    { "app.clazz", LOG_LEVEL_ALL }
});

void func() {
    static Logger log("app.func");
    log.trace("Hello from func()");
}

class Clazz {
public:
    Clazz() {
        log.trace("Hello from Clazz"); // Uses class-local logger
    }

private:
    static Logger log;
};

// Class-local logger
Logger Clazz::log("app.clazz");

// Global logger (uses "app" category by default)
Logger log;

void setup() {
    log.info("Hello from setup()"); // Uses global logger
    func();
    Clazz();
}

void loop() {
}

Serial output:

0000000071 app: INFO: Hello from setup()
0000000071 app.func: TRACE: Hello from func()
0000000117 app.clazz: TRACE: Hello from Clazz

---

Doneness:

• Contributor has signed CLA
• Problem and Solution clearly stated
• Code peer reviewed
• API tests compiled
• Run unit/integration/application tests on device
• Add documentation
• Add to CHANGELOG.md after merging (add links to docs and issues)

[sergeuz]

Sorry for a bit noisy diff – I had to squash multiple commits while transiting from my forked repo. Key changes can be found here: https://github.com/spark/firmware/blob/feature/logger_api/wiring/inc/spark_wiring_logging.h#L173

[sergeuz]

Couple of questions to discuss:

Should we declare global Logger instance in one of our header files to make it accessible by default (like we currently do for Serial)?

Do we actually want to expose methods for direct logging, i.e. Logger::printf(), Logger::write()? Those can probably be confusing.

[monkbroc]

The API looks good.

Should we declare global Logger instance in one of our header files to make it accessible by default (like we currently do for Serial)?

I'd mirror EEPROM: Create a singleton on first access.

Do we actually want to expose methods for direct logging, i.e. Logger::printf(), Logger::write()? Those can probably be confusing.

I don't think there's a need to expose printf and write.

I would like to see DUMP exposed since this is a common thing I want to do: check if a buffer has the values I expect during program run.

[m-mcgowan]

This is a great start! 👍 For simpler programming, would using non-static loggers be a workable alternative? The main upside is that they can be declared and initialized within the class declaration.
Is there any consequence to having multiple logger instances for the same category?

Similarly for function loggers, how about:

void function()
{
    FunctionLogger log("app.function");
    // would be nice to use __FUNCTION_NAME__ here but the underscores are a bit scary! 
} 

[sergeuz]

This should be ready for the review. Primary changes are:

• Added default global logger (Log):

SerialLogHandler logHandler;

void setup() {
    Log.info("Hello!");
}

• Reworked the documentation.
• Moved LogManager to the public namespace.
• Made baud rate argument optional for the existent log handlers.

[m-mcgowan]

@sergeuz - do you feel the API is stable enough that we should include it in 0.6.0, or is it best to postpone until 0.7.0?

[sergeuz]

@m-mcgowan I think it's stable and the code is quite straightforward to review. The documentation may require some editing though. If we don't have enough time to review both this PR and #1022 which depends on this branch and introduces ABI breaking changes, then I would postpone both PRs until 0.7.0.

[m-mcgowan]

Fantastic job! 👍