一个专为高性能和丰富功能集而构建的 C 日志库。

法语 | 韩语 | 简体中文

主要特性 | 构建与安装 | 基本用法 | 贡献指南

主要特性

Stumpless 拥有众多特性，使 C 语言中的日志记录快速且简单：

• 记录到多种目标，如 Splunk、rsyslog、 journald、Windows 事件日志、sqlite 等！
• 结构化与非结构化日志，以满足您的需求
• 支持在 Linux、Windows、Mac、FreeBSD、MinGW、MSYS2、Cygwin、DOS 等系统上构建！
• 线程安全
• 可在编译时调整或移除，以实现零运行时开销
• 支持多种语言本地化 🇦🇱 🇧🇷 🇧🇬 🇨🇳 🇨🇿 🇩🇪 🇩🇰 🇪🇸 🇫🇷 🇬🇷 🇭🇺 🇮🇳 🇮🇱 🇮🇹 🇯🇵 🇰🇪 🇰🇷 🇵🇱 🇸🇰 🇱🇰 🇸🇪 🇹🇷 🇺🇸 🇻🇳 🇪🇬🇷🇴 (添加您的语言！)
• 易于访问的 文档、 示例 以及支持。

它可以记录到哪些目标？

该库的主要目标之一是为各种日志目标提供一致的日志记录接口。 这意味着您可以专注于定义事件及其去向，而无需寻找其他 SDK 或添加守护进程 和插件来实现目标。Stumpless 可以将日志写入：

• 简单的字符缓冲区
• 文件和流
• Unix 套接字（例如本地 syslog 守护进程）
• 网络服务器（IPv4 或 IPv6，TCP 或 UDP）
• Systemd Journald 服务
• Sqlite3 数据库
• Windows 事件日志
• 自定义函数，用于您可能需要的其他任何用途！

没看到您需要的功能？请创建一个 问题 提出您的请求，我们会将其纳入我们的 路线图！

快速构建与安装

Stumpless 仅需 cmake 和一个受 cmake 支持的构建工具链（如 GCC 或 Visual Studio）即可构建。

# cloning the latest version of the source tree
git clone git@github.com:goatshriek/stumpless.git

# creating a new build directory
mkdir build
cd build

# configuring the new build
cmake ../stumpless

# building stumpless (with 4 threads - adjust as desired)
cmake --build . --parallel 4

# install the library (you probably need sudo to do this)
sudo cmake --install .

查看安装说明]以获取更多关于在不同环境和/或使用其他工具链构建和安装 stumpless 的详细信息。

基本用法

最简单的入门方法是使用 stumplog 函数作为标准库中 syslog 函数的直接替代：

// if you're used to doing this:
syslog( LOG_INFO | LOG_USER, "My message #%d", count );

// then you can start by changing to this:
stumplog( LOG_INFO | LOG_USER, "My message #%d", count );

如果您尚未打开目标，此操作将向日志记录到平台的默认目标：在 Linux 上为 /dev/log，在 Mac 系统上为 /var/run/syslog，在 Windows 机器上则为 Windows 事件日志。如果您在调用 stumplog 之前 打开了一个目标，甚至多个目标，则日志将发送到最近打开的目标。

如果您希望函数调用更简短，可以使用 stump 函数 将消息发送到当前目标。您还可以使用格式说明符， 就像使用 printf 时一样：

stump( "Login attempt failure #%d for user %s", count, username );

如果你不需要格式说明符，请使用 _str 的变体之一： 它既更快又更安全！

stump_str( "Login failure! See structured data for info." );

如果你想打开一个特定的目标而不是使用默认目标，那么只需 打开你需要的目标并开始发送消息。例如，要记录到 名为 example.log 的文件：

target = stumpless_open_file_target( "example.log" );

// uses the last opened target by default
stump( "Login attempt failure #%d for user %s", count, username );

通过网络向 Splunk 或 rsyslog 之类的目标发送消息同样简单：

target = stumpless_open_udp4_target( "send-to-splunk-example",
                                     "mylogserver.com" ); // or use an IP
stump( "Login attempt failure #%d for user %s", count, username );

如果你有多个目标，你可以像这样向选定的目标发送消息：

stumpless_add_message( target,
                       "Login attempt failure #%d for user %s",
                       count,
                       username );

严重级别简写

在日志调用中直接指定严重级别是很常见的，因此 stumpless 提供了一些宏函数，以使这一过程更简洁、更高效。例如， 要记录严重级别为 INFO 的消息，您可以这样做：

stump_i( "this gets logged as an info message" );

如果您还想在每条消息中查看源文件、行号和函数名称信息， 您可以使用 _t（'t' 代表 trace）：

stump_t( "this includes source info" );

使用这些函数还有一个额外的好处，即通过简单地定义 STUMPLESS_ENABLE_UPTO 或 STUMPLESS_DISABLE_DOWNTO 符号，可以在编译时将其移除。这使得在不同构建之间轻松更改日志级别， 例如，可以在源代码没有差异的情况下拥有 prod 和 debug 版本。

// be sure to define this before stumpless.h gets included
#define STUMPLESS_ENABLE_UPTO_INFO

// ...

// this log will go through just fine
stump_i( "I'm doing that thing you asked" );

// this debugging message is completely removed: no runtime impact whatsoever
stump_d( "DEBUG info: %d, %d, %s", thing_1, thing_2, stringy_thingy );

查看 stumpless/level 中的头文件，以查看完整的严重级别简写函数列表，或者查看 严重级别示例 以查看一个完整的程序运行过程。

更多示例

如需了解上述场景的更详细示例、特定目标 类型的使用、如何处理更复杂的消息结构等，请查看 示例。这些包括带注释的示例代码文件，可供编译、 运行和修改，以帮助你入门。

贡献

发现问题或有功能请求？只需使用其中一个 模板创建一个 issue，我们会尽快回复。你也可以查看 项目的贡献指南，以了解 你可以通过哪些不同方式为开源社区做出贡献的更多细节！

如果你想亲自编写一些代码或进行更新，请查看 开发指南以获取详细的指导。 根据你的经验水平和对 贡献的熟悉程度，有几种选择。

第一个选项是浏览标记为 good first issue标签的 issue 列表。 这些 issue 被选为工作量较小但意义重大的任务，并 包含完成它们的一般方法细节。如果你只是想 尝试一下这个项目或开源贡献，它们是一个很好的起点。

更有经验的开发者可能更倾向于查看项目的完整问题列表，以及 路线图。 如果某个项目引起了你的兴趣，请在现有问题中留下评论，或者如果该问题尚不存在，则新建一个问题并说明你打算处理它，以便其他人能够了解该工作正在进行中。

文档和社区

如果你好奇 stumpless 中某些未在此处说明的工作方式，你可以查看文档中相应的部分，这些文档存储在 docs 文件夹中。 仓库中的文件夹包含各自的 README 文件，其中详细说明了它们的内容以及其他相关信息。每个函数的文档也托管在 项目网站上，既包括 C 库，也包括 C++ 等其他语言绑定。

Stumpless 还在本地安装中包含以 man 页面形式提供的文档。安装库后，你可以通过运行 man 命令并输入将目录替换为下划线的头文件名，来查看任何头文件（及其包含的函数）的文档，例如 man stumpless_log.h 以查看记录简单字符串 消息的函数的文档。

还有许多方式可以让你联系项目团队和更广泛的社区以获取支持。

• Issues 和 discussions on Github 是如果你有任何具体问题或建议时获得回复的好方法。
• 在 gitter 上有一个持续的聊天，你可以在那里找到公告并提问。
• 关于项目的新闻通常也会由 goatshriek 在 Twitter 上发布，使用 #StumplessLib。
• 如果你希望进行私密沟通，可以通过 email 联系主要维护者。这是 notifying 我们项目安全问题的首选方式，以便我们尽快处理，从而降低被滥用的风险。