Imported from Mx-Iris/FrameworkToolbox (plugins/framework-toolbox/skills/loggable-and-log/SKILL.md). Install upstream with npx skills add Mx-Iris/FrameworkToolbox --skill loggable-and-log. Copyright stays with the author.

Using @Loggable and #log

Overview

@Loggable and #log are a pair of Swift macros from FoundationToolbox (in the FrameworkToolbox package) that generate os.log-based logging infrastructure for a type with zero protocol conformance and zero boilerplate.

• @Loggable is an attached member macro. It synthesizes subsystem, category, _osLog, and logger storage on the annotated type.
• #log is a freestanding expression macro. It expands into a version-checked branch that calls os.Logger on macOS 11+/iOS 14+/watchOS 7+/tvOS 14+ and falls back to the legacy os_log C API on older OS versions.

Core invariant — they are designed to be used together. #log expands into code that references Self.logger and Self._osLog, which only exist on a type annotated with @Loggable. Using #log outside such a type is a compile error.

When to Use

Use @Loggable + #log instead of any of the following:

• Hand-written os.Logger(subsystem:category:) stored properties
• Hand-written static let _osLog = OSLog(...) plus availability-gated branches
• Conformance to a "Loggable" protocol that exposes logger
• Wrapper functions like log(_ message: String) that lose os_log's static format-string benefits

Skip these macros when:

• The target file does not import FoundationToolbox and adding the dependency is not desired.
• The platform does not have os (e.g., Linux). Both macros are wrapped in #if canImport(os) and the type's logger/_osLog will not exist there.
• The code is in a free function, top-level script, global constant, or extension on a type you cannot annotate with @Loggable — #log requires a Self with the synthesized members.

Quick Reference

Setup

import Foundation
import os.log
import FoundationToolbox

All three imports are required at the call site:

• FoundationToolbox — provides the @Loggable and #log macro declarations.
• os.log — the macro expansions reference OSLog, os_log, and os.Logger directly, so the os module must be in scope. (import os works too.)
• Foundation — @Loggable expands into code that reads Bundle.main.bundleIdentifier (or Bundle(for: self).bundleIdentifier on classes) when no explicit subsystem: is given.

The macros are gated on #if canImport(os), so they are unavailable on platforms without Apple's os framework (Linux, Windows). Code that must compile cross-platform should wrap the call site in #if canImport(os) itself.

@Loggable — Attached Member Macro

Signature

@attached(member, names: named(_osLog), named(category), named(subsystem), named(logger))
public macro Loggable(
    _ accessLevel: AccessLevel = .private,
    subsystem: StaticString? = nil,
    category: StaticString? = nil
)

What it generates

For @Loggable struct UserService { }:

struct UserService {
    private nonisolated static var category: String { "UserService" }
    private nonisolated static var subsystem: String { Bundle.main.bundleIdentifier ?? "UserService" }
    private nonisolated static let _osLog = OSLog(subsystem: subsystem, category: category)

    @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
    private nonisolated static let logger = os.Logger(subsystem: subsystem, category: category)

    @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
    private nonisolated var logger: os.Logger { Self.logger }

    private nonisolated static func _osLog(for category: FoundationToolbox.LogCategory) -> os.OSLog {
        LoggableMacro._sharedOSLog(subsystem: subsystem, category: category.name)
    }

    @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
    private nonisolated static func logger(for category: FoundationToolbox.LogCategory) -> os.Logger {
        LoggableMacro._sharedLogger(subsystem: subsystem, category: category.name)
    }
}

The last two members are the per-category accessors backing #log(category:). They are always generated (on protocols they land in the default-implementation extension), and the runtime helpers cache one os.Logger / OSLog per subsystem/category string pair, shared process-wide.

Parameters

accessLevel — first positional argument, defaults to .private. Accepts .private, .fileprivate, .internal, .package, .public. Controls visibility of every generated member. The default .private is a deliberate choice — most call sites only need to use the logger from inside the type itself.

subsystem: — optional StaticString. When omitted, the macro synthesizes a Bundle-based default:

• For class types: Bundle(for: self).bundleIdentifier ?? "<TypeName>"
• For struct / enum / actor: Bundle.main.bundleIdentifier ?? "<TypeName>"

category: — optional StaticString. When omitted, defaults to the type name as a string literal (e.g., "UserService").

The StaticString requirement means only string literals are accepted. You cannot pass a runtime String, a constant defined elsewhere, or a string-interpolation expression.

Type support

Works on struct, class, enum, and actor. The class variant uses Bundle(for: self) so that the bundle identifier is resolved against the bundle that owns the class — important for frameworks where Bundle.main would resolve to the host app instead of the framework.

MainActor-isolated types are supported because every generated member is marked nonisolated. You can call #log(...) from any actor isolation domain.

#log — Freestanding Expression Macro

Signature

@freestanding(expression)
public macro log(_ level: LoggableMacro.OSLogType, _ message: LoggableMacro.OSLogMessage) -> Void

@freestanding(expression)
public macro log(
    _ level: LoggableMacro.OSLogType,
    category: LogCategory,
    _ message: LoggableMacro.OSLogMessage
) -> Void

What it generates

#log(.debug, "Processing \(value, privacy: .public) with \(secret, privacy: .private)")

expands to:

{
    if #available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *) {
        Self.logger.debug("Processing \(value, privacy: .public) with \(secret, privacy: .private)")
    } else {
        os_log(.debug, log: Self._osLog,
               "Processing %{public}@ with %{private}@",
               "\(value)", "\(secret)")
    }
}()

The expansion is wrapped in an immediately-invoked closure so it remains a single expression and can be used anywhere a Void expression is valid.

Selecting a named category

Declare categories once as static members on LogCategory (the Notification.Name pattern) — the IDE autocompletes them like any other static member:

extension LogCategory {
    static let network = LogCategory("network")
    static let persistence = LogCategory("persistence")
}

Then, inside any @Loggable type, pass one as the category: argument:

#log(.debug, category: .network, "request issued")

expands to:

{
    if #available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *) {
        Self.logger(for: .network).debug("request issued")
    } else {
        os_log(.debug, log: Self._osLog(for: .network), "request issued")
    }
}()

Notes:

• Categories are app-global values, shareable across types; the subsystem always stays the enclosing type's own.
• The category expression is transplanted verbatim into the expansion, so any LogCategory expression works — .network, LogCategory("adhoc"), or a stored constant — and is evaluated at runtime like a normal function argument.
• The category logger is resolved through a process-wide cache keyed by the subsystem/category pair, so repeated calls reuse one os.Logger instance.

Log level mapping

The level passed to #log maps differently to the modern and legacy APIs:

Note the modern-API names: .default becomes notice(_:), and .fault becomes critical(_:). Apple chose those modern names to match the OS log severity model; the macro hides the discrepancy.

Privacy

Privacy values accepted in interpolation:

The legacy fallback intentionally errs on the side of visibility: if you don't specify privacy, the value is logged publicly. This matches what os_log would do without an explicit privacy qualifier and avoids accidentally redacting useful diagnostics on older OS versions. If you need a value to remain private on every supported OS, annotate it explicitly with .private or .sensitive.

Format and alignment

Interpolation supports the same format: and align: parameters as OSLogMessage:

#log(.info, "id: \(id, format: .hex, privacy: .public)")
#log(.info, "name: \(s, align: .left(columns: 20), privacy: .public)")
#log(.debug, "val: \(n, format: .decimal(minDigits: 4), align: .right(columns: 10), privacy: .private)")
#log(.info, "pi: \(pi, format: .fixed(precision: 2))")

On macOS 11+ these parameters are passed through to os.Logger verbatim. On the legacy fallback, formatting and alignment are stripped — every interpolation becomes a %{privacy}@ specifier with the value coerced via "\(value)". This is a deliberate trade-off: legacy os_log does not support the modern interpolation surface area, so the macro produces a correct, simple format string instead of attempting to translate every option.

Percent literals

A literal % in the format string is automatically escaped to %% in the legacy branch so that os_log does not interpret it as a format specifier. The modern branch is unaffected.

#log(.info, "100% done: \(x)")
// legacy: os_log(.info, log: Self._osLog, "100%% done: %{public}@", "\(x)")

Critical Constraints

1. #log must be inside a type annotated with @Loggable (or one that otherwise provides Self.logger and Self._osLog with matching shapes). The expansion references Self.logger and Self._osLog — using it from a free function or top-level script will fail to compile.
2. subsystem: and category: arguments must be string literals. They are typed as StaticString? and the macro extracts the source via StringLiteralExprSyntax. Passing a let constant: String = "..." will not compile.
3. accessLevel is positional, not labeled. Write @Loggable(.public), not @Loggable(accessLevel: .public). The other two parameters are labeled.
4. Both macros require canImport(os). They are unavailable on Linux/Windows. Wrap cross-platform call sites in #if canImport(os).
5. Generated members are nonisolated. This is intentional — it lets you log from any isolation domain. Do not try to redeclare logger with a different isolation; the synthesized one is final.
6. @Loggable does not add protocol conformance. It directly synthesizes members. There is a separate Loggable protocol in FoundationToolbox/Loggable.swift, but it exists for manual opt-in (e.g., extending a type you cannot annotate). The macro path and the protocol path are independent.

Common Mistakes

Worked Example

import Foundation
import os.log
import FoundationToolbox

@Loggable(.internal, subsystem: "com.acme.networking", category: "API")
final class APIClient {
    func send(_ request: URLRequest) async throws -> Data {
        #log(.info, "Sending \(request.httpMethod ?? "GET", privacy: .public) to \(request.url?.absoluteString ?? "", privacy: .private)")

        do {
            let (data, response) = try await URLSession.shared.data(for: request)
            #log(.debug, "Got \(data.count, format: .byteCount, privacy: .public) bytes from \((response as? HTTPURLResponse)?.statusCode ?? -1, privacy: .public)")
            return data
        } catch {
            #log(.error, "Request failed: \(error)")
            throw error
        }
    }
}

Decisions made above:

• .internal access level so other types in the same module can read APIClient.logger (e.g., for testing) but consumers of the framework cannot.
• Explicit subsystem so the logger ends up under com.acme.networking regardless of which app embeds the framework.
• category: "API" instead of the auto-derived "APIClient" — categories are the granularity used in log stream --predicate and Console.app filtering, so a stable, human-readable name is more useful than the type name.
• .private for the URL because URLs frequently contain query parameters with PII.
• .public for HTTP method and status code because they are operational data with no privacy concern.
• .byteCount format on the response size for human-readable Console output.
• Plain \(error) for the error — OSLogMessage has an Error overload, and the legacy fallback will String-coerce it.

Reference: source files

• Sources/FoundationToolbox/Macros/LoggableMacro.swift — macro declaration and doc comment for @Loggable.
• Sources/FoundationToolbox/Macros/LogMacro.swift — macro declaration and doc comment for #log, plus the LoggableMacro namespace types (OSLogType, OSLogPrivacy, OSLogMessage, etc.) that exist purely to give IDE autocomplete in interpolation positions.
• Sources/FoundationToolboxMacros/LoggableMacro.swift — implementation of the member macro.
• Sources/FoundationToolboxMacros/LogMacro.swift — implementation of the expression macro, including the legacy-format builder and privacy-name mapping.
• Sources/FoundationToolbox/LogCategory.swift — the LogCategory struct users extend with static members for #log(category:).
• Sources/FoundationToolbox/Loggable.swift — the (separate, optional) Loggable protocol for manual opt-in, plus the shared per-subsystem/category logger caches.
• Tests/FoundationToolboxMacroTests/LoggingMacroTests.swift — golden expansion tests covering every access level, every type kind, every level, every privacy variant, mask variants, format/align passthrough, and percent escaping. Read these to confirm exact expansion shape before changing call sites.