esp-link/syslog/syslog.md

syslog
======

The lib implements a RFC5424 compliant syslog interface for ESP8266. The syslog
message is send via UDP.

syslog messages are queued on heap until the Wifi stack is fully initialized.
If the remaining heap size reaches a given limit, syslog will add a final obituary
and stop further logging until the queue is empty and sufficient heap space is
available again.

The module may be controlled by flashconfig variables:

* **syslog_host: host[:port]**

    **host** is an IP-address or DNS-name. **port** is optional and defaults to 514.
DNS-Resolution is done as soon as the Wifi stack is up and running.

* **syslog_minheap: 8192**

    **minheap** specifies the minimum amount of remaining free heap when queuing up
syslog messages. If the remaining heap size is below **minheap**, syslog will insert
an obituary message and stop queuing. After processing all queued messages, the
logging will be enabled again.

* **syslog_filter: 0..7**

    **syslog_filter** is the minimum severity for sending a syslog message. The filter
is applied against the message queue, so any message with a severity numerical lower
than **syslog_filter** will be dropped instead of being send.

* **syslog_showtick: 0|1**

    If **syslog_showtick** is set to **1**, syslog will insert an additional timestamp
(system tick) as "PROCESS" field (before the users syslog message).
The value shown is in ms, (1µs resolution) since (re)boot or timer overflow.

* **syslog_showdate: 0|1**

    If **syslog_showdate** is set to **1**, syslog will insert the ESPs NTP time
into the syslog message. If "realtime_stamp" (NTP 1s ticker) is **NULL**, the
time is derived from a pseudo-time based on the absolute value of systemticks.

    Some syslog servers (e.g. Synology) will do crazy things if you set **syslog_showdate** to **1**


The syslog module exports two functions:

```
syslog_init(char *server_name);
syslog(uint8_t facility, uint8_t severity, const char *tag, const char *fmt, ...);
```

syslog_init
-----------
usage: `syslog_init(char *server_name);`

**syslog_init** expects a server name in format "host:port" (see **syslog_host** flashconfig).

If **server_name** is **NULL**, all dynamic allocated memory (buffers, queues, interfaces)
are released and the syslog state is set to "SYSLOG_HALTED".

If **server_name** is **""**, syslog state is set to "SYSLOG_HALTED", without clearing
the queue.

Otherwise, syslog_init will allocate all required structures (buffers, interfaces) and
send all collected syslog messages.

syslog is self-initializing, meaning the syslog_init(server_name) is called on first
invocation. The syslog_init function is only for convenience if you have to stop or disable syslog functions.


syslog
------
usage: `syslog(uint8_t facility, uint8_t severity, const char *tag, const char *fmt, ...);`

* **facility**

    the message facility (see syslog.h, **enum syslog_facility**).

* **severity**

    the message severity (see syslog.h, **enum syslog_severity**)

* **tag**

    user defined tag (e.g. "MQTT", "REST", "UART") to specify where the message belongs to

* ** const char *fmt, ...**

    the desired message, in printf format.

Examples
========

    showtick=0, showdate=0
    Invocation: syslog()
output:

    showtick=1, showdate=1
    Invocation: syslog()
output:

    showtick=1, showdate=1, NTP not available
    Invocation: syslog()
output:

    showtick=1, showdate=1, NTP available
    Invocation: syslog()
output: