Class DittoLogger

java.lang.Object
com.ditto.java.DittoLogger
public class DittoLogger extends Object

Singleton with static methods to customize Ditto's logging behavior.

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 setEnabled(boolean) to false, or instantiating a new Ditto instance. After either of these actions, it is safe to remove the persistence directory.

Please refer to exportToFileBlocking(String) for further details on locally collected logs.

  • Method Details

    • isEnabled

      public static boolean isEnabled()

      Checks whether logging is enabled.

      Logs exported through exportToFileBlocking(String) are not affected by this setting and will also include logs emitted while isEnabled() is false.

      Returns:
      true if logging is enabled, false otherwise.

    • setEnabled

      public static void setEnabled(boolean newValue)

      Sets whether logging is enabled.

      Logs exported through exportToFileBlocking(String) are not affected by this setting and will also include logs emitted while isEnabled() is false.

      Parameters:
      newValue - true to enable logging, false to disable.

    • getMinimumLogLevel

      public static @NonNull DittoLogLevel getMinimumLogLevel()

      Returns the minimum log level at which logs will be logged, provided isEnabled() is true.

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

      Logs exported through exportToFileBlocking(String) are not affected by this setting and include all logs at DittoLogLevel.DEBUG and above.

      Returns:
      the minimum DittoLogLevel.

    • setMinimumLogLevel

      public static void setMinimumLogLevel(@NonNull DittoLogLevel logLevel)

      Sets the minimum log level at which logs will be logged, provided isEnabled() is true.

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

      Logs exported through exportToFileBlocking(String) are not affected by this setting and include all logs at DittoLogLevel.DEBUG and above.

      Parameters:
      logLevel - the minimum DittoLogLevel.

    • exportToFileBlocking

      public static @NonNull DittoULong exportToFileBlocking(@NonNull String path) throws DittoException

      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 isEnabled() setting and the configured getMinimumLogLevel(). 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 path specified by the path parameter. When uncompressed, the file contains one JSON value per line with the oldest entry on the first line (JSON lines format).

      By default, Ditto limits the amount of logs it retains on disk to 15 MB and a maximum age of 15 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.

      For more granular exception handling check the DittoException.IoExceptionReason subtypes.

      Parameters:
      path - the path 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 path to have a .jsonl.gz file extension but Ditto won't enforce it.
      Returns:
      the number of bytes written to disk.
      Throws:
      DittoException - when the file cannot be written to disk. Prevent this by ensuring that no file exists at the provided path, all parent directories exist, sufficient permissions are granted, and that the disk is not full.
      See Also:

    • setLogFile

      public static void setLogFile(@Nullable String logFile)

      Registers a file path where logs will be written, in addition to console output.

      Whenever Ditto emits a log, it will be written to both the console and the specified file.

      Parameters:
      logFile - the file path where logs should be written, or null to unregister the current logging file. If not null, the file path must be within an already existing directory.

    • setCustomLogCallback

      public static void setCustomLogCallback(@NonNull DittoLogCallback logCallback)

      Registers a callback for custom handling of log events.

      This provides a fully customizable way of handling log events from the logger, in addition to logging to the console and to a file (if configured).

      Parameters:
      logCallback - the DittoLogCallback to be called each time a log statement is issued by Ditto (after filtering by log level). Must not be null.

    • unsetCustomLogCallback

      public static void unsetCustomLogCallback()

      Unregisters the currently registered custom log callback.

      After calling this method, the custom callback (if any was set) will no longer be invoked.