|
1 | | -# cLog – Modern C++ Logging Library |
| 1 | +# cLog |
2 | 2 |
|
3 | | -> **Frictionless, async-by-default, structured JSON logging for modern C++** |
| 3 | +[](https://github.com/mbn-code/cLog/actions) |
| 4 | +[](LICENSE) |
| 5 | +[](https://github.com/mbn-code/cLog/stargazers) |
4 | 6 |
|
5 | | -## Quickstart Example |
6 | | -```cpp |
7 | | -#include "logger.hpp" |
8 | | -int main() { |
9 | | - Logger log; |
10 | | - log.info("system.start").kv("version", "1.0"); |
11 | | -} |
12 | | -``` |
13 | | -**First log call launches a background worker thread for async output by default.** |
| 7 | +**Modern C++ Structured Logging Library** |
14 | 8 |
|
15 | 9 | --- |
16 | 10 |
|
17 | | -## Features (Design Table) |
18 | | -| Feature | Approach | |
19 | | -|-------------------------|-----------------------------------------------------------------| |
20 | | -| Installation | Single header, instant use, nlohmann/json is fully internal | |
21 | | -| First Log | Async by default—first use launches worker thread, documented up front | |
22 | | -| Sync Mode | Compile-time build flag for full sync, runtime opt-in if available | |
23 | | -| No Macros | Never used—tooling, refactoring, and debugging always work | |
24 | | -| Structured Logs | JSON output, no user-level JSON code | |
25 | | -| Compile-time level | Minimal overhead when disabled; eliminates dead code | |
26 | | -| Sinks | Console/file by default; custom/extensible sinks, not required | |
27 | | -| Debug/Stack Context | Opt-in: header, adds stacktrace/thread/context as desired | |
28 | | -| Thread Info | Included via debug header/opt-in only | |
29 | | -| Config | (Future) JSON/YAML—deserializes to core logger API, never magic | |
30 | | -| Testing/CI | GoogleTest + GitHub Actions, boring, predictable, cross-platform | |
31 | | -| Docs/Examples | Always shows one-liner start, then advanced opt-ins | |
| 11 | +> **Async by default, chainable API, no macros.** |
| 12 | +> Extensible sinks, structured JSON out; robust thread lifecycle & lossless shutdown. |
32 | 13 |
|
33 | 14 | --- |
34 | 15 |
|
35 | | -## Rationale and Values |
36 | | -- **Zero-magic API** |
37 | | -- **No macros ever**: Easy refactoring and debugging |
38 | | -- **Async by default, never silent**: Docs and behavior preempt confusion |
39 | | -- **Structured JSON output only**: No user-facing JSON APIs |
40 | | -- **Extensible, but extensions never required** |
| 16 | +## ⭐️ Getting Started |
41 | 17 |
|
42 | | -For more, see [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) (to be added). |
| 18 | +```cpp |
| 19 | +#include "include/logger.hpp" |
| 20 | +#include "include/file_sink.hpp" |
43 | 21 |
|
44 | | ---- |
| 22 | +int main() { |
| 23 | + c_log::Logger log; |
| 24 | + log.add_sink(std::make_unique<c_log::FileSink>("log.json")); |
| 25 | + log.info("startup").kv("user", "alice").kv("run", 1); |
| 26 | +} |
| 27 | +``` |
45 | 28 |
|
46 | | -## Async and Sync Behavior |
47 | | -- Async (background thread and queue) is the default. First log output launches async worker. |
48 | | -- Sync mode: Compile-time flag disables async for embedded/hard-realtime, or use `Logger log(Logger::Mode::Sync);` at runtime where threads are available. |
| 29 | +#### Install |
| 30 | +Just add `include/` to your project. No dependencies outside C++17 STL and bundled nlohmann/json. |
49 | 31 |
|
50 | 32 | --- |
51 | 33 |
|
52 | | -## Sinks and Extensibility |
53 | | -- Output goes to stderr (JSON per line) by default |
54 | | -- Register file or custom sinks using `.add_sink(std::make_unique<FileSink>("file.log"));` |
55 | | -- All extensibility is opt-in. No required advanced config. |
| 34 | +## Features |
| 35 | +- Async and sync modes (`Logger::Mode`) |
| 36 | +- Automatic background flushing/shutdown |
| 37 | +- Console and file sink out-of-the-box |
| 38 | +- Fully structured logs (JSON) |
| 39 | +- Clean chainable API: `info().kv().kv()` |
| 40 | +- Robust: lossless, race-free, cross-platform tested |
56 | 41 |
|
57 | 42 | --- |
58 | 43 |
|
59 | | -## Debugging, Stack, and Thread Context |
60 | | -- Include `logger_debug.hpp` to add `.with_stacktrace()`/`.with_context()`/`.with_threadinfo()` to entries. |
61 | | -- Zero core overhead unless debug features are requested. |
| 44 | +## Issues and Contributing |
| 45 | +- Please [open an Issue](https://github.com/mbn-code/cLog/issues) for bugs, features, or questions! |
| 46 | +- Star the repo if you find it useful ⭐ |
| 47 | +- [Contributing Guide](CONTRIBUTING.md) |
62 | 48 |
|
63 | 49 | --- |
64 | 50 |
|
65 | | -## FAQ |
66 | | -- **Q: Do I ever need to touch JSON types?** |
67 | | - > Never. JSON is entirely internal. |
68 | | -
|
69 | | -- **Q: Why async by default?** |
70 | | - > For performance. You control opt-out via build or API. |
| 51 | +## License |
| 52 | +MIT - see [LICENSE](LICENSE) |
71 | 53 |
|
72 | 54 | --- |
73 | 55 |
|
74 | | -## License |
75 | | -MIT. Includes vendored [nlohmann/json](https://github.com/nlohmann/json) (MIT). |
| 56 | +*Project status: Alpha. API will stabilize with community use.* |
0 commit comments