= Logging for C (LogC)
CZ.NIC z.s.p.o. <packaging@turris.cz>
v1.0, 2020-06-14
:icons:

This is library for C for logging. It is able to output to any stream (file,
socket, stdout, ...) as well as to syslog. It optionally outputs colors and source
code line and more.

It is loosely designed close to Python logging but is intended to be versatile in
C and primarily easy to use no matter if you are writing library or application.

This library tries to introduce minimum amount of additional dependencies to be as
simple to include as possible.


== Dependencies

* On non-glibc http://www.lysator.liu.se/~nisse/misc[argp-standalone]
* http://hyperrealm.github.io/libconfig/[libconfig] for optional liblogc_config

For bootstrap (not release tarballs):

* autotools
* autoconf-archive
* https://www.gnu.org/software/gperf[gperf]

For tests:

* https://libcheck.github.io/check[check]
* Optionally http://www.valgrind.org[valgrind]
* For linting https://github.com/danmar/cppcheck[cppcheck]
* For coverage http://ltp.sourceforge.net/coverage/lcov.php[lcov]


== Compilation

To compile this library you have to run:

----
 ./configure
 make
----

Subsequent installation can be done with `make install`.

When you do not use distribution archive then you have to run initially
`./bootstrap`.


== LogC log in general

In general every component such as library or separate submodule should have its
own log with appropriate name set. Application then can choose how to configure
logging for different components.

=== Default output

By default, logs are printed to standard error output in format such as:

 Name: Message: Standard error message

Initial `Name:` is printed only if name of log is non-empty. The same thing
applies on standard error message, no message is printed if `errno == 0`.

It is also possible to display logging source. That would be in format:

 Name(file:line,function): Message: Standard error message

Where `file` is name of source file, `line` is source line in file and `function`
is function name message is printed from.

=== Message severity

Every log message has severity level. These are established levels and convention
on when to use which severity. LogC defines the following severity levels with suggested
usage:

critical:: should be used for messages causing program exit or restart or any
  other such drastic measure. This is intended as last measure for program to take
  if somethings goes horribly wrong.

error:: should be used for recoverable problems that highly influence program
  flow. There are commonly reports about outcomes that are not expected and
  commonly mean that standard program functionality was compromised.

warning:: should be used for unexpected findings. Warnings are not essentially a
  problems but rather something that user should review to ensure smooth
  functionality.

notice:: can be considered as warning with less priority or rather more
  significant informational message. This should commonly be used to tell users
  about completed important operations.

info:: are general informational messages. Note that in default verbosity this
  level is hidden. It should be used to inform user about

debug:: should be used for reports about deeper functionality. This level is
  hidden in default verbosity level. These reports should still be somewhat
  readable by user. Do not use it for info that only developer can understand to.

trace:: is lowest verbosity level available. It is in default verbosity hidden. It
  is intended to be used for dumps of internal state that are handy for deep dive
  debugging. This level is pretty much solely intended for reports from developer
  to developer. It can be used to let users to record output and send it to
  developers to trace program execution without needing to recreate conditions.

=== Concept of log verbosity

LogC provides pretty common concept of message verbosity. That is every message
has severity assigned and only messages with high enough severity are propagated
to logs. The limit for propagation is called verbosity and user can change it
commonly trough configuration of an application.

In LogC default verbosity is zero and that corresponds to `notice` severity. This
means that in default only notice, warning, error and critical messages are
propagated. Following table contains severities with their minimal verbosity
level.
|===
| Message severity | Verbosity level condition
| critical | < 4
| error | < 3
| warning | < 2
| notice | < 1
| info | < 0
| debug | < -1
| trace | < -2
|===

=== Environment variables

LogC internally expects and reads few predefined environment variables. The reason
for this is to allow basic debug print by LogC even before argument parsing and
program initialization in general.

LOG_LEVEL::
  This variables allows you to specify initial log level. Value is expected to be
  integer. To increase verbosity

LOG_ORIGIN::
  By setting this environment variable to anything non-empty results in enable of
  log origin. That is enrichment of log message by source file, line and function.
  This has of course effect only if log format contains origin fields (default one
  does).

[NOTE]
  These environment variables are read just once so it is in general not a good
  idea to change/set them in your program unless you are doing it before `exec`.

=== Error reporting and `errno` handling

LogC tries to simplify error reporting by appending standard error message
(retrieved using `strerror` function) anytime `errno` is not set to zero.

`errno` is automatically set to zero after every message posted to LogC.

[WARNING]
  LogC error reporting requires careful `errno` usage. You should know which
  function in your program can set `errno` and always reset `errno` to zero
  afterwards or log error using LogC.


== Usage

To use LogC you have to include `logc.h` and link your program or library with
`liblogc`. For programmers guide refer to appropriate link:./docs/logc.adoc[logc
documentation].

LogC provides additional optional extensions documented separately:

- link:./docs/logc_argp.adoc[LogC Argp] that implements common log related
  arguments.
- link:./docs/logc_config.adoc[LogC Config] that implements common log settings
  from configuration files.
- link:./docs/logc_assert.adoc[LogC Assert] providing standard `assert.h`
  compatibility.
- link:./docs/logc_asserts.adoc[LogC Asserts] provides extension for LogC Assert.
- link:./docs/logc_util.adoc[LogC Utilities] contains additional non-standard
  header only utilities.


== Running tests

LogC contains basic tests in directory tests. To run all tests you can just simply
run:

----
 make check
----

You can also run tests with Valgrind:

----
 make check-valgrind
----

To run checks with just one specific Valgrind test such as memtest you can run:

----
 make check-valgrind-memcheck
----

Source code of project can be also linted with cppcheck by running:

----
 make lint
----

There is also possibility to generate code coverage for test cases. To do so you
can run:

----
 make check-code-coverage
----
