Logging for Swift SDK

How to enable logging

Use the following code to enable logging:

import PubNubSDK
import Foundation

// Configure PubNub logging system
func configureLogging() {
    // Set logging levels
    // Available options: .all, .debug, .info, .event, .warn, .error, .log
    // You can also combine them: [.event, .warn, .error]
    PubNub.log.levels = [.all]  // This enables all logging

    if #available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *) {
        // OSLogWriter integrates with Apple's native logging system
        PubNub.log.writers = [OSLogWriter()]
    } else {
        // Fallback on earlier versions

show all 18 lines

PubNub log runner

The PubNub log runner is a singleton instance, and should be configured once at the beginning of your application's lifecycle. Changing log properties will overwrite their previous entries.

OSLogWriter

Starting from version 9.0.0, the PubNub Swift SDK uses the OSLogWriter for logging, which integrates with Apple's native logging system.

PubNub.log.writers = [OSLogWriter()]

OSLogWriter provides several advantages:

• Integrates with Apple's native logging system
• Better performance and security
• Proper handling of sensitive data
• Logs can be viewed in Apple's Console app

Minimum OS requirements

OSLogWriter requires iOS 14.0+, macOS 11.0+, watchOS 7.0+, or tvOS 14.0+. If your app supports earlier OS versions, you should use conditional checks as shown in the How to enable logging example at the beginning of this document, which demonstrates how to use OSLogWriter on newer OS versions and fall back to ConsoleLogWriter and FileLogWriter on older versions.

Create custom log writers

You can create a custom log writer if you want to output logs to a specific destination.

To create a custom log writer, implement the LogWriter protocol, then add an instance of your custom writer to the PubNub.log.writers property.

// Custom Log Writer Implementation
class CustomLogWriter: LogWriter {
    // Required by LogWriter protocol
    public let executor: LogExecutable
    public let prefix: LogPrefix
    
    init(prefix: LogPrefix = .all) {
        self.prefix = prefix
        self.executor = LogExecutionType.sync(lock: NSRecursiveLock())
    }
    
    // Required method to handle log messages
    public func send(
        message: @escaping @autoclosure () -> String, 
        withType logType: LogType, 

show all 25 lines

An example of custom log writer usage:

// Create and use custom log writer
PubNub.log.writers = [CustomLogWriter()]

Log level reference

Log levels are as follows:

Log Level	Bitmask	Description
none	0	Logging is disabled.
debug	1 << 0	May be useful during development or while troubleshooting a specific problem. Warning! Debug logging is intended for use in a development environment. Don't use it shipping software.
info	1 << 1	Information that may be helpful, but isn't essential, for troubleshooting errors.
event	1 << 2	Logs as part of an event stream
warn	1 << 3	Designates potentially harmful situations.
error	1 << 4	Error-level messages are intended for reporting process-level errors. If an activity object exists, logging at this level captures information for the entire process chain.
log	1 << 31	This is a special category used to log errors that occur internal to the logger.
all	UInt32.max	All log levels will be captured

Set log levels

Configure log levels by assigning the PubNub.log.levels array property to your desired log levels, as in the following examples.

Enable all logging

// Enable all logging levels - this captures everything including debug information
// Useful during development to see all SDK operations
PubNub.log.levels = [.all]

Enable only error logging

// Enable only error logging - captures only critical errors
// Useful for production environments where you only want to know about serious issues
PubNub.log.levels = [.error]

Enable non-debug level logging

// Enable all standard logging levels except debug information
// This gives good visibility without excessive detail
// - .log: Standard log messages
// - .error: Error messages
// - .warn: Warning messages
// - .event: Significant event notifications
// - .info: Informational messages
PubNub.log.levels = [.log, .error, .warn, .event, .info]

Disable logging with either of the following

// Method 1: Set to .none explicitly
PubNub.log.levels = [.none]

// Method 2: Use an empty set to disable all logging
PubNub.log.levels = []

Disable logging with either of the following

// Method 1: Set to .none explicitly
PubNub.log.levels = [.none]

// Method 2: Use an empty set to disable all logging
PubNub.log.levels = []

Log filtering in Xcode

When using OSLogWriter, logs are integrated with Apple's native logging system, which allows for powerful filtering capabilities in Xcode's console and Apple's Console app.

Subsystem and categories

PubNub logs are organized using:

• Subsystem: Identifies the PubNub SDK in logs, making it easier to find SDK-specific logs in your application by filtering through com.pubnub.

• Categories: Used for more detailed classification of logs:

  • Networking: Logs related to network operations
  • PubNub: Logs related to method calls on the PubNub class object
  • Crypto: Logs related to CryptoModule (encryption/decryption activities)
  • EventEngine: Logs related to subscription and presence event workflow (when enableEventEngine is set to true)

Filtering logs in Xcode

While all log writers will record category information, the filtering capabilities in Xcode's console are only available when using OSLogWriter.

To filter logs in Xcode:

1. Run your application in debug mode.
2. Open the Xcode console.
3. Use the search field to filter by subsystem or category.
4. You can also use the built-in filter buttons in the console to focus on specific log types.

This filtering capability makes it much easier to debug specific aspects of the PubNub SDK's operation in complex applications.