DittoLogger

public class DittoLogger

Class with static methods to customize the logging behavior from Ditto.

Currently, Ditto uses the persistence directory of the Ditto instance that was most recently created to store a limited amount of logs. Ditto may continue writing logs to a persistence directory even after the associated Ditto instance is deallocated. If this is a concern, consider either disabling logging by setting DittoLogger.enabled to false, or instantiating a new Ditto instance. After either of these actions, it is safe to remove the persistence directory. Please refer to DittoLogger.export(to:) for further details on locally collected logs.

  • Represents whether logging is enabled.

    Logs exported through DittoLogger.export(to:) are not affected by this setting and will also include logs emitted while enabled is false.

    Declaration

    Swift

    public static var enabled: Bool { get set }

  • The minimum log level at which logs will be logged, provided the logger is enabled.

    For example if this is set to DittoLogLevel.warning, then only logs that are logged with the Warning or Error log levels will be shown.

    Logs exported through DittoLogger.export(to:) are not affected by this setting and include all logs at DittoLogLevel.debug and above.

    Declaration

    Swift

    public static var minimumLogLevel: DittoLogLevel { get set }

  • Represents whether or not emojis should be used as the log level indicator in the logs.

    Declaration

    Swift

    public static var emojiLogLevelHeadingsEnabled: Bool { get set }

  • Registers a file path where logs will be written to, whenever Ditto wants to issue a log (on top of emitting the log to the console).

    Declaration

    Swift

    public static func setLogFile(_ logFile: String?)

    Parameters

    logFile

    it can be nil, in which case the current logging file, if any, is unregistered, otherwise, the file path must be within an already existing directory.

  • Registers a file path where logs will be written to, whenever Ditto wants to issue a log (on top of emitting the log to the console).

    Declaration

    Swift

    public static func setLogFileURL(_ logFile: URL?)

    Parameters

    logFile

    it can be nil, in which case the current logging file, if any, is unregistered, otherwise, the file path must be within an already existing directory.

  • Registers a callback for a fully customizable way of handling log “events” from the logger (on top of logging to the console, and to a file, if any).

    Declaration

    Swift

    public static func setCustomLogCallback(_ logCb: ((DittoLogLevel, String) -> ())?)

    Parameters

    logCallback

    a block that can be nil, in which case the current callback, if any, is unregistered. Otherwise it is called each time a log statement is issued by Ditto (after filtering by log level).
  • export(to:) Asynchronous

    Exports collected logs to a compressed and JSON-encoded file on the local file system.

    DittoLogger locally collects a limited amount of logs at DittoLogLevel.debug level and above, periodically discarding old logs. This internal logger is always enabled and works independently of the enabled setting and the configured minimumLogLevel. Its logs can be requested and downloaded from any peer that is active in a Ditto app using the portal’s device dashboard. This method provides an alternative way of accessing those logs by exporting them to the local file system.

    The logs will be written as a gzip compressed file at the URL specified by the fileURL parameter. When uncompressed, the file contains one JSON value per line with the oldest entry on the first line (JSON lines format).

    Ditto limits the amount of logs it retains on disk to 15 MB and a maximum age of three days. Older logs are periodically discarded once one of these limits is reached.

    This method currently only exports logs from the most recently created Ditto instance, even when multiple instances are running in the same process.

    Throws

    DittoSwiftError.ioError when the file cannot be written to disk. Prevent this by ensuring that no file exists at the provided URL, all parent directories exists, sufficient permissions are granted, and that the disk is not full.

    Declaration

    Swift

    @discardableResult
public static func export(to fileURL: URL) async throws -> UInt64

    Parameters

    fileURL

    The URL of the file to write the logs to. The file must not already exist, and the containing directory must exist. It is recommended for the fileURL to have the .jsonl.gz file extension but Ditto won’t enforce it, nor correct it.

    Return Value

    Number of bytes written to disk.