Lib.rs

增强型命令行日志工具。

关键特性 | 基本用法 | 贡献

关键特性

无头日志记录器旨在替代并改进传统的 logger 工具。它使用 Rust 和 Stumpless 编写，并在以下方面对传统工具进行了改进：

• 更多的日志目标选项（文件、Windows事件日志）
• 单次调用即可将日志发送到多个目的地
• 便携式，已在Windows和Linux上测试
• 每个日志目标一个线程

将日志发送到任何地方

无头日志记录器支持Stumpless提供的所有目标类型，包括 logger 有的一切。

默认目标

无头日志记录器有默认目标的概念，试图抽象出系统上发送日志的最合理位置。对于Windows，这是名为Stumpless的事件日志，对于Linux和Mac系统，这是 /var/run/syslog 或 /dev/log，如果其他都失败了，这是一个名为 stumpless-default.log 的文件。如果你不向无头日志记录器提供显式的目标，它就会发送到这个位置。

stumpless Send it!
# where this goes depends on your system!

如果你想显式地将日志发送到默认目标，例如需要同时发送到其他位置，可以使用 --default 选项，如下所示

stumpless --default Send it!
# same as before!

stdout 和 stderr

如果你只想打印日志，则可以使用 stdout 或 stderr。

stumpless --stdout Hello from Stumpless!
# <13>1 2023-01-01T19:32:19.802953Z dante stumpless-cli - - - Hello from Stumpless!

stumpless --stderr Stumpless says something went wrong...
# <13>1 2023-01-01T19:33:08.957079Z dante stumpless-cli - - - Stumpless says something went wrong...

文件

无头日志记录器提供了一种简单的方法来将日志写入文件，无需通过syslog守护进程或滥用流重定向。使用 --log-file 标志可以指定要发送日志的文件，短选项为 -l。

stumpless --log-file round.log Everything is a file these days

cat round.log
# <13>1 2023-01-19T02:20:22.984425Z dante stumpless-cli - - - Everything is a file these days

如果您想将日志条目写入多个文件，您只需多次指定此标志即可。这在stumpless中的大多数日志目标中都适用，这意味着您可以直接从shell发送消息到各种不同的位置。每个不同的日志目标都由自己的线程处理，以防止它们相互阻塞。

stumpless --log-file square.log --log-file triangle.log You get a message, and you get a message!

# note that the timestamp is slightly different in these two messages
cat square.log
# <13>1 2023-01-22T01:35:07.112856Z dante stumpless-cli - - - You get a message, and you get a message!

cat triangle.log
# <13>1 2023-01-22T01:35:07.112963Z dante stumpless-cli - - - You get a message, and you get a message!

网络

将日志发送到网络服务器是一个常见任务。Stumpless通过默认启用的network功能支持此操作。它支持IPv4和IPv6，包括TCP和UDP。您可以使用--tcp4、--udp4、--tcp6和--udp6选项来指定这些。

stumpless --tcp4 one-log-server.example Send this message over TCP on IPv4.

stumpless --udp6 two-log-server.example Send this message over UDP on IPv6.

# of course, you can send multiple messages at once, as with other target types:
stumpless --tcp6 red-log-server.example \
          --udp4 blue-log-server.example \
          Send this message to two servers at once!

默认情况下，这些目标使用端口514。如果您想使用不同的端口，则可以使用--port选项（或-P简短选项）来自定义。

stumpless --tcp4 special-snowflake-1.example --port 7777
          --udp6 special-snowflake-2.exampel --port 8888
          This message goes to two servers on different ports!

套接字

如果您想将消息发送到Unix套接字（如传统的/dev/log），则可以使用--socket，或-u简短选项（想想“u”代表Unix）。您会注意到，这与logger使用的选项相同。

stumpless --socket /dev/log Say hello to the daemon for me

套接字日志仅在启用socket功能的构建中可用。

Journald

当然，如果需要，stumpless可以将日志记录到systemd的日志记录服务中。这使用的是logger用户可能已经熟悉的相同的--journald选项。

stumpless --journald Send this message to the local journald service.

Journald日志仅在启用journald功能的构建中可用。

Windows事件日志

在存在Windows事件日志的计算机上，您也可以将其发送到那里。默认情况下，它将发送到名为“Stumpless”的应用程序日志，但您可以根据需要更改此设置。

stumpless --windows-event-log This will go into the Stumpless Application log.

# if you have your own special log, you can send to that instead
stumpless --windows-event-log=MySpecialLog This is a message for my own special log.

请注意，未配置的应用程序（包括默认的Stumpless日志）不会显示日志。如果您只想安装默认设置并以此方式使用，可以在运行stumpless时使用--install-wel-default-source选项来执行此操作。如果您想要安装，可以单独运行此命令。请注意，这需要足够的权限来修改注册表。它还将将其创建的注册表条目指向stumpless可执行文件所需的资源，因此请确保在您计划留下stumpless的地方再进行此操作。

# makes registry entries to install the Stumpless application log
# these will point at stumpless.exe, so make sure it's where you want it!
# and that it is in a place that Event Viewer has permissions, if you intend to
# browse the logs through that application
stumpless --install-wel-default-source

Windows事件日志仅在启用wel功能的构建中可用。

结构化数据

通过使用结构化数据字段，可以简化日志条目的解析。您可以使用与logger相同的选项添加这些：使用--sd-id添加元素，并在之后使用任何--sd-param添加更多详细字段到元素。以下是一些示例，这将更容易理解。

# Note that, as with logger, the quotes are required, and may need to be escaped
# for your shell. For bash or cmd.exe this might instead be color=\"red\", for
#PowerShell color='\"red\"', and so on.
stumpless --stdout --sd-id ball --sd-param color="red" --sd-param size="medium" Caught a ball!
# <13>1 2023-01-28T02:34:50.127Z Angus stumpless-cli - - [ball color="red" size="medium"] Caught a ball!

stumpless --stdout \
          --sd-id breadsticks \
          --sd-id mainCourse --sd-param meat="beef" --sd-param side="potatoes" \
          --sd-id dessert --sd-param type="cake" \
          Ate a feast!
# <13>1 2023-01-28T18:53:14.721851Z dante stumpless-cli - - [breadsticks][mainCourse meat="beef" side="potatoes"][dessert type="cake"] Ate a feast!

stumpless和logger之间的差异

此工具不是作为其他logger实现的直接替代品编写的。这并不是说它与它们完全不同：大多数选项都是相同的，并且使用的一般模式也是相同的。但是，由于简单性、性能或必要性的决策，出现了差异。以下是在您熟悉或使用其他日志记录器时与您相关的偏差。

• 没有参数时的默认输出取决于底层stumpless构建的默认目标，而不是/dev/log。
• 时间质量结构化数据元素尚未包含（等待Stumpless实现此功能）。
• 网络服务器IP版本和协议一起指定，例如--tcp4，而不是通过-T或-d标志独立于-n标志来分别指定。这是为了支持在单个调用中使用不同的组合来指定多个目标。
• 以下标志/操作模式不受支持：
  • 用于消息的RFC 3164 BSD syslog格式的--rfc3164

贡献

发现一个问题或有功能请求？只需使用其中一个模板创建一个问题，我们将会尽快回复。您还可以查看项目的贡献指南，了解更多您可以向开源社区回馈的不同方式！

如果您想实际编写一些代码或自己进行更新，有一些选项取决于您的经验和您对贡献的熟悉程度。

第一个选项是浏览带有标签good first issue的问题列表。这些问题被选为工作量小但有意义的工作，并包括您完成它们可以采取的一般方法的详细信息。如果您只是想尝试这个项目或开源贡献，这是一个很好的起点。

经验更丰富的开发者可能更喜欢查看项目上的完整问题列表以及路线图。如果某个项目引起了您的兴趣，请在现有问题中留言或如果尚不存在，则打开一个新问题，并声明您打算处理它，以便其他人知道它正在进行中。

或者，您可能只是想表示感谢！如果是这样，或者如果您有其他愿意私下告诉我的事情，请在Twitter上使用#StumplessLib或通过电子邮件！我非常希望看到您与他人分享这个项目，或者只是听听您对这个项目的想法。

进一步文档

如果您对这里未解释的stumpless中的某件事感到好奇，您可以在存储在存储库docs文件夹中适当部分的文档中进行检查。存储库中的文件夹包含自己的README文件，详细说明其包含的内容和任何其他相关信息。如果您仍然找不到答案，请提交一个问题或前往gitter寻求帮助。