Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marcransome/flog
A command-line tool for sending log messages to Apple's unified logging system. 🪵
https://github.com/marcransome/flog
command-line macos unified-logging
Last synced: about 2 months ago
JSON representation
A command-line tool for sending log messages to Apple's unified logging system. 🪵
- Host: GitHub
- URL: https://github.com/marcransome/flog
- Owner: marcransome
- License: mit
- Created: 2022-08-13T16:42:24.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-30T17:56:29.000Z (8 months ago)
- Last Synced: 2024-05-01T20:59:56.473Z (8 months ago)
- Topics: command-line, macos, unified-logging
- Language: C
- Homepage:
- Size: 1.27 MB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# flog
[](https://securityscorecards.dev/viewer/?uri=github.com/marcransome/flog) [](https://github.com/marcransome/flog/actions/workflows/codeql-analysis.yml) [](https://github.com/marcransome/flog/issues) [](https://opensource.org/licenses/mit-license.php) [](https://www.apple.com/macos/)
`flog` is a command-line tool for sending log messages to Apple's unified logging system and is primarily intended for use in scripts.
---
## Rationale
> _Why not use `logger(1)`?_
`logger` doesn't support the full set of log levels offered by Apple's unified logging system, and it lacks support for _subsystem_ and _category_ strings. `flog` uses the C language APIs for the unified logging system and supports both.
## Getting started
### Installation
Install with [Homebrew](https://brew.sh):
```shell
brew install marcransome/tap/flog
```
### Logging messages
To log a message using the `default` log level:
```shell
flog ''
```
Optionally specify a _subsystem_ and _category_ using the `-s, --subsystem` and `-c, --category` options:
```shell
flog -s uk.co.fidgetbox -c general 'informational message'
```
Override the default log level using the `-l, --level` option and one of the values `info`, `debug`, `error` or `fault`:
```shell
flog -l fault -s uk.co.fidgetbox -c general 'unrecoverable failure'
```
`flog` can also read the log message from the standard input stream using a pipe:
```shell
./some-script | flog -l info
```
Or the log message can be read from a file using shell redirection:
```shell
flog < /var/log/some-script.log
```
Use the `-a, --append` option to also append the log message to a file (creating the file if necessary):
```shell
flog -a /var/log/some-script.log -l fault -s uk.co.fidgetbox -c general 'unrecoverable failure'
```
> [!WARNING]
> Log message strings are _public_ by default and can be read using the `log(1)` command or [Console](https://support.apple.com/en-gb/guide/console/welcome/mac) app. To mark a message as private add the `-p|--private` option to the command. Doing so will redact the message string, which will be shown as `''` when accessed using the methods previously mentioned. [Device Management Profiles](https://developer.apple.com/documentation/devicemanagement) can be used to grant access to private log messages.
### Reading log messages
Refer to the `log(1)` man page provided on macOS-based systems for extensive documentation on how to access system wide log messages, or alternatively use the [Console](https://support.apple.com/en-gb/guide/console/welcome/mac) app.
Here's an example log stream in Console, filtered by subsystem name, showing messages generated by `flog`:
And here's a similar log stream viewed with Apple's `log(1)` command:
## Development
`flog` is written in C and requires a suitable compiler and additional tools to build from source. The [just](https://github.com/casey/just) command runner is used to manage the development and release process, which functions in a similar manner to `make`. For an overview of the available recipes and their usage run `just --list`.
### Requirements
* macOS `11.x` (Big Sur) or later
* A C17 compiler
* CMake version `>=3.22`
* The [just](https://github.com/casey/just) command runner
* `pkg-config` version `>=0.29.2`
* `libpopt` version `>=1.19`
* `libcmocka` version `>=1.1.7`
* [Pandoc](https://github.com/jgm/pandoc) (if building the `man` page)
### Building from source
To perform a development build from the project directory:
```shell
just build
```
The resulting `flog` binary will be output to a `build/debug/bin` directory and test targets to `build/debug/test`.
### Running unit tests
To build and execute all test targets:
```shell
just test
```
Alternatively, invoke individual test targets directly from the `build/debug/test` directory. All test target files begin with the prefix `test_` followed by the name of the source file under test.
## Building the man page
To build the man page:
```shell
just man
```
The `flog.1` man page is output to the `man` directory and is converted from the source file `man/flog.1.md` using [Pandoc](https://github.com/jgm/pandoc).
## Acknowledgements
* Trunk icon made by [Freepik](https://www.flaticon.com/authors/freepik) from [www.flaticon.com](https://www.flaticon.com/)
## License
`flog` is provided under the terms of the [MIT License](https://opensource.org/licenses/mit-license.php).
## Contact
Email me at [[email protected]](mailto:[email protected]) or [create an issue](https://github.com/marcransome/flog/issues).