{"id":23305693,"url":"https://github.com/goatshriek/stumpless-logger","last_synced_at":"2025-08-22T10:30:46.678Z","repository":{"id":81550730,"uuid":"465463392","full_name":"goatshriek/stumpless-logger","owner":"goatshriek","description":"CLI tool to log information to a variety of destinations, local and remote.","archived":false,"fork":false,"pushed_at":"2024-01-28T01:41:10.000Z","size":46,"stargazers_count":8,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"latest","last_synced_at":"2024-12-16T12:08:03.347Z","etag":null,"topics":["cli","command-line","command-line-tool","event-log","journald","library","log","logger","logging","logging-library","rust","syslog","terminal","tool"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goatshriek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null}},"created_at":"2022-03-02T20:44:09.000Z","updated_at":"2024-08-16T22:45:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"60490059-ce11-454b-ab4d-3508d831354f","html_url":"https://github.com/goatshriek/stumpless-logger","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatshriek%2Fstumpless-logger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatshriek%2Fstumpless-logger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatshriek%2Fstumpless-logger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatshriek%2Fstumpless-logger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goatshriek","download_url":"https://codeload.github.com/goatshriek/stumpless-logger/tar.gz/refs/heads/latest","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230582885,"owners_count":18248672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","command-line-tool","event-log","journald","library","log","logger","logging","logging-library","rust","syslog","terminal","tool"],"created_at":"2024-12-20T12:13:50.401Z","updated_at":"2024-12-20T12:13:51.150Z","avatar_url":"https://github.com/goatshriek.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"**An enhanced command line logging utility.**\n\n[![crates.io](https://img.shields.io/crates/v/stumpless)](https://crates.io/crates/stumpless)\n[![Linux Builds](https://github.com/goatshriek/stumpless-logger/actions/workflows/linux.yml/badge.svg)](https://github.com/goatshriek/stumpless-logger/actions/workflows/linux.yml)\n[![Windows Builds](https://github.com/goatshriek/stumpless-logger/actions/workflows/windows.yml/badge.svg)](https://github.com/goatshriek/stumpless-logger/actions/workflows/windows.yml)\n[![Mac Builds](https://github.com/goatshriek/stumpless-logger/actions/workflows/mac.yml/badge.svg)](https://github.com/goatshriek/stumpless-logger/actions/workflows/mac.yml)\n[![Gitter](https://badges.gitter.im/stumpless/community.svg)](https://gitter.im/stumpless/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n[![Apache 2.0 License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1-ff69b4.svg)](https://github.com/goatshriek/stumpless-logger/blob/latest/docs/CODE_OF_CONDUCT.md)\n\n[Key Features](#key-features) |\n[Basic Usage](#send-your-logs-anywhere) |\n[Contributing](#contributing)\n\n\n## Key Features\nThe stumpless logger aims to be a replacement for and improvement over the\ntraditional `logger` utility. It is written with\n[Rust](https://www.rust-lang.org/) and\n[Stumpless](https://github.com/goatshriek/stumpless), and offers a number of\nimprovements over legacy tools, including:\n\n * more logging target options (files, Windows Event Log)\n * log to multiple destinations with a single invocation\n * portable and tested on Windows and Linux\n * separate thread for each log target\n\n\n## Send Your Logs Anywhere\nThe stumpless logger supports all of the target types that Stumpless provides,\nwhich include everything `logger` has and then some.\n\n\n### The Default Target\nStumpless has the concept of a default target, which attempts to abstract away\nthe most logical place to send logs on your system. For Windows this is the\nWindows Event Log in a log named Stumpless, for Linux and Mac systems this is\n/var/run/syslog or /dev/log, and if all else fails this is a file named\n`stumpless-default.log`. If you don't provide an explicit target to stumpless,\nthis is what it will send logs to.\n\n```sh\nstumpless Send it!\n# where this goes depends on your system!\n```\n\nYou can explicitly send logs to the default target if you want to, for example\nif you need to send to other locations as well as this one, using the\n`--default` option like this:\n\n```sh\nstumpless --default Send it!\n# same as before!\n```\n\n\n#### `stdout` and `stderr`\nIf you just want to print logs, then use the stdout or stderr.\n\n```sh\nstumpless --stdout Hello from Stumpless!\n# \u003c13\u003e1 2023-01-01T19:32:19.802953Z dante stumpless-cli - - - Hello from Stumpless!\n\nstumpless --stderr Stumpless says something went wrong...\n# \u003c13\u003e1 2023-01-01T19:33:08.957079Z dante stumpless-cli - - - Stumpless says something went wrong...\n```\n\n\n#### Files\nStumpless provides an easy way to write logs to files without going through a\nsyslog daemon or abusing stream redirection. The `--log-file` flag lets you\nspecify a file to send logs to, with the predictable choice of `-l` as the short\noption.\n\n```sh\nstumpless --log-file round.log Everything is a file these days\n\ncat round.log\n# \u003c13\u003e1 2023-01-19T02:20:22.984425Z dante stumpless-cli - - - Everything is a file these days\n```\n\nIf you want to write log entries into more than one file, you can just specify\nthis flag multiple times. This is true for most log targets in stumpless, and\nmeans that it's simple to send messages to a variety of diverse locations\nstraight from a shell. Each different log target is handled in its own\nthread to prevent them from blocking one another.\n\n```sh\nstumpless --log-file square.log --log-file triangle.log You get a message, and you get a message!\n\n# note that the timestamp is slightly different in these two messages\ncat square.log\n# \u003c13\u003e1 2023-01-22T01:35:07.112856Z dante stumpless-cli - - - You get a message, and you get a message!\n\ncat triangle.log\n# \u003c13\u003e1 2023-01-22T01:35:07.112963Z dante stumpless-cli - - - You get a message, and you get a message!\n```\n\n\n#### Network\nSending logs to network servers is a common task. Stumpless supports this with\nthe `network` feature, which is enabled by default. This supports both IPv4 and\nIPv6, for both TCP and UDP. You can specify these with the `--tcp4`, `--udp4`,\n`--tcp6`, and `--udp6` options.\n\n```sh\nstumpless --tcp4 one-log-server.example Send this message over TCP on IPv4.\n\nstumpless --udp6 two-log-server.example Send this message over UDP on IPv6.\n\n# of course, you can send multiple messages at once, as with other target types:\nstumpless --tcp6 red-log-server.example \\\n          --udp4 blue-log-server.example \\\n          Send this message to two servers at once!\n```\n\nBy default, these targets use port 514. If you want to use a different port,\nthen use the `--port` option (or `-P` short option) to customize this.\n\n```sh\nstumpless --tcp4 special-snowflake-1.example --port 7777\n          --udp6 special-snowflake-2.exampel --port 8888\n          This message goes to two servers on different ports!\n```\n\n\n#### Sockets\nIf you want to send messages to Unix sockets (such as the traditional\n`/dev/log`), then you can use `--socket`, or `-u` for short (think\n'u' for Unix). You'll note that this is the same option as `logger` uses.\n\n```sh\nstumpless --socket /dev/log Say hello to the daemon for me\n```\n\nSocket logging is only available in builds where the `socket` feature has been\nenabled.\n\n\n#### Journald\nOf course, stumpless can log to systemd's journaling service if desired. This\nuses the same `--journald` option that `logger` users may already be familiar\nwith.\n\n```sh\nstumpless --journald Send this message to the local journald service.\n```\n\nJournald logging is only available in builds where the `journald` feature has\nbeen enabled.\n\n\n#### Windows Event Logs\nOn machines where a Windows Event Log is present, you can send messages to it as\nwell. By default this will go to an application log named \"Stumpless\", but you\nchange this if you want.\n\n```sh\nstumpless --windows-event-log This will go into the Stumpless Application log.\n\n# if you have your own special log, you can send to that instead\nstumpless --windows-event-log=MySpecialLog This is a message for my own special log.\n```\n\nNote that logs don't show up for applications that aren't configured, including\nthe default Stumpless log. If you just want to install the default and use it\nthis way, you can run stumpless with the `--install-wel-default-source` option\nto do this. You can run this by itself if you want to install. Note that this\nrequires enough privileges to make registry changes. It will also point registry\nentries it creates at the stumpless executable for resources it needs, so don't\ndo this until you have stumpless in a place where you plan to leave it.\n\n```sh\n# makes registry entries to install the Stumpless application log\n# these will point at stumpless.exe, so make sure it's where you want it!\n# and that it is in a place that Event Viewer has permissions, if you intend to\n# browse the logs through that application\nstumpless --install-wel-default-source\n```\n\nWindows Event Logging is only available in builds where the `wel` feature has\nbeen enabled.\n\n\n#### Structured Data\nLog entries can often be made easier to parse by using structured data fields.\nYou can add these with the same options as `logger` uses: `--sd-id` adds an\nelement, and any `--sd-param` after this adds more detailed fields to the\nelement. This is easier to understand with some examples:\n\n```sh\n# Note that, as with logger, the quotes are required, and may need to be escaped\n# for your shell. For bash or cmd.exe this might instead be color=\\\"red\\\", for\n#PowerShell color='\\\"red\\\"', and so on.\nstumpless --stdout --sd-id ball --sd-param color=\"red\" --sd-param size=\"medium\" Caught a ball!\n# \u003c13\u003e1 2023-01-28T02:34:50.127Z Angus stumpless-cli - - [ball color=\"red\" size=\"medium\"] Caught a ball!\n\nstumpless --stdout \\\n          --sd-id breadsticks \\\n          --sd-id mainCourse --sd-param meat=\"beef\" --sd-param side=\"potatoes\" \\\n          --sd-id dessert --sd-param type=\"cake\" \\\n          Ate a feast!\n# \u003c13\u003e1 2023-01-28T18:53:14.721851Z dante stumpless-cli - - [breadsticks][mainCourse meat=\"beef\" side=\"potatoes\"][dessert type=\"cake\"] Ate a feast!\n```\n\n\n## Differences Between `stumpless` and `logger`\nThis tool is _not_ written as a drop-in replacement for other `logger`\nimplementations. This is not to say that it is completely different: most of the\noptions are the same, and the general modes of use are the same. But there are\ndifferences that arise from decisions made for simplicity, performance, or\nnecessity. Here are the deviations that are relevant to you if you're already\nfamiliar with or using other loggers.\n\n * The default output with no arguments is determined by the\n   [default target](https://goatshriek.github.io/stumpless/docs/c/latest/target_8h.html#a137ec6ade02951be14bff3572725f076)\n   of the underlying stumpless build instead of `/dev/log`.\n * The time quality structured data element is not included (pending Stumpless\n   implementation of\n   [this feature](https://github.com/goatshriek/stumpless/issues/223)).\n * Network servers IP version and protocol are specified together such as\n   `--tcp4` rather than separately via `-T` or `-d` flags independent of the\n   `-n` flag. This is to support the specification of multiple targets using\n   different combinations in a single invocation.\n * The following flags/modes of operation are not supported:\n   * `--rfc3164` for the RFC 3164 BSD syslog format of messages\n\n\n## Contributing\nNotice a problem or have a feature request? Just create an issue using one of\nthe templates, and we will respond as quickly as we can. You can also look at\nthe project's [Contribution Guidelines](docs/CONTRIBUTING.md) for more details\non the different ways you can give back to the open source community!\n\nIf you want to actually write some code or make an update yourself, there are a\nfew options based on your level of experience and familiarity with making\ncontributions.\n\nThe first option is to browse the list of issues that are marked with the label\n[good first issue](https://github.com/goatshriek/stumpless-logger/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).\nThese issues are selected to be a small but meaningful amount of work, and\ninclude details on the general approach that you can take to complete them. They\nare a great place to start if you are just looking to test the waters of this\nproject or open source contribution in general.\n\nMore experienced developers may prefer to look at the full list of issues on the\nproject, as well as the\n[roadmap](https://github.com/goatshriek/stumpless-logger/blob/latest/docs/roadmap.md).\nIf an item catches your interest, drop a comment in the existing issue or open\na new one if it doesn't exist yet and state your intent to work on it so that\nothers will have a way to know it is underway.\n\nOr perhaps you are just looking for a way to say thanks! If that's the case or\nif there is something that you would prefer to drop me a private message about,\nplease feel free to do so on Twitter with\n[#StumplessLib](https://twitter.com/search?q=%23StumplessLib), or in an\n[email](mailto:joel@goatshriek.com)! I'd love to see you share the project\nwith others or just hear your thoughts on it.\n\n\n## Further Documentation\nIf you're curious about how something in stumpless works that isn't explained\nhere, you can check the appropriate section of the documentation, stored in the\ndocs folder of the repository. Folders in the repository contain their own\nREADME files that detail what they contain and any other relevant information.\nIf you still can't find an answer, submit an issue or head over to\n[gitter](https://gitter.im/stumpless/community) and ask for some help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatshriek%2Fstumpless-logger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoatshriek%2Fstumpless-logger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatshriek%2Fstumpless-logger/lists"}