The Residue class provides helper methods to connect and interact to residue server seamlessly. More...

#include <residue.h>

Public Types
enum	Flag : unsigned int { NONE = 0, ALLOW_UNKNOWN_LOGGERS = 1, ALLOW_BULK_LOG_REQUEST = 16, COMPRESSION = 256 }
	Server flags enum that are relavant to the client.

enum	InternalLoggingLevel : std::int8_t { crazy = 0, debug = 1, info = 2, warning = 3, error = 4, none = 5 }

Public Member Functions
	Residue (Residue &&)=delete

	Residue (const Residue &)=delete

Residue &	operator= (const Residue &)=delete

std::string	crashHandlerLoggerId () const noexcept
	Crash handler logger. Not for public use.

unsigned long	getTimestamp () const noexcept
	Gets timestamp for replay attack prevention. This function always uses unix-time for comparison.

std::string	serverVersion () const noexcept

Static Public Member Functions
static Residue &	instance () noexcept
	Singleton instance.

static std::string	version () noexcept
	Version of Residue library.

static std::string	info () noexcept
	Version of Residue library and dependencies.

static void	connect (const std::string &host, int port)
	Connect to residue on specified host and port. More...

static void	connect (int port)
	Connect to residue on localhost. More...

static void	connect (const std::string &host)
	Connect to residue using default port. More...

static void	connect ()
	Connect to residue on localhost using default port. This is more useful when you have client ID so you won't have varying client IDs. More...

static void	reconnect (const std::string &host="", int port=-1)
	Reconnects residue server using new or initially provided parameters. (Disconnect then connect) More...

static bool	connected () noexcept
	Check connection to the server. More...

static const std::string &	clientId () noexcept
	Returns current client ID. Returns empty if not connected.

static bool	connecting () noexcept
	Check connection to the server. More...

static unsigned int	maxBulkSize () noexcept
	If connected this identifies maximum number of items in bulk that server accepts.

static unsigned int	serverFlags () noexcept
	If connected this identifies server flags.

static void	disconnect () noexcept
	Safely disconnects from the server. This will also call wait() More...

static void	wait () noexcept
	Wait to dispatch all the log requests to the server.

static void	setApplicationId (const std::string &id) noexcept
	Application ID is what gets passed on to the server for app format specifier.

static void	setResidueHomePath (const std::string &path) noexcept
	Sets residue home path for $RESIDUE_HOME.

static void	enableBulkDispatch ()
	enableBulkDispatch turns on bulk dispatch. More...

static void	disableBulkDispatch () noexcept
	disableBulkDispatch turns off bulk dispatch.

static void	enableUtc () noexcept
	Send UTC time to the server. By default local time is sent.

static void	disableUtc () noexcept
	Send Local time to the server. By default local time is sent.

static void	setTimeOffset (int offset) noexcept
	Offset in seconds for log time. [Default: 0].

static void	setDispatchDelay (unsigned int delay) noexcept
	Delay between dispatching log messages (in milliseconds) [Default: 1ms]. More...

static void	setBulkSize (unsigned int bulkSize)
	Sets number of log messages to be bulked together. More...

static void	enableAutoBulkParams () noexcept
	Enables automatic setting of bulk parameters depending on what's most efficient. It essentially enables bulk if server supports it and sets bulk size and dispatch delay accordingly. More...

static void	disableAutoBulkParams () noexcept
	Disables automatic setting of bulk params. More...

static void	setKeySize (std::size_t keySize)
	Size of RSA key (in bits) when connecting. More...

static void	setApplicationArgs (int argc, char **argv)

static void	setApplicationArgs (int argc, const char **argv)
	Wrapper for START_EASYLOGGINGPP. More...

static void	setKnownClient (const std::string &clientId, const std::string &privateKeyPem)
	If server knows you already you can let us know and we will use this identity. More...

static void	setServerPublicKey (const std::string &publicKeyPem)
	Sets server public key for encrypted connection. More...

static void	setInternalLoggingLevel (int level)
	Sets logging level for residue client library internal logging. More...

static void	setInternalLoggingLevel (InternalLoggingLevel level)
	Helper function to set logging level for debugging/info. More...

static bool	hasFlag (Flag flag) noexcept
	Checks for server flag and returns true if flag set otherwise not.

static void	setThreadName (const std::string &threadName) noexcept
	Sets current thread name.

static void	enableCrashHandler (const std::string &loggerId=el::base::consts::kDefaultLoggerId)
	Enables crash handler. More...

static const std::vector< std::string > &	errors () noexcept
	Useful for debugging the issue. Contains last 10 errors from server (i.e, error_text in response) Last error is the latest, second last is second latest, ...

static void	loadConfigurationFromJson (const std::string &json)
	Loads configuration from JSON. More...

static void	saveConnection (const std::string &outputFile)
	Saves connection parameter to the file. More...

static std::string	connection ()

static void	loadConnectionFromJson (const std::string &connectionJson)
	Loads configuration from JSON. More...

Static Public Attributes
static const std::size_t	DEFAULT_KEY_SIZE
	Default key size for RSA. More...

static const int	DEFAULT_PORT
	Default port 8777 of residue.

static const std::string	LOCALHOST
	127.0.0.1

static const unsigned int	TOUCH_THRESHOLD
	Threshold (seconds) to check against client age and whether we should send touch request or not.

static volatile int	s_internalLoggingLevel
	See setInternalLoggingLevel(InternalLoggingLevel)

Friends
class	ResidueDispatcher

Related Functions
(Note that these are not member functions.)
static void	loadConfiguration (const std::string &jsonFilename)
	Loads all the configurations from JSON file. More...

static void	loadConnection (const std::string &connectionFile)
	Loads connection from file instead of re-pulling it from server. More...

Detailed Description

The Residue class provides helper methods to connect and interact to residue server seamlessly.

Member Function Documentation

◆ connect() [1/4]

static void Residue::connect	(	const std::string &	host,
		int	port
	)

inlinestatic

Connect to residue on specified host and port.

Parameters

host	Host where residue server is running
port	Residue server port (Try Residue::DEFAULT_PORT)

Exceptions

exception When connection fails

◆ connect() [2/4]

static void Residue::connect ( int port )

inlinestatic

Connect to residue on localhost.

See also: connect(const std::string&, int)

Exceptions

exception When connection fails

◆ connect() [3/4]

static void Residue::connect ( const std::string & host )

inlinestatic

Connect to residue using default port.

See also: connect(const std::string&, int)

Exceptions

exception When connection fails

◆ connect() [4/4]

static void Residue::connect ( )

inlinestatic

Connect to residue on localhost using default port. This is more useful when you have client ID so you won't have varying client IDs.

See also: connect(const std::string&, int); setParams(const std::string&, const std::string&)

Exceptions

exception When connection fails

◆ connected()

static bool Residue::connected ( )

inlinestaticnoexcept

Check connection to the server.

Returns: Whether connected to the server or not

◆ connecting()

static bool Residue::connecting ( )

inlinestaticnoexcept

Check connection to the server.

Returns: Whether connection to the server is in progress

◆ disableAutoBulkParams()

static void Residue::disableAutoBulkParams ( )

inlinestaticnoexcept

Disables automatic setting of bulk params.

Note: It does not reset parameters back to what they were, meaning this only implies it does not change any parameters when reconnected

See also: enableAutoBulkParams()

◆ disconnect()

static void Residue::disconnect ( )

staticnoexcept

Safely disconnects from the server. This will also call wait()

You should always call this before ending your application.

◆ enableAutoBulkParams()

static void Residue::enableAutoBulkParams ( )

inlinestaticnoexcept

Enables automatic setting of bulk parameters depending on what's most efficient. It essentially enables bulk if server supports it and sets bulk size and dispatch delay accordingly.

Note

You need re-connect using

connect()

helper method

By default it is enabled

◆ enableBulkDispatch()

static void Residue::enableBulkDispatch ( )

inlinestatic

enableBulkDispatch turns on bulk dispatch.

Note: MAKE SURE SERVER SUPPORTS BULK LOG REQUESTS

Exceptions

exception if server does not allow bulk requests. (can only determine when connected)

◆ enableCrashHandler()

static void Residue::enableCrashHandler ( const std::string & loggerId = el::base::consts::kDefaultLoggerId )

inlinestatic

Enables crash handler.

Parameters

loggerId Logger ID for handling crash

◆ loadConfigurationFromJson()

static void Residue::loadConfigurationFromJson ( const std::string & json )

inlinestatic

Loads configuration from JSON.

Parameters

json	JSON Configuration

See also: loadConfiguration(const std::string&)

◆ loadConnectionFromJson()

static void Residue::loadConnectionFromJson ( const std::string & connectionJson )

static

Loads configuration from JSON.

Parameters

connectionJson JSON connection

Exceptions

ResidueException if configuration not found or socket could not be connected

See also: loadConnection(const std::string&); saveConnection(const std::string&)

◆ reconnect()

static void Residue::reconnect	(	const std::string &	host = `""`,
		int	port = `-1`
	)

inlinestatic

Reconnects residue server using new or initially provided parameters. (Disconnect then connect)

Parameters

host	If left empty, existing value (initially provided) will be used
port	If set to -1, existing value (initially provided) will be used

◆ saveConnection()

static void Residue::saveConnection ( const std::string & outputFile )

inlinestatic

Saves connection parameter to the file.

Exceptions

ResidueException if not connected or if file is not writable

◆ setApplicationArgs() [1/2]

static void Residue::setApplicationArgs	(	int	argc,
		char **	argv
	)

inlinestatic

See also: setApplicationArgs(int, const char*)

◆ setApplicationArgs() [2/2]

static void Residue::setApplicationArgs	(	int	argc,
		const char **	argv
	)

inlinestatic

Wrapper for START_EASYLOGGINGPP.

This is recommended for all the applications using Residue in order to send verbose logs to the server.

See also: https://github.com/muflihun/easyloggingpp#setting-application-arguments

◆ setBulkSize()

static void Residue::setBulkSize ( unsigned int bulkSize )

inlinestatic

Sets number of log messages to be bulked together.

Note: This depends on what server accepts. The configuration value on the server is max_items_in_bulk. Please contact your log server hosting to get this number. Failing to select correct number can fail.

Exceptions

ResidueException if connected and specified bulk size exceeds maximum allowed

◆ setDispatchDelay()

static void Residue::setDispatchDelay ( unsigned int delay )

inlinestaticnoexcept

Delay between dispatching log messages (in milliseconds) [Default: 1ms].

Setting correct delay is very important depending on your application and needs. Some applications that run for long (e.g, GUI application) may need longer delays between collecting log message and dispatching them to the server. This is very helpful for bulk requests in combination with compression enabled servers. When you collect many messages before they are dispatched to the server and you have bulk request and compression enabled, there are more changes of similar strings, meaning smaller packets.

For example, if you have dispatch delay set to 10000 (10 seconds) and you have bulk requests (size 20) and compression enabled, when you log messages (using any method, e.g, LOG(INFO)...) it is going to hold the message in local memory for 10 seconds. Let's say within 10 seconds you logged 100 times, in this situation there are high chances you will have duplicate strings (for example lots of ":" or alphabets (e.g, "a") hence the compression will be much more useful.

◆ setInternalLoggingLevel() [1/2]

static void Residue::setInternalLoggingLevel ( int level )

inlinestatic

Sets logging level for residue client library internal logging.

Parameters

level CRAZY = 0, DEBUG = 1, INFO = 2, WARNING = 3, ERROR = 4, NONE = 5 (default)

E.g, for ERROR and WARNING = use level 3 for just ERROR = use level 4

◆ setInternalLoggingLevel() [2/2]

static void Residue::setInternalLoggingLevel ( InternalLoggingLevel level )

inlinestatic

Helper function to set logging level for debugging/info.

See also: setInternalLoggingLevel(int)

◆ setKeySize()

static void Residue::setKeySize ( std::size_t keySize )

inlinestatic

Size of RSA key (in bits) when connecting.

RSA key is generated on the fly when client is unknown to the server.

You can choose to speed up connection process by understanding 3 following points and acting accordingly;

Default value is 2048-bit which takes ~150ms to generate the key, if you increase it to 4096-bit it takes ~3s to generate this key. This means connection will be 2850 ms slow but is more secure. This situation is useful for big applications that can take this long, e.g, gui application
Having pre-defined key helps speed up connection process by saving overhead of key generation with each connection.

Parameters

keySize Size of key in bits, i.e, 2048, 4096, ...

See also: setKnownClient

Exceptions

ResidueException if size is not one of 2048, 4096 or 8192

◆ setKnownClient()

static void Residue::setKnownClient	(	const std::string &	clientId,
		const std::string &	privateKeyPem
	)

inlinestatic

If server knows you already you can let us know and we will use this identity.

Note: YOU NEED TO RUN CONNECT() AFTER THIS

Parameters

clientId	what server knows you as
privateKeyPem	Contents of your RSA private key. THIS IS NOT PATH TO THE FILE RATHER IT'S CONTENTS OF THE FILE

See also: connect

Exceptions

ResidueException if you specified client ID but private key is null

◆ setServerPublicKey()

static void Residue::setServerPublicKey ( const std::string & publicKeyPem )

inlinestatic

Sets server public key for encrypted connection.

Note: The bigger the server key, the slower server will respond (but it's more secure)

Friends And Related Function Documentation

◆ loadConfiguration()

static void loadConfiguration ( const std::string & jsonFilename )

A JSON file should look similar to. Only

url

is required, rest of them are optional

{
    "url": "localhost:8777",
    "application_id": "com.muflihun.sampleapp",
    "rsa_key_size": 2048,
    "utc_time": false,
    "time_offset": -3600,
    "dispatch_delay": 1,
    "main_thread_id": "main_thread",
    "client_id": "my_client",
    "client_private_key": "client-private.pem",
    "client_key_secret": "",
    "server_public_key": "server-public.pem",
    "internal_logging_level": 2
}

Parameters

jsonFilename Path to configuration JSON file (const std::string&)

◆ loadConnection()

static void loadConnection ( const std::string & connectionFile )

You must load configurations before this

This is useful if you know server has this connection and do not want to renew your connection.

This also automatically connects the required sockets

(const std::string&)

Exceptions

ResidueException if configuration not found or socket could not be connected

Member Data Documentation

◆ DEFAULT_KEY_SIZE

const std::size_t Residue::DEFAULT_KEY_SIZE

static

Default key size for RSA.

See also: setKeySize

The documentation for this class was generated from the following file:

include/residue.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Related Functions

Detailed Description

Member Function Documentation

◆ connect() [1/4]

◆ connect() [2/4]

◆ connect() [3/4]

◆ connect() [4/4]

◆ connected()

◆ connecting()

◆ disableAutoBulkParams()

◆ disconnect()

◆ enableAutoBulkParams()

◆ enableBulkDispatch()

◆ enableCrashHandler()

◆ loadConfigurationFromJson()

◆ loadConnectionFromJson()

◆ reconnect()

◆ saveConnection()

◆ setApplicationArgs() [1/2]

◆ setApplicationArgs() [2/2]

◆ setBulkSize()

◆ setDispatchDelay()

◆ setInternalLoggingLevel() [1/2]

◆ setInternalLoggingLevel() [2/2]

◆ setKeySize()

◆ setKnownClient()

◆ setServerPublicKey()

Friends And Related Function Documentation

◆ loadConfiguration()

◆ loadConnection()

Member Data Documentation

◆ DEFAULT_KEY_SIZE