/ 
Log-Any-Adapter-MacOS-OSLog-0.0.5
/ Log::Any::Adapter::MacOS::OSLog

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 adapter lets Perl applications log directly to macOS' unified logging system 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:

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.

os_category

Not to be confused with Log::Any 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.

private

Optional, defaults to false. A Boolean value indicating whether logged messages should be redacted in the macOS unified logging system.

Log::Any methods

The following Log::Any methods are mapped to macOS os_log(3) functions as follows:

Formatted methods like infof, errorf, etc., are supported via Log::Any'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.

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

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

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.

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.

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

git clone https://codeberg.org/mjgardner/perl-Log-Any-Adapter-MacOS-OSLog.git

AUTHOR

Mark Gardner <mjgardner@cpan.org>

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.