Using the Convoworks log files

Sometimes things are not going well, especially when propagating model changes to target platform/s. There are some error messages you can see in the GUI, but in some cases they will not tell you enough. We’ll certainly improve error reporting in the future, but in the meantime you can enable log files and check in details what is going on.

Enabling the log files

By default, log is disabled in Convoworks WP. There are several constants you can define in your wp-config.php to enable logging. As we actually have two separate APIs, public and admin, you have the ability to configure them separately (optional).

Here are available constants.

• CONVO_LOG_PATH – default null – path to the log files folder.
• CONVO_LOG_LEVEL – default 'info' – log level to apply. Check for available levels at PSR-3: Logger Interface
• CONVO_LOG_FILENAME – default 'debug.log' – actual filename for the log file

We strongly recommend to place the log folder below the webroot. Log files should not be accessible by the browsers!

Each constant can be appended with _PUBLIC or _ADMIN to set the desired api specific settings. Otherwise, it fails to the non suffixed variant.

Here are few examples

// Recommended - separate, bellow webroot, with date in filename - case when your web is in the '/var/www/mysite.com/www'
define( 'CONVO_LOG_PATH', '/var/www/mysite.com/log');
define( 'CONVO_LOG_LEVEL_ADMIN', 'info');
define( 'CONVO_LOG_LEVEL_PUBLIC', 'error');
define( 'CONVO_LOG_FILENAME_PUBLIC', 'convo-public-'.date('Y-m-d').'.log');
define( 'CONVO_LOG_FILENAME_ADMIN', 'convo-admin-'.date('Y-m-d').'.log');

// All to WP default log
define( 'CONVO_LOG_PATH', __DIR__ . '/wp-content');
define( 'CONVO_LOG_LEVEL', 'info');
define( 'CONVO_LOG_FILENAME', 'debug.log');

Recommended log levels

Log level debug will give you most detailed information, but it is mostly cluttered and you should probably use it rarely. As default, use info level which will provide you with narrowed, but more informative data.

If you are going to use it on production, use the error level. Also make sure that you establish some cleanup procedure or otherwise you might encounter no disk space issue.

Also have in mind, that if you have traffic on your services, the public log will tend to be much larger than admin log.

Reading the log files

You can use less, tail or some other command line command to read your log files. Except search they offer a nice ability to hook up to the end of file (shift+F in less).

Besides other things. each request has this information logged (info log level)

• Request info – at the very beginning of the request. http method, IP address, endpoint called, user agent
• Time, in human readable form and microtime appendix – allows you to easily spot if something takes too much time to execute
• Request hash – next to time – unique hash that each request has. Useful when several requests are performed at the same time and their log lines are interlaced.
• Caller info – line which called the log in first place
• Returned http response code and duration as the last log line

Here are few basic less commands:

• shift+f – hook to the last line – ctrl+c for existing mode
• ? – search backward, / – search forward
• n – repeat previous search, shift+n Repeat previous search in reverse direction

Convoworks Prototype note

Unlike the WordPress plugin, Convoworks Prototype comes with log enabled by default (at info level). Here we use a bit simpler approach, there are only two constants (no log filename adjustment) and the both APIs are logged into the same log file.

// default log settings
define( 'CONVO_LOG_PATH', '../../log');
define( 'CONVO_LOG_LEVEL', 'info');