The C/C++ Diagnostic Logging Sweetspot
- Introduction
- Ten important things to know about Pantheios
- Installation
- Components
- Examples
- Getting started
- Project Information
Pantheios is an efficient, flexible, and robust C/C++ diagnostic logging API library. It is designed to give application code a type-safe, high-performance way to emit diagnostic statements, while leaving where and whether those statements are emitted to link-time front-end and back-end choices.
Pure Pantheios is the Application Layer plus the Core. Stock front-ends and back-ends are convenient, but not required for that core contract.
Please feel free to request — nay, demand — improvements in any areas that you feel are deficient. Criticism will be gratefully received.
Further reading: http://pantheios.org/, FAQ.md.
-
It's a diagnostic logging API library, not a diagnostic logging library.
The architecture is split into four parts — Application Layer, Core, Front-end, and Back-end (see Architecture). A common first reaction is "the performance is brilliant, but you don't have all the features of log4cxx". That is intentional. Pantheios is designed to sit above feature-rich logging libraries: write a simple back-end that wraps, say, log4cxx or log4cplus, plug it in at link-time, and keep Pantheios' performance and type-safety with the richer feature set underneath.
-
It's open-source, and free.
It is released under the 3-clause BSD license. See LICENSE.
-
It depends on other libraries, which are also open-source and free.
STLSoft is required. b64 is optional (for the
pantheios::b64inserter). shwild and xTests are used for testing. See Dependencies. -
It's designed for efficiency.
Pantheios aims to be substantially faster than other serious C++ diagnostic logging libraries (historically claimed up to two orders of magnitude in favourable cases). See the original performance notes (also mirrored historically on SourceForge) for measurements and discussion of the "sweet spot".
-
It is type-safe.
Unlike diagnostic logging built on C's Streams or C++'s IOStreams libraries, the Application Layer is designed for 100% type-safety of statement arguments.
-
Selection of logging transport (back-end(s)) is done at link-time, for good reason.
A diagnostic logging library must be available whenever any part of the application needs it. In C++, a significant amount of work can run during dynamic initialisation, so setup cannot wait for
main(). The consequence is Pantheios' main hard-to-use aspect: arranging the link of Core, front-end, and back-end. Tutorials and examples (including implicit-link headers) cover that; see Getting started. -
It's highly extensible.
Stock back-ends cover common transports (console /
fprintf, file, Syslog, COM Error Object, speech, Windows Debugger, Windows Event Log, and others). A custom back-end is a small C API. The Application Layer already understands a wide range of string-like and convertible types (including types such asstruct tm,FILETIME,struct in_addr, and so on), and you can extend the set of types usable in logging statements; see the documentation and inserter / shim examples. -
It's used in serious commercial systems, including high-throughput financial environments.
Pantheios has been deployed by organisations in Australia, the US, and elsewhere. At least one notable high-throughput user commissioned custom front-/back-ends for extreme performance; NDA prevents naming the client or the customisations. They described the result as operating with "clock-cycle speed".
-
It's highly portable.
Pantheios targets a wide range of C++ compilers and UNIX, Linux, macOS, and Windows. On UNIX-like platforms it avoids unnecessary platform-specific constructs. New compiler/platform combinations typically need only modest STLSoft configuration work; the maintainers are happy to help.
-
It remains under active development, and feedback is welcome.
The aim is that Pantheios be the diagnostic logging API of choice for C++ programmers who want performance without sacrificing robustness or flexibility. Suggestions on how better to achieve that are welcome via GitHub Issues.
Detailed instructions — via CMake, via bundling, via custom makefile parameters — are provided in the accompanying INSTALL.md file.
In short: install STLSoft 1.11 (and optionally b64 and shwild) via CMake, clone Pantheios, run prepare_cmake.sh, build, then cmake --install.
| Layer | Responsibility |
|---|---|
| Application Layer | What application code uses to write statements (pantheios::log / log_*, C pantheios_logputs / pantheios_logprintf) |
| Core | Ties the layers together; C++ auto-initialises via Schwarz counters in pantheios/pantheios.hpp (unless PANTHEIOS_NO_AUTO_INIT); C must call pantheios_init() |
| Front-end | Severity filtering and process identity (pantheios_fe_init, pantheios_fe_isSeverityLogged, …) |
| Back-end | Emits statements accepted by the front-end (pantheios_be_init, pantheios_be_logEntry, …) |
Apart from initialising the Core (automatic in C++ compilation units), application code does not normally interact with the Core directly. Front-end and back-end are selected at link-time, so initialisation can complete before main() and any code in the process can log.
C++ application code typically includes pantheios/pantheios.hpp and logs with pantheios::log_* helpers or pantheios::log(severity, …).
Statement arguments are converted lazily — inserters do work only if the front-end accepts the severity.
Common inserters include:
pantheios::integer,pantheios::real,pantheios::pointer,pantheios::hex_ptr;pantheios::character,pantheios::boolean;pantheios::args,pantheios::blob,pantheios::b64(optional; requires b64);pantheios::processId,pantheios::threadId,pantheios::hostId;
and others under include/pantheios/inserters/.
Stock front-ends include fe.simple, fe.all, fe.null, fe.fail, fe.N, and fe.WindowsRegistry (plus *.WithCallback variants). Process identity for stock front-ends is supplied by defining PANTHEIOS_FE_PROCESS_IDENTITY.
Stock back-ends include be.fprintf, be.file, be.null, be.fail, be.N, be.lrsplit, be.syslog, be.AnsiConsole, and Windows-oriented backends such as be.WindowsConsole, be.WindowsDebugger, be.WindowsEventLog, be.WindowsSyslog, be.COMErrorObject, be.speech, and others. ACE-oriented stock backends exist in the tree; full CMake optional discovery for ACE is not yet complete.
Examples are provided in the examples directory (C under examples/c/, C++ under examples/cpp/), including:
example.c.101,example.c.core.pantheios_logprintf,example.c.N;example.cpp.misc.101;example.cpp.linking.implicit_link_1;example.cpp.frontends.custom;example.cpp.backends.file,example.cpp.backends.callback;example.cpp.inserters.integer,example.cpp.inserters.b64,example.cpp.inserters.args;example.cpp.custom.wrap_log4cxx,example.cpp.custom.wrap_log4cplus;example.cpp.tracing.standard;example.cpp.contract.PANTHEIOS_ASSERT;
A minimal C++ program using implicit linking of the Core, fe.simple, and be.fprintf:
#include <pantheios/pantheios.hpp>
#include <pantheios/implicit_link/core.h>
#include <pantheios/implicit_link/fe.simple.h>
#include <pantheios/implicit_link/be.fprintf.h>
#include <stdlib.h>
PANTHEIOS_EXTERN const PAN_CHAR_T PANTHEIOS_FE_PROCESS_IDENTITY[] =
PANTHEIOS_LITERAL_STRING("hello.pantheios");
int main()
{
pantheios::log_INFORMATIONAL(PANTHEIOS_LITERAL_STRING("Hello!"));
return EXIT_SUCCESS;
}See examples/cpp/linking/example.cpp.linking.implicit_link_1 for the canonical form of this pattern. C programs must call pantheios_init() (and check the return) before logging — see examples/c/example.c.101.
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Pantheios.
| Dependency | Role | Required? |
|---|---|---|
| STLSoft 1.11 (1.11.1-alpha25 or later) | Implementation and interface support | ✅ Always |
| b64 | pantheios::b64 inserter |
⚪ Optional (PANTHEIOS_NO_B64 when absent) |
| shwild | Pattern matching in tests | ⚪ Optional; tests only |
| xTests (≥ 0.25.4) | Unit / component tests | ⚪ Tests only (BUILD_TESTING) |
| ACE | Stock be.ACE / related backends |
⚪ Optional; CMake wiring incomplete |
Projects closely related to Pantheios include:
- b64 — optional Base-64 inserter support;
- Pantheios.Extras.DiagUtil;
- Pantheios.Extras.Main;
- Pantheios.Extras.xHelpers;
- shwild — used in testing;
- STLSoft — required foundation;
- xTests — used in testing;
Pantheios is released under the 3-clause BSD license. See LICENSE for details.