SimpleLogger

SimpleLogger is a modern Swift logging utility built on Apple's Unified Logging system (OSLog). It provides strongly typed categories, queryable log access, advanced time-based filtering, and multiple export formats, designed primarily for SwiftUI applications.

Features

• Type-safe logger categories with duplicate detection
• Unified Logging integration (OSLog)
• Observable log manager for SwiftUI
• Advanced filtering
  • Specific date
  • Date range
  • Hour range
  • Rolling presets (minutes → years)
• Export formats
  • Plain text
  • JSON
  • JSON Lines (.jsonl)
  • CSV (configurable delimiters)
  • Optional gzip compression
• System log exclusion
• Severity-level filtering

Installation

Add SimpleLogger to your Swift project using Swift Package Manager.

dependencies: [
  .package(
    url: "https://github.com/markbattistella/SimpleLogger", 
    from: "1.0.0"
  )
]

Alternatively, you can add SimpleLogger using Xcode by navigating to File > Add Packages and entering the package repository URL.

Usage

Basic Usage

SimpleLogger wraps over OSLog.Logger under a simplified name and provides a convenience initialiser that automatically uses your app's bundle identifier as the subsystem.

import SimpleLogger

let logger = Logger(category: .ui)
logger.info("User tapped the start button")

Logger Categories

Categories are strongly typed using LoggerCategory.

Architecture and Patterns

Logger Category	Description
routing	Logger category for routing-related logs.
navigation	Logger category for navigation-related logs.
stateManagement	Logger category for state management-related logs.
dependencyInjection	Logger category for dependency injection-related logs.
observers	Logger category for observer-related logs.
publishers	Logger category for publisher-related logs.
subscribers	Logger category for subscriber-related logs.
events	Logger category for event-related logs.
signals	Logger category for signal-related logs.

Miscellaneous

Logger Category	Description
analytics	Logger category for analytics-related logs.
configuration	Logger category for configuration-related logs.
errorHandling	Logger category for error handling-related logs.
logging	Logger category for logging-related logs.
configurationManagement	Logger category for configuration management-related logs.
imageProcessing	Logger category for image processing-related logs.
videoProcessing	Logger category for video processing-related logs.
audioProcessing	Logger category for audio processing-related logs.
sensors	Logger category for sensor-related logs.
camera	Logger category for camera-related logs.
location	Logger category for location-related logs.
maps	Logger category for maps-related logs.

Networking and Connectivity

Logger Category	Description
network	Logger category for network-related logs.
api	Logger category for API-related logs.
upload	Logger category for upload-related logs.
download	Logger category for download-related logs.
sync	Logger category for synchronisation-related logs.
connectivity	Logger category for connectivity-related logs.
reachability	Logger category for reachability-related logs.
streaming	Logger category for streaming-related logs.
bluetooth	Logger category for Bluetooth-related logs.

Performance and Optimisation

Logger Category	Description
performance	Logger category for performance-related logs.
memoryManagement	Logger category for memory management-related logs.
concurrency	Logger category for concurrency-related logs.
threading	Logger category for threading-related logs.
debugging	Logger category for debugging-related logs.
monitoring	Logger category for monitoring-related logs.

Data Management and Persistence

Logger Category	Description
coreData	Logger category for Core Data-related logs.
swiftData	Logger category for Swift Data-related logs.
database	Logger category for database-related logs.
caching	Logger category for caching-related logs.
persistence	Logger category for persistence-related logs.
serialization	Logger category for serialisation-related logs.
deserialization	Logger category for deserialisation-related logs.
parsing	Logger category for parsing-related logs.
keychain	Logger category for keychain-related logs.
userDefaults	Logger category for UserDefaults-related logs.
backup	Logger category for backup-related logs.
restore	Logger category for restore-related logs.

Security and Permissions

Logger Category	Description
security	Logger category for security-related logs.
encryption	Logger category for encryption-related logs.
decryption	Logger category for decryption-related logs.
permissions	Logger category for permissions-related logs.
authentication	Logger category for authentication-related logs.
authorization	Logger category for authorisation-related logs.

System and OS

Logger Category	Description
lifecycle	Logger category for lifecycle-related logs.
initialization	Logger category for initialisation-related logs.
deinitialization	Logger category for de-initialisation-related logs.
fileSystem	Logger category for file system-related logs.
backgroundTasks	Logger category for background tasks-related logs.
scheduling	Logger category for scheduling-related logs.
notifications	Logger category for notifications-related logs.
timers	Logger category for timers-related logs.

Testing and Validation

Logger Category	Description
testing	Logger category for testing-related logs.
unitTesting	Logger category for unit testing-related logs.
integrationTesting	Logger category for integration testing-related logs.
uiTesting	Logger category for UI testing-related logs.
mocking	Logger category for mocking-related logs.
stubbing	Logger category for stubbing-related logs.
validation	Logger category for validation-related logs.

UI and User Interaction

Logger Category	Description
ui	Logger category for UI-related logs.
gestures	Logger category for gesture-related logs.
animations	Logger category for animation-related logs.
transitions	Logger category for transition-related logs.
accessibility	Logger category for accessibility-related logs.
localization	Logger category for localisation-related logs.
internationalization	Logger category for internationalisation-related logs.
theming	Logger category for theming-related logs.
styling	Logger category for styling-related logs.
layout	Logger category for layout-related logs.
rendering	Logger category for rendering-related logs.

Utilities and Helpers

Logger Category	Description
utils	Logger category for utility-related logs.
extensions	Logger category for extension-related logs.
helpers	Logger category for helper-related logs.
factories	Logger category for factory-related logs.
builders	Logger category for builder-related logs.
commands	Logger category for command-related logs.
handlers	Logger category for handler-related logs.
middlewares	Logger category for middleware-related logs.
interceptors	Logger category for interceptor-related logs.

Custom Categories

You can define your own categories safely:

extension LoggerCategory {
  static let payments = LoggerCategory("Payments")
}

let logger = Logger(category: .payments)

If a duplicate category is registered at runtime (case-insensitive), SimpleLogger logs a warning automatically.

LoggerManager

LoggerManager is the central observable object for fetching, filtering, and exporting logs.

import SwiftUI
import SimpleLogger

@main
struct MyApp: App {
  @StateObject private var loggerManager = LoggerManager()

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environment(loggerManager)
    }
  }
}

Filtering Logs

Filtering is controlled by a filter kind plus associated state.

Filter Kinds

loggerManager.kind = .specificDate

Available kinds:

• .specificDate
• .dateRange
• .hourRange
• .preset

Specific Date

loggerManager.kind = .specificDate
loggerManager.specificDate = Date()

Date Range

loggerManager.kind = .dateRange
loggerManager.dateRangeStart = startDate
loggerManager.dateRangeEnd = endDate

Hour Range

loggerManager.kind = .hourRange
loggerManager.hourRangeDate = Date()
loggerManager.hourRangeStartHour = 9
loggerManager.hourRangeEndHour = 17

Presets

loggerManager.kind = .preset
loggerManager.preset = .lastTwentyFourHours

Presets range from 5 minutes up to 1 year, grouped logically for UI presentation.

Log Levels

You can filter by severity:

loggerManager.levels = [.error, .fault]

Available levels:

• debug
• info
• notice
• error
• fault

Fetching Logs

Fetching is explicit and cancellable.

loggerManager.fetch()

State exposed for UI:

• logs
• isFetching
• hasValidResults
• lastError

Exporting Logs

Exports are asynchronous and return Result<Data, LoggerManagerError>.

Supported Formats

.log
.json
.jsonLines
.csv(.comma | .semicolon | .tab | .pipe)
.gzip(Format)

Example

let result = await loggerManager.export(
  format: .gzip(.jsonLines)
)

switch result {
  case .success(let data):
    // write data to file
  case .failure(let error):
    print(error.localizedDescription)
}

CSV Delimiters

.csv(.semicolon)
.csv(.tab)

All CSV values are safely quoted and escaped.

Error Handling

Errors are surfaced via LoggerManagerError:

.fetch(Error)
.export(Error)

Each error provides a user-friendly errorDescription.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request for any features, fixes, or improvements.

License

SimpleLogger is available under the MIT license. See the LICENCE file for more information.