mirror of https://github.com/nirenjan/libx52.git
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
Pinelog - a lightweight logging API
|
||
===================================
|
||
|
||
Pinelog is a lightweight logging API for C programs that's designed to be
|
||
included in your program source code. Parameters for Pinelog are configured at
|
||
build time by means of preprocessor flags.
|
||
|
||
# Usage
|
||
## Logging macros
|
||
|
||
Pinelog uses `printf` style formatting, using the following list of macros. The
|
||
macro indicates the level at which the message is logged.
|
||
|
||
* `PINELOG_FATAL`
|
||
* `PINELOG_ERROR`
|
||
* `PINELOG_WARN`
|
||
* `PINELOG_INFO`
|
||
* `PINELOG_DEBUG`
|
||
* `PINELOG_TRACE`
|
||
|
||
**Note:** `PINELOG_FATAL` is used when the program encounters a fatal condition
|
||
and needs to abort. This will log the fatal message and terminate the program
|
||
with an exit code of 1.
|
||
|
||
### Example
|
||
|
||
```C
|
||
PINELOG_INFO("configuration file %s not found, using defaults", config_file);
|
||
```
|
||
|
||
## Logging levels
|
||
|
||
The default logging level is `ERROR`, and this can be controlled by the
|
||
preprocessor flag `PINELOG_DEFAULT_LEVEL`.
|
||
|
||
The program can control the level at which messages can be logged at runtime,
|
||
by using the `pinelog_set_level` function. This function takes in the level
|
||
definition, which is one of the following, in increasing order of priority.
|
||
|
||
* `PINELOG_LVL_TRACE`
|
||
* `PINELOG_LVL_DEBUG`
|
||
* `PINELOG_LVL_INFO`
|
||
* `PINELOG_LVL_WARNING`
|
||
* `PINELOG_LVL_ERROR`
|
||
* `PINELOG_LVL_FATAL`
|
||
* `PINELOG_LVL_NONE`
|
||
|
||
Setting the level to a given priority suppresses all log messages of lower
|
||
priority, i.e., if the level is set to `PINELOG_LVL_ERROR`, messages at
|
||
`WARNING` level and below will be suppressed, but `ERROR` and `FATAL` messages
|
||
will be logged.
|
||
|
||
**Note:** `PINELOG_LVL_NONE` suppresses all log messages, but `PINELOG_FATAL`
|
||
will still terminate the program, even though nothing is logged.
|
||
|
||
### Example
|
||
|
||
```C
|
||
pinelog_set_level(PINELOG_LVL_WARNING);
|
||
```
|
||
|
||
```
|
||
-DPINELOG_DEFAULT_LEVEL=PINELOG_LVL_WARNING
|
||
```
|
||
|
||
## Output redirection
|
||
|
||
Pinelog defaults to writing the log messages to standard output, and this can
|
||
be controlled by the preprocessor flag `PINELOG_DEFAULT_STREAM`.
|
||
|
||
However, the application can redirect log messages at runtime to a different
|
||
`FILE *` stream, or to a file by using one of the following two methods:
|
||
|
||
```C
|
||
FILE *out = fopen("/run/app.fifo", "w");
|
||
pinelog_set_output_stream(out);
|
||
pinelog_set_output_file("/var/log/app.log");
|
||
```
|
||
|
||
```
|
||
-DPINELOG_DEFAULT_STREAM=stderr
|
||
```
|
||
|
||
## Logging format
|
||
|
||
Pinelog uses an opinionated logging format that is fixed as follows. Fields
|
||
within `[]` are optional and controlled by build time flags.
|
||
|
||
[2021-07-14 11:08:04 ][ERROR: ][./test_pinelog.c:108 ]formatted message.
|
||
|
||
The program can be controlled by the following preprocessor flags, all of which
|
||
default to `0` (disabled). Set the flag to `1` to enable it.
|
||
|
||
* `PINELOG_SHOW_DATE` - Display the ISO 8601 date and time when the message is
|
||
logged.
|
||
* `PINELOG_SHOW_LEVEL` - Display the level at which the message is logged.
|
||
* `PINELOG_SHOW_BACKTRACE` - Display the file and line where the message is
|
||
logged.
|
||
|
||
* `PINELOG_STRIP_FILE_PATH` - If `1` (default), the file in the log line is only
|
||
the basename. If `0`, the compiler’s `__FILE__` is used instead, which usually
|
||
keeps a path prefix (for example `libx52/core.c` vs `libx52io/core.c`).
|
||
|
||
Set these flags by using the `-D` compiler argument, .e.g.
|
||
`-DPINELOG_SHOW_LEVEL=1 -DPINELOG_SHOW_DATE=1`
|
||
|
||
When using Meson, the pinelog option `strip-file-path` sets
|
||
`-DPINELOG_STRIP_FILE_PATH` for the library and for dependents via
|
||
`declare_dependency(compile_args: ...)`.
|
||
|
||
### Level strings
|
||
|
||
The application can control the level strings displayed by means of preprocessor
|
||
flags, if the application wishes to display the log messages in a language other
|
||
than English. This can be achieved by means of the following preprocessor
|
||
definitions.
|
||
|
||
* `PINELOG_FATAL_STR`
|
||
* `PINELOG_ERROR_STR`
|
||
* `PINELOG_WARNING_STR`
|
||
* `PINELOG_INFO_STR`
|
||
* `PINELOG_DEBUG_STR`
|
||
* `PINELOG_TRACE_STR`
|
||
|
||
### Example
|
||
|
||
```
|
||
-DPINELOG_ERROR_STR=\"E\" -DPINELOG_FATAL_STR=\"F\"
|
||
```
|
||
|
||
# Integrating Pinelog
|
||
|
||
Pinelog is intended to be integrated into your application source tree, either
|
||
by means of including the sources directly, or by including the repository as
|
||
a Git submodule or subtree.
|