{"id":19498051,"url":"https://github.com/marcransome/flog","last_synced_at":"2025-04-25T22:32:51.798Z","repository":{"id":56743199,"uuid":"524454257","full_name":"marcransome/flog","owner":"marcransome","description":"A command-line tool for sending log messages to Apple's unified logging system. 🪵","archived":false,"fork":false,"pushed_at":"2024-04-30T17:56:29.000Z","size":1334,"stargazers_count":4,"open_issues_count":8,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-01T20:59:56.473Z","etag":null,"topics":["command-line","macos","unified-logging"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcransome.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"marcransome"}},"created_at":"2022-08-13T16:42:24.000Z","updated_at":"2024-05-06T18:54:36.465Z","dependencies_parsed_at":"2023-02-18T18:01:47.020Z","dependency_job_id":"b983fd18-7d33-4aa8-b930-4021b966a342","html_url":"https://github.com/marcransome/flog","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fflog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fflog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fflog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fflog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcransome","download_url":"https://codeload.github.com/marcransome/flog/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224019638,"owners_count":17242176,"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":["command-line","macos","unified-logging"],"created_at":"2024-11-10T21:49:04.955Z","updated_at":"2025-04-25T22:32:51.785Z","avatar_url":"https://github.com/marcransome.png","language":"C","funding_links":["https://github.com/sponsors/marcransome"],"categories":[],"sub_categories":[],"readme":"\u003cimg alt=\"flog\" src=\"images/trunk.png\" width=\"180\" align=\"right\"\u003e\n\n# flog\n\n[![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/marcransome/flog?label=OpenSSF%20Scorecard)](https://securityscorecards.dev/viewer/?uri=github.com/marcransome/flog) [![CodeQL](https://github.com/marcransome/flog/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/marcransome/flog/actions/workflows/codeql-analysis.yml) [![Issues](https://img.shields.io/github/issues/marcransome/flog)](https://github.com/marcransome/flog/issues) [![License](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/mit-license.php) [![macOS](https://img.shields.io/badge/macOS-11+-blue)](https://www.apple.com/macos/)\n\n`flog` is a command-line tool for sending log messages to Apple's unified logging system and is primarily intended for use in scripts.\n\n---\n\n## Rationale\n\n\u003e _Why not use `logger(1)`?_\n\n`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.\n\n## Installation\n\nInstall with [Homebrew](https://brew.sh):\n\n```shell\nbrew install marcransome/tap/flog\n```\n\n## Logging messages\n\nTo log a message using the `default` log level:\n\n```shell\nflog '\u003cmessage\u003e'\n```\n\nOptionally specify a _subsystem_ and _category_ using the `-s, --subsystem` and `-c, --category` options:\n\n```shell\nflog -s uk.co.fidgetbox -c general 'informational message'\n```\n\nOverride the default log level using the `-l, --level` option and one of the values `info`, `debug`, `error` or `fault`:\n\n```shell\nflog -l fault -s uk.co.fidgetbox -c general 'unrecoverable failure'\n```\n\n`flog` can also read the log message from the standard input stream using a pipe:\n\n```shell\n./some-script | flog -l info\n```\n\nOr the log message can be read from a file using shell redirection:\n\n```shell\nflog \u003c /var/log/some-script.log\n```\n\nUse the `-a, --append` option to also append the log message to a file (creating the file if necessary):\n\n```shell\nflog -a /var/log/some-script.log -l fault -s uk.co.fidgetbox -c general 'unrecoverable failure'\n```\n\n\u003e [!WARNING]\n\u003e 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 `'\u003cprivate\u003e'` 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.\n\n## Reading log messages\n\nRefer 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.\n\nHere's an example log stream in Console, filtered by subsystem name, showing messages generated by `flog`:\n\n\u003cimg width=\"1004\" alt=\"console\" src=\"images/console.png\"\u003e\n\nAnd here's a similar log stream viewed with Apple's `log(1)` command:\n\n\u003cimg width=\"995\" alt=\"log\" src=\"images/log.png\"\u003e\n\n## Option Aliasing\n\n`flog` supports option aliasing (via the `libpopt` library). An alias is an arbitrary name which expands to one or more command-line options, making repeat operations less verbose and allowing for sets of options to be grouped contextually by name.\n\nFor example, the `--runtime-failure` alias below expands to the command-line options `-l fault -s uk.co.fidgetbox.server -c runtime`:\n\n```shell\n$ flog --runtime-failure \"Expected a numeric value to be provided\"\n```\n\nUser-defined aliases can be added to the files `/etc/popt` and `$HOME/.popt`, both of which can contain an arbitrary number of aliases. Each alias should be formatted as:\n\n```\nuk.co.fidgetbox.flog alias \u003calias-name\u003e \u003coptions\u003e\n```\n\nFor the previous example, the entry would read:\n\n```\nuk.co.fidgetbox.flog alias --runtime--failure -l fault -s uk.co.fidgetbox.server -c runtime\n```\n\n## Development\n\n`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`.\n\n### Requirements\n\n* macOS `11.x` (Big Sur) or later\n* A C17 compiler\n* CMake version `\u003e=3.22`\n* The [just](https://github.com/casey/just) command runner\n* `pkg-config` version `\u003e=0.29.2`\n* `libpopt` version `\u003e=1.19`\n* `libcmocka` version `\u003e=1.1.7`\n* [Pandoc](https://github.com/jgm/pandoc) (if building the `man` page)\n\n### Building from source\n\nTo perform a development build from the project directory:\n\n```shell\njust build\n```\n\nThe resulting `flog` binary will be output to a `build/debug/bin` directory and test targets to `build/debug/test`.\n\n### Running unit tests\n\nTo build and execute all test targets:\n\n```shell\njust test\n```\n\nAlternatively, 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.\n\n## Building the man page\n\nTo build the man page:\n\n```shell\njust man\n```\n\nThe `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).\n\n## Acknowledgements\n\n* Trunk icon made by [Freepik](https://www.flaticon.com/authors/freepik) from [www.flaticon.com](https://www.flaticon.com/)\n\n## License\n\n`flog` is provided under the terms of the [MIT License](https://opensource.org/licenses/mit-license.php).\n\n## Contact\n\nEmail me at [marc.ransome@fidgetbox.co.uk](mailto:marc.ransome@fidgetbox.co.uk) or [create an issue](https://github.com/marcransome/flog/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcransome%2Fflog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcransome%2Fflog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcransome%2Fflog/lists"}