The Phoenix Trap

Code, music, philosophy, etc.

Tag: C

Logging from Perl to macOS’ unified log with FFI and Log::Any
Part 1: The elephant in the room

A few weeks ago, I started hosting my own Mastodon instance on a Mac mini in my home office. I wanted to join the social Fediverse on my own terms–but it didn’t take long to notice ballooning disk usage. Cached media from other users’ posts was piling up fast.

That got me thinking: how do I track this growth before it gets out of hand?

Logging seemed like the obvious answer. On Unix and Linux systems, it’s straightforward enough. But on macOS, finding a native, maintainable solution takes more digging.

Part 2: Feeding the Apple

macOS is Unix-based, so you’d expect logging to be simple. You can install logrotate via Homebrew, then schedule it with cron(8). It works–but it adds layers of configuration files, permissions, and guesswork. I wanted something native. Something that felt like it belonged on a Mac.

Turns out, macOS offers two built-in options. One is newsyslog, a BSD-style tool that rotates logs based on size or time. It’s reliable, but it requires privileged root-owned configuration files and feels like a holdover from older Unix systems.

The other is Apple’s unified logging system–a modern API used across macOS, iOS, and even watchOS. It’s structured, searchable, and already baked into the platform. That’s the one I decided to explore.

Howard Oakley’s explainer on the Unified Log helped me understand Apple’s system for consolidating logs. It showed how they are stored in a compressed binary format, complete with structured metadata and privacy controls. With that foundation, I turned to Apple’s OSLog Framework documentation. It showed how to tag entries and filter them with predicates. macOS handles the rest.

It’s elegant–but you need to use the API to write logs. Yes, reading and filtering can be done on the command line or in the Console app. But Apple seems to expect logging to be the sole province of Swift and Objective‑C developers. I’d rather not have to learn a new programming language just to write logs.

UPDATE: Howard Oakley’s blowhole utility provides a simple way to write to the unified log from the command line, but all messages come from the “co.eclecticlight.blowhole” subsystem with a “general” category. We can do better.

Part 3: A platypus in the key of C

I do know Perl. I also know just enough C to be dangerous. And I briefly considered learning Swift or Objective‑C. Nevertheless, I wondered about bridging Perl to Apple’s unified logging system without switching languages.

macOS exposes a C API in <os/log.h>:
```
#include <os/log.h>

void
os_log(os_log_t log, const char *format, ...);

void
os_log_info(os_log_t log, const char *format, ...);

void
os_log_debug(os_log_t log, const char *format, ...);

void
os_log_error(os_log_t log, const char *format, ...);

void
os_log_fault(os_log_t log, const char *format, ...);
```
Perl’s CPAN has a module called FFI::Platypus that would let me call foreign functions in C and other languages. It looked promising.

But there’s a catch: these logging functions are variadic macros, not plain functions. That makes them inaccessible via FFI. Worse, they expand into private API calls–unstable across OS updates and risky to rely upon.

So I wrote a small C wrapper to convert each macro into a proper function. This makes them FFI-safe and lets me control visibility (public logging vs. private, redacted logging) using Apple’s format specifiers:
```
#include <os/log.h>

#define DEFINE_OSLOG_WRAPPERS(level_macro, suffix)    \
    void os_log_##suffix##_public(os_log_t log,       \
                                  const char *msg) {  \
        level_macro(log, "%{public}s", msg);          \
    }                                                 \
    void os_log_##suffix##_private(os_log_t log,      \
                                   const char *msg) { \
        level_macro(log, "%{private}s", msg);         \
    }

// Generate wrappers for each log level
DEFINE_OSLOG_WRAPPERS(os_log, default)
DEFINE_OSLOG_WRAPPERS(os_log_info, info)
DEFINE_OSLOG_WRAPPERS(os_log_debug, debug)
DEFINE_OSLOG_WRAPPERS(os_log_error, error)
DEFINE_OSLOG_WRAPPERS(os_log_fault, fault)
```
This macro generates two functions per log level–one public, one private–giving downstream Perl code a choice. It’s verbose, but it’s safe, auditable, and future-proof.

Part 4: Plugging into Log::Any

With the wrapper library in place, I began mapping Apple’s log levels to something Perl can use. I chose Log::Any from CPAN because it’s lightweight, widely supported, and its adapters don’t lock you into a specific back-end. The same code that logs to the screen can also log to a file, or in our case, Apple’s system.

Admittedly, at this point I’m no longer writing a simple logging script for my Mastodon instance. Instead, it’s a full-fledged logging module. Oh well.

Some Log::Any levels share the same underlying Apple call– OSLog doesn’t distinguish between notice and info or trace and debug. That’s a little different from how Unix syslog does things, but that’s fine. The goal here is compatibility, not perfect fidelity.

Building a simple dispatch table to route log messages based on level, I then used FFI::Platypus to bind each wrapper function:
```
use FFI::Platypus 2.00;

my %OS_LOG_MAP = (
    trace     => 'os_log_debug',
    debug     => 'os_log_debug',
    info      => 'os_log_info',
    notice    => 'os_log_info',
    warning   => 'os_log_fault',
    error     => 'os_log_error',
    critical  => 'os_log_default',
    alert     => 'os_log_default',
    emergency => 'os_log_default',
);

my $ffi = FFI::Platypus->new(
    api => 2,
    lib => [ './liboslogwrapper.dylib' ],
);

$ffi->attach(
    [ os_log_create => '_os_log_create' ],
    [ 'string', 'string' ],
    'opaque',
);

# attach each wrapper function
my %UNIQUE_OS_LOG = map { $_ => 1 } values %OS_LOG_MAP;
foreach my $function ( keys %UNIQUE_OS_LOG ) {
    for my $variant (qw(public private)) {
        my $name = "${function}_$variant";
        $ffi->attach(
            [ $name => "_$name" ],
            [ 'opaque', 'string' ],
            'void',
        );
    }
}
```
This setup gives me a clean way to log from Perl using Apple’s native system. I can achieve this without touching Swift, Objective‑C, or external tools. Each log level maps to a C wrapper, and the FFI layer handles the rest.

Now I just need an init function to create the os_log_t object and a set of methods for logging and detecting whether a given log level is enabled:
```
use strict;
use Carp;
use base qw(Log::Any::Adapter::Base);
use Log::Any::Adapter::Util qw(
  detection_methods
  numeric_level
);

sub init {
    my $self = shift;
    $self->{private} ||= 0;
    croak 'subsystem is required'
      unless defined $self->{subsystem};

    $self->{_os_log} = _os_log_create(
      @{$self}{qw(subsystem category)},
    );

    return;
}

foreach my $log_level ( keys %OS_LOG_MAP ) {
    no strict 'refs';
    *{$log_level} = sub {
        my ( $self, $message ) = @_;

        &{  "_$OS_LOG_MAP{$log_level}_"
                . ( $self->{private}
                    ? 'private'
                    : 'public'
                ) }( $self->{_os_log}, $message );
    };
}

foreach my $method ( detection_methods() ) {
    my $method_level = numeric_level(substr $method 3);
    no strict 'refs';
    *{$method} = sub {
        !!( $method_level <= (
          $_[0]->{log_level} // numeric_level('info')
        ) );
    };
}
```
What’s that “subsystem” bit up there? That’s the term macOS uses for identifying processes in logs. They’re usually formatted in reverse DNS notation (e.g., “com.example.perl”). Once again, Howard Oakley has a great explainer on the topic.

Also, there’s some metaprogramming going on there:
- The first foreach loop creates functions called trace, debug, and info. These functions call the corresponding FFI::Platypus-created functions. It uses the private variants if the private attribute for the log adapter was set.
- The second foreach loop creates creates functions called is_trace, is_debug, is_info, etc., that return true if the adapter is catching that level of log message.
Part 5: At long last, logging… mostly

Once this is packaged in a Perl module, how do you use it? At least that part isn’t too hard:
```
use Log::Any '$log', default_adapter => [
  'MacOS::OSLog', subsystem => 'com.phoenixtrap.perl',
];
use English;
use Carp qw(longmess);

$log->info('Hello from Perl!');
$log->infof('You are using Perl %s', $PERL_VERSION);

$log->trace( longmess('tracing!') );
$log->debug(     'debugging!'     );
$log->info(      'informing!'     );
$log->notice(    'noticing!'      );
$log->warning(   'warning!'       );
$log->error(     'erring!'        );
$log->critical(  'critiquing!'    );
$log->alert(     'alerting!'      );
$log->emergency( 'emerging!'      );
```
And then you can run this command line to stream log messages from the subsytem used above:
```
% log stream --level debug \
  --predicate 'subsystem == "com.phoenixtrap.perl"
```
What happened to the trace and debug log messages that were supposed to call os_log_debug(3)? According to macOS’ log(1) manual page, you have to explicitly allow debugging output for a given subsystem:
```
% sudo log config --mode "level:debug" \
  --subsystem com.phoenixtrap.perl
```
Et voilà!

Hmm, same lack of debugging messages.

I’m still figuring this out. Any clues? Drop me a line!

UPDATE: This is now fixed thanks to some inspiration from the source code of Log::Any::Adapter::Syslog. I’ve updated the code on Codeberg; here is the diff.

Bonus: Fancy output

Thanks to Log::Any::Proxy, you also get sprintf formatting variant functions:
```
use English;
$log->infof(
    'You are using Perl %s in %d',
    $PERL_VERSION, (localtime)[5] + 1900,
);
```
```
You are using Perl v5.40.2 in 2025
```
If you output an object that overloads string representation, you get that string:
```
use DateTime;
$log->infof('It is now %s', DateTime->now);
```
```
It is now 2025-08-10T20:16:50
```
And you get single-line Data::Dumper output of complex data structures, plus replacing undefined values with the string “undef”:
```
$log->info( {
    foo    => 'hello',
    bar    => 'world',
    colors => [ qw(
        red
        green
        blue
    ) ],
    null => undef,
} );
```
```
{bar => "world",colors => ["red","green","blue"],foo => "hello",null => undef}
```
Conclusion: Build once, use everywhere

The best tools aren’t always the ones you planned to build. They’re the ones that solve a problem cleanly–and then solve five more you hadn’t thought of yet.

What started as a quick fix for Mastodon media monitoring became a reusable bridge between Perl and macOS’ Unified Log. Along the way, I got to explore Apple’s logging internals, write an FFI-respecting C wrapper, and integrate cleanly with Log::Any. The resulting code is modular, auditable, and–most importantly–maintainable.

I didn’t set out to write a logging adapter. But when you care about clean ops and reproducible infrastructure, sometimes the best tools are the ones you build yourself. And if they happen to be over-engineered for the task at hand? All the better–they’ll probably outlive it.

Try it out or contribute!

The full adapter code is on Codeberg. If you’re logging from Perl on macOS, give it a spin. Contributions, bug reports, and real-world feedback are welcome–especially if you’re testing it in production or on older macOS versions.

I’ll do my best to stay compatible with past and future macOS and Perl releases. Keeping the code auditable and minimal should help it stay useful without becoming a moving target.
August 10, 2025
Cutting the fat: Lightweight Perl OO modules
This blog has devoted a fair amount of attention to the popular and multifaceted object-oriented system Moose and its lightweight subset Moo. I’ve also covered Object::Pad, the testbed of concepts and syntax for Corinna, the proposed next-generation Perl core OO system. But what if your project is too memory‑, performance‑, or dependency-constrained for these options?

It turns out that CPAN has a rich history of lighter-weight OO modules to meet many different needs. If you can live with their trade-offs, they’re worth investigating instead of rolling your own layer over Perl’s OO. Here are a few.

Class::Struct

Class::Struct’s main claim to fame is its inclusion in the standard Perl distribution, so there’s no need to install dependencies from CPAN. It provides a syntax for defining classes as C‑style structs at either compile time or runtime. (There’s no speed advantage to the former; it just means that your class will be built as if you had written the accessors yourself as subs.) Here’s an example:
```
#!/usr/bin/env perl

use v5.24; # for strict, say, and postfix dereferencing
use warnings;

package Local::MyClass;
use Class::Struct (
    foo => '$',
    bar => '@',
    baz => '%',
);

package main;

my $obj = Local::MyClass->new(
    foo => 'hello',
    bar => [1, 2, 3],
    baz => { name => 'Mark'},
);

say $obj->foo, ' ', $obj->baz('name');
say join ',', $obj->bar->@*;

# replace the name element of baz
$obj->baz(name => 'Sharon');

# replace the second element of bar
$obj->bar(1, 'replaced');
say $obj->foo, ' ', $obj->baz('name');
say join ',', $obj->bar->@*;
```
And here’s the output:
```
hello Mark
1,2,3
hello Sharon
1,replaced,3
```
Note that Class::Struct supports accessors for scalar, array, and hash types, as well as other classes (not demonstrated). Consult the module’s documentation for the different ways to define and retrieve them.

Class::Accessor

Class::Accessor does one thing: it makes accessors and mutators (also known as getters and setters) for fields in your class. Okay, it actually does another thing: it provides your class with a new method to initialize those fields. Those accessors can be read-write, read-only, or write-only. (Why would you want write-only accessors?) You can define any of them using either its historical class methods or a Moose-like attribute syntax.

If you’re trying to squeeze every bit of performance out of your code and can sacrifice a little flexibility in altering accessor behavior, you can opt for Class::Accessor::Fast or Class::Accessor::Faster. The former still uses hash references under the hood to represent objects and the latter uses array references. The main Class::Accessor documentation contains an efficiency comparison of the three for your edification.

Here’s an example script using Class::Accessor::Faster and the Moose-like syntax:
```
#!/usr/bin/env perl

use v5.12; # for strict and say
use warnings;

package Local::MyClass;
use Class::Accessor::Faster 'moose-like';

has readwrite => (is => 'rw');
has readonly  => (is => 'ro');

package main;

my $obj = Local::MyClass->new( { # must be a hash reference
    readwrite => 'hello',
    readonly  => 'world',
} );

say $obj->readwrite, ' ', $obj->readonly;
$obj->readwrite('greetings');
say $obj->readwrite, ' ', $obj->readonly;

# throws an error
$obj->readonly('Cleveland');
```
And here is its output:
```
hello world
greetings world
'main' cannot alter the value of 'readonly' on objects of class 'Local::MyClass' at ./caf.pl line 24.
```
Class::Tiny

Class::Tiny both does less and more than Class::Accessor. All of its generated accessors are read-write, but you can also give their attributes lazy defaults. Its generated constructor takes arguments via either a Class::Accessor-style hash reference or a plain list of key/value pairs, so that’s a little more convenient. It also supports Moose-style BUILDARGS, BUILD, and DEMOLISH methods for argument adjustment, validation, and object cleanup, respectively.

It’s a toss-up as to which of the previous two is “better.” You’ll have to examine their respective features and determine which ones map to your needs.

Here’s an example script that shows a few of Class::Tiny’s unique features:
```
#!/usr/bin/env perl

use v5.12; # for strict and say
use warnings;

package Local::MyClass;
use Class::Tiny qw<foo bar>,
{
    baz       => 'default baz',
    timestamp => sub { time },
};

package main;

my $obj = Local::MyClass->new( # plain key-values OK
    foo => 'hello',
    bar => 'world',
);

say $obj->foo, ' ', $obj->bar;
say 'Object built on ', scalar localtime $obj->timestamp;
$obj->foo('greetings');
$obj->bar('Cleveland');
say $obj->foo, ' ', $obj->bar;
say $obj->baz;
```
And its output:
```
hello world
Object built on Tue Sep  7 09:00:00 2021
greetings Cleveland
default baz
```
Object::Tiny

For an even more minimalist approach, consider Object::Tiny. Its accessors are read-only, it gives you a simple constructor, and that’s it. Its documentation lists a number of reasons why it can be superior to Class::Accessor, including lower memory usage and less typing. There’s also a fork called Object::Tiny::RW that adds read-write support to its accessors.

Class::Tiny’s documentation contains a feature table comparison of it, Object::Tiny, and Class::Accessor. This may help you decide which to use.

Here’s an example script:
```
#!/usr/bin/env perl

use v5.12; # for strict and say
use warnings;

package Local::MyClass;
use Object::Tiny qw<foo bar>;

package main;

my $obj = Local::MyClass->new(
    foo => 'hello',
    bar => 'world',
);

say $obj->foo, ' ', $obj->bar;

# has no effect unless you use Object::Tiny::RW
$obj->foo('greetings');
say $obj->foo, ' ', $obj->bar;
```
And its output:
```
hello world
hello world
```
Add some speed with XS

If the above options are still too slow and you don’t mind requiring a C compiler to install them, there are variants that use Perl’s XS interface instead of pure Perl code:
Roles with Role::Tiny

If you’re eyeing Moose and Moo’s support for roles (also known as traits) as an alternative to inheritance but still want to keep things light with one of the above modules, you’re in luck. The Role::Tiny module lets you compose methods into consuming classes with Moo-like syntax and will pull in Common Lisp Object System-style method modifier support from Class::Method::Modifiers if you need it. It does mean another couple of CPAN dependencies, so if that’s a problem in your situation you’ll just have to live without roles.

Here’s an example script with a role and a consuming class that uses Class::Tiny. The role requires that its consumers implement a required_method, provides a foo method that uses it, and a method modifier for bar.
```
#!/usr/bin/env perl

use v5.12; # for strict and say
use warnings;

package Local::MyRole;
use Role::Tiny;

requires 'required_method';

sub foo {
    my $self = shift;
    say $self->required_method();
}

before bar => sub {
    warn 'About to call bar...';
};

package Local::MyClass;
use Class::Tiny {name => ''};
use Role::Tiny::With;
with 'Local::MyRole';

sub bar {
    my ($self, $greeting) = @_;
    say "$greeting ", $self->name;
}

sub required_method {
    my $self = shift;
    return 'Required by Local::MyRole';
}

package main;

my $obj = Local::MyClass->new(name => 'Mark');
$obj->bar('hello');

$obj->name('Sharon');
$obj->bar('salutations');

$obj->foo();
```
And its output:
```
About to call bar... at ./rt.pl line 17.
hello Mark
About to call bar... at ./rt.pl line 17.
salutations Sharon
Required by Local::MyRole
```
What’s your favorite?

There will always be those who insist on writing everything longhand, but modules like these can save a lot of time and typing as well as reduce errors. Do you have a favorite, maybe something I missed? Let me know in the comments.
September 7, 2021
Paul Evans’ Writing a Core Perl Feature

This upcoming blog series by Perl core contributor Paul Evans promises to be very interesting, as it details what goes into developing and committing a new feature into Perl itself. Evans recently added the isa operator to Perl 5.32, and will be describing how to add a similar (but fictional) feature across 10 or more articles. I’m looking forward to following along.

February 1, 2021