# NAME Log::Any::Adapter::MacOS::OSLog - log to macOS' unified logging system # VERSION version 0.0.5 # SYNOPSIS use Log::Any::Adapter ('MacOS::OSLog', subsystem => 'com.example.foo', ); # or use Log::Any::Adapter; Log::Any::Adapter->set('MacOS::OSLog', subsystem => 'org.example.bar', ); # You can override defaults: Log::Any::Adapter->set('MacOS::OSLog', subsystem => 'net.example.baz', os_category => 'secret', private => 1, ); # DESCRIPTION This [Log::Any](https://metacpan.org/pod/Log%3A%3AAny) adapter lets Perl applications log directly to macOS' [unified logging system](https://developer.apple.com/documentation/os/logging) using FFI and C wrappers--no Swift required. To send log entries easily from the command line, a `maclog` utility script is also included in this distribution. # METHODS ## init This method is not called directly, but rather is passed named arguments as a hash when setting a [Log::Any::Adapter](https://metacpan.org/pod/Log%3A%3AAny%3A%3AAdapter): - subsystem Required. Must be a reversed fully-qualified domain name (FQDN), e.g., `com.example.perl`. - log\_level, min\_level, level These are all synonymous and strings that set the minimum logging level for the adapter. Whatever level is set, messages for that level and above will be logged. Defaults to `trace` and is affected by various [environment variables](#configuration-and-environment). - os\_category Not to be confused with [Log::Any categories](https://metacpan.org/pod/Log%3A%3AAny#CATEGORIES), this is used to categorize log entries in the unified log. However, just to keep things simple, it defaults to the name of the category used by [Log::Any](https://metacpan.org/pod/Log%3A%3AAny). - private Optional, defaults to false. A Boolean value indicating whether logged messages should be redacted in the macOS unified logging system. ## [Log::Any](https://metacpan.org/pod/Log%3A%3AAny) methods The following [Log::Any](https://metacpan.org/pod/Log%3A%3AAny) methods are mapped to macOS [os\_log(3)](http://man.he.net/man3/os_log) functions as follows: - trace: [os\_log\_debug(3)](http://man.he.net/man3/os_log_debug) - debug: [os\_log\_debug(3)](http://man.he.net/man3/os_log_debug) - info (or inform): [os\_log\_info(3)](http://man.he.net/man3/os_log_info) - notice: [os\_log\_info(3)](http://man.he.net/man3/os_log_info) - warning: [os\_log\_fault(3)](http://man.he.net/man3/os_log_fault) - error (or err): [os\_log\_error(3)](http://man.he.net/man3/os_log_error) - critical (or crit or fatal): [os\_log(3)](http://man.he.net/man3/os_log) - alert: [os\_log(3)](http://man.he.net/man3/os_log) - emergency: [os\_log(3)](http://man.he.net/man3/os_log) Formatted methods like `infof`, `errorf`, etc., are supported via [Log::Any](https://metacpan.org/pod/Log%3A%3AAny)'s standard interface. # DIAGNOSTICS Using this adapter without specifying a properly-formatted `subsystem` argument will throw an exception. # CONFIGURATION AND ENVIRONMENT Configure the same as [Log::Any](https://metacpan.org/pod/Log%3A%3AAny). The following environment variables can set the logging level if no level is set on the adapter itself: - `TRACE` sets the minimum level to **trace** - `DEBUG` sets the minimum level to **debug** - `VERBOSE` sets the minimum level to **info** - `QUIET` sets the minimum level to **error** In addition, the `LOG_LEVEL` environment variable may be set to a string indicating the desired logging level. # DEPENDENCIES - [Log::Any::Adapter::Base](https://metacpan.org/pod/Log%3A%3AAny%3A%3AAdapter%3A%3ABase) - [Log::Any::Adapter::Util](https://metacpan.org/pod/Log%3A%3AAny%3A%3AAdapter%3A%3AUtil) - [FFI::Platypus](https://metacpan.org/pod/FFI%3A%3APlatypus) 2.00 or greater - [namespace::autoclean](https://metacpan.org/pod/namespace%3A%3Aautoclean) # INCOMPATIBILITIES Because this module relies on the macOS unified logging system introduced in macOS Sierra version 10.12, it is incompatible with earlier versions of OS X, Mac OS X, the classic Mac OS, and all other non-Apple platforms (Microsoft Windows, Linux, other Unixes, etc.). It could conceivably be built and run on Apple iOS, iPadOS, tvOS, and watchOS, but you'd have to build and deploy a native version of Perl itself on those systems. # BUGS AND LIMITATIONS Undoubtedly. Open an issue in the tracker. # SEE ALSO - `maclog`, a utility script included in this distribution, used to send log entries easily from the command line or other scripts - For a full write-up on the rationale, implementation, and integration details, see [the blog post](https://phoenixtrap.com/2025/08/10/perl-macos-oslog). - Apple's [unified logging system developer documentation](https://developer.apple.com/documentation/os/logging) - Apple's [OSLog developer documentation](https://developer.apple.com/documentation/OSLog) - The Eclectic Light Company's [explainer on macOS logs](https://eclecticlight.co/2021/09/27/explainer-logs/) - The Eclectic Light Company's [explainer on macOS subsystem identifiers](https://eclecticlight.co/2022/08/27/explainer-subsystems/) # SUPPORT ## Perldoc You can find documentation for this module with the perldoc command. perldoc Log::Any::Adapter::MacOS::OSLog ## Websites The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources. - MetaCPAN A modern, open-source CPAN search engine, useful to view POD in HTML format. [https://metacpan.org/release/Log-Any-Adapter-MacOS-OSLog](https://metacpan.org/release/Log-Any-Adapter-MacOS-OSLog) - RT: CPAN's Bug Tracker The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN. [https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Any-Adapter-MacOS-OSLog](https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Any-Adapter-MacOS-OSLog) - CPANTS The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution. [http://cpants.cpanauthors.org/dist/Log-Any-Adapter-MacOS-OSLog](http://cpants.cpanauthors.org/dist/Log-Any-Adapter-MacOS-OSLog) - CPAN Testers The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions. [http://www.cpantesters.org/distro/L/Log-Any-Adapter-MacOS-OSLog](http://www.cpantesters.org/distro/L/Log-Any-Adapter-MacOS-OSLog) - CPAN Testers Matrix The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms. [http://matrix.cpantesters.org/?dist=Log-Any-Adapter-MacOS-OSLog](http://matrix.cpantesters.org/?dist=Log-Any-Adapter-MacOS-OSLog) - CPAN Testers Dependencies The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution. [http://deps.cpantesters.org/?module=Log::Any::Adapter::MacOS::OSLog](http://deps.cpantesters.org/?module=Log::Any::Adapter::MacOS::OSLog) ## Bugs / Feature Requests Please report any bugs or feature requests through the web interface at [https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog/issues](https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog/issues). ## Source Code The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :) [https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog](https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog) git clone https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog.git # AUTHOR Mark Gardner # COPYRIGHT AND LICENSE This software is copyright (c) 2025 by Mark Gardner. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.