Main singleton (global instance) to tweak the behavior of Ditto's logging infrastructure. More...

#include <Log.hpp>

Public Types
typedef void(*	Callback) (LogLevel, std::string)

Static Public Member Functions
static void	e (std::string const &message)

static void	w (std::string const &message)

static void	i (std::string const &message)

static void	d (std::string const &message)

static void	v (std::string const &message)

static void	process_log_message (LogLevel log_level, std::string const &message)

static bool	get_logging_enabled ()

static void	set_logging_enabled (bool enabled)

static bool	get_emoji_log_level_headings_enabled ()

static void	set_emoji_log_level_headings_enabled (bool enabled)

static LogLevel	get_minimum_log_level ()

static void	set_minimum_log_level (LogLevel log_level)

static void	set_log_file (std::string const &log_file_path)
	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).

static void	disable_log_file ()
	Disables logging to the previously set log file.

static void	set_custom_log_cb (Callback log_cb)
	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).

static std::future< uint64_t >	export_to_file (std::string const &file_path)
	Exports collected logs to a compressed and JSON-encoded file on the local file system.

Detailed Description

Main singleton (global instance) to tweak the behavior of Ditto's logging infrastructure.

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 Log::set_logging_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 Log::export_to_file() for further details on locally collected logs.

Member Function Documentation

◆ export_to_file()

std::future< uint64_t > ditto::Log::export_to_file ( std::string const & file_path )

static

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

Log locally collects a limited amount of logs at debug level and above, periodically discarding old logs. This internal logger is always enabled and works independently of values set with Log::set_logging_enabled() and Log::set_minimum_log_level(). 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 filePath 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.

Parameters

[in] file_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 file_path to have the .jsonl.gz file extension but Ditto won't enforce it, nor correct it.

Exceptions

DittoError 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. More precisely, this may throw:

Returns: the number of bytes written to disk.

◆ get_emoji_log_level_headings_enabled()

bool ditto::Log::get_emoji_log_level_headings_enabled ( )

static

Get whether logging levels are signified using emoji headings.

◆ get_logging_enabled()

bool ditto::Log::get_logging_enabled ( )

static

Get whether logging is enabled or not.

Logs exported through Log::export_to_file() are not affected by this setting and will also include logs emitted when logging is disabled.

◆ get_minimum_log_level()

LogLevel ditto::Log::get_minimum_log_level ( )

static

Get the minimum log level at which logging should be occurring.

Logs exported through Log::export_to_file() are not affected by this setting and include all logs at debug level and above.

◆ set_custom_log_cb()

void ditto::Log::set_custom_log_cb ( Log::Callback log_cb )

static

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).

Parameters

[in] log_cb a callback that is called each time a log statement is issued by Ditto (after filtering by log level).

◆ set_emoji_log_level_headings_enabled()

void ditto::Log::set_emoji_log_level_headings_enabled ( bool enabled )

static

Set whether logging levels are signified using emoji headings.

Parameters

[in] enabled a bool representing whether logging levels are to be signified using emoji headings.

◆ set_log_file()

void ditto::Log::set_log_file ( std::string const & log_file_path )

static

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).

Parameters

[in] log_file_path the file path to be used to write logs at (the file path must be within an already existing directory).

◆ set_logging_enabled()

void ditto::Log::set_logging_enabled ( bool enabled )

static

Set whether Ditto logging is enabled or not.

Logs exported through Log::export_to_file() are not affected by this setting and will also include logs emitted when logging is disabled.

Parameters

[in] enabled a bool representing whether logging should be enabled or not.

◆ set_minimum_log_level()

void ditto::Log::set_minimum_log_level ( LogLevel log_level )

static

Set the minimum log level at which logging should be occurring.

Logs exported through Log::export_to_file() are not affected by this setting and include all logs at debug level and above.

Parameters

[in] log_level the minimum logging level at which logging should be occurring.

Public Types

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ export_to_file()

◆ get_emoji_log_level_headings_enabled()

◆ get_logging_enabled()

◆ get_minimum_log_level()

◆ set_custom_log_cb()

◆ set_emoji_log_level_headings_enabled()

◆ set_log_file()

◆ set_logging_enabled()

◆ set_minimum_log_level()