DS_CAP_SYS_LOG

DS_CAP_SYS_LOG — System Log

Description

This capability adds support for a system log ("syslog" for short). Syslog is normally used to print diagnostic messages, such as startup or shutdown, as well as various program error conditions. It is more of interest for controller programmer than for end user.

The following fields are implemented:

Field	Description	Default Value
Print *System::log	System log	&Serial

The library exposes a log object (a pointer to Arduino Print class). This means that a whole multitude of printing methods (print(), println(), printf(), ...) is available. You have to include a newline into log message (or use println()).

Print class by itself does not specify where the log would go ("log sink"). For this, a more specialized initialization must be done. Currently supported is the standard ESP8266 option of hardware serial line. Other potential sinks (not implemented) include software serial, file, network socket (TCP or UDP), or even an on-board screen (where available).

It is quite common to prefix log with timing information. Absolute time is rarely needed; relative time is usually enough. For this, a wrapper macro TIMED() is provided, to be used as System::log->printf(TIMED("hello\n")). This will prefix the log message with the millis() information. Note that internally it uses a printf()-like formatting, so it can only be used in conjunction with printf() call. All log messages issued from inside the library add timing to the output.

Requires

• ESP8266 Arduino Core — Print class implementation

Cooperates With

• DS_CAP_APP_ID — if application identification is enabled, it will be logged on system startup;
• DS_CAP_APP_LOG — System::appLogWriteLn() may use an option copy_to_syslog, which will echo application log message into syslog;
• DS_CAP_SYS_TIME — if time is enabled, time synchronization event will be sent to syslog;
• DS_CAP_WEBSERVER — if web server is enabled, each serving of a web page will be logged (including client IP-address);
• DS_CAP_WIFIMANAGER — if Wi-Fi manager is enabled, entry and exit from Wi-Fi manager will be logged.

Nearly all capabilities use syslog to report their startup sequences or serious error conditions. Because of this, syslog is the first thing which gets initialized when System::begin() is called.

Conflicts With

None.

Usage

None. See the corresponding syslog implementations.

Mandatory Calls

System::begin()	Not required
System::update()	Not required

Note that while this capability per se does not require System::begin() call, the underlying implementation, like hardware serial, would most likely need it to work correctly. Check its page for details.

Examples

None.

Bugs

• It would be more consistent and elegant to have System::log as Print & rather than Print *, but I did not manage to initialize it reliably (see weak initializations);
• For historical reason, assignment of Serial log sink is currently done in the generic log section rather under hardware serial option (issue #4). This problem has no user-visible effect and will be fixed in future version of the library. For the same reason, if DS_CAP_SYS_LOG is defined without DS_CAP_SYS_LOG_HW, the log would be still sent to Serial, but without proper initialization; i.e., nothing will be printed.

Availability

Version 1.0 or later.

See Also

• DS_CAP_SYS_LOG_HW
• DS_CAP_APP_LOG