loggable-and-log

Implements os.log instrumentation in Swift using the @Loggable and #log macros from FrameworkToolbox.

3|2|Updated Sep 13, 2023
One-click install
npx skills add https://github.com/Mx-Iris/FrameworkToolbox --skill loggable-and-log-mx-iris
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: loggable-and-log
Source: https://github.com/Mx-Iris/FrameworkToolbox/tree/main/plugins/framework-toolbox/skills/loggable-and-log
Command: npx skills add https://github.com/Mx-Iris/FrameworkToolbox --skill loggable-and-log-mx-iris

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Adding structured os.log logging to Swift types normally requires hand-written OSLog storage, availability-gated branches for pre-macOS 11 systems, and repetitive subsystem/category boilerplate. This Skill teaches how to use the @Loggable and #log macros from FrameworkToolbox to generate all of that logging infrastructure with zero protocol conformance and zero boilerplate. ## Core Features & Use Cases - Macro-based logger synthesis: Apply @Loggable to a struct, class, enum, or actor to synthesize subsystem, category, _osLog, and logger members, with configurable access level, subsystem, and category. - Unified #log expression macro: Emit log lines that call os.Logger on macOS 11+/iOS 14+ and automatically fall back to the legacy os_log C API on older OS versions, with correct level mapping (.default to notice, .fault to critical). - Privacy, formatting, and named categories: Control privacy levels (.public/.private/.sensitive/.auto), numeric formats, string alignment, and route logs through shared named categories declared as static LogCategory members. - Use Case: While building a networking layer in a Swift framework, annotate APIClient with @Loggable(.internal, subsystem: "com.acme.networking", category: "API") and use #log(.info, ...) calls with privacy-annotated interpolations to get Console.app-filterable diagnostics that also work on iOS 13. ## Quick Start Ask the AI to add @Loggable to your Swift type and insert #log calls with appropriate levels and privacy annotations for its key operations.

Frequently Asked Questions about loggable-and-log

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add os.log logging to a Swift type with @Loggable?

Annotate the type with @Loggable, for example @Loggable struct Foo, after importing FoundationToolbox, os.log, and Foundation. The macro synthesizes subsystem, category, _osLog, and logger members, and you then emit log lines with #log(.info, "message") inside that type.

How do I set a custom subsystem and category for os.Logger in Swift?

Pass string literals to the macro: @Loggable(.internal, subsystem: "com.acme.app", category: "Network"). The access level is the first positional argument, and subsystem and category must be StaticString literals, not runtime String values.

Does #log work on iOS 13 or macOS 10.15?

Yes, #log expands into an availability check that calls os.Logger on macOS 11+/iOS 14+ and falls back to the legacy os_log C API on older systems. Privacy and format options are translated to legacy format specifiers, with .sensitive collapsing to %{private}@.

Why does #log fail to compile in a free function or extension?

The #log expansion references Self.logger and Self._osLog, which only exist on types annotated with @Loggable. Using it in a free function, top-level script, or unannotated type produces a compile error; move the call into a @Loggable type.

Can I use @Loggable and #log on Linux or Windows?

No, both macros are gated on #if canImport(os) because they depend on Apple's os framework. On Linux or Windows the generated logger members do not exist, so cross-platform code must wrap call sites in #if canImport(os).

How do I log to a named category shared across types?

Declare static members on LogCategory, such as extension LogCategory { static let network = LogCategory("network") }, then call #log(.debug, category: .network, "message"). The subsystem stays the enclosing type's own, and category loggers are cached process-wide.