Skip to main content
English (US) Nederlands

Logging server activity in Studio Server 10.14 or higher – Configuration

Updated

When technical issues occur with Studio Server or any of the client applications that are logged in to the server, logging can be enabled for troubleshooting purposes. The created log files store all SQL queries and Web service details.

This article describes how to configure the system.

Info: Performing the steps described in this article requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or WoodWing Support team. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

Notes:

The following steps and areas to configure are described:

  1. Enabling and disabling logging
  2. Assigning read and write access to log folders
  3. Setting the detail level
  4. Setting the log level for users
  5. Centralized logging
  6. Defining the log file format
  7. Profiling PHP code
  8. Logging SQL statements
  9. Logging RabbitMQ services
  10. Logging internal Web services
  11. Logging the full stack of calling functions

Info: Use the filter to only show the information for one step or area:

1. Enabling and disabling logging

IMPORTANT: With low-level logging turned on, the file size of the log files will keep growing, thereby consuming disk space and reducing performance.

Enabling logging is done by defining the directory to output log files that are output to the local disk.

Note: This step is mandatory, including when centralized logging is used.

  • Option: OUTPUTDIRECTORY
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value: Any path to a mounted disk or shared folder that the web server user (such as an Apache user) can write to.

Note: The path needs to end with a forward slash '/'. Example: ‘c:/entlog/output/’.

  • Default value: empty (logging is not enabled)
  • Example:

define ('OUTPUTDIRECTORY', '');

Disabling logging

Once logging is enabled and configured, it can be temporarily disabled by emptying the value of the OUTPUTDIRECTORY setting.

In other words: as long as an output directory is configured and a log level other than NONE is set for the server or individual users, logging takes place.

2. Assigning read and write access to log folders

Make sure that read and write access is set to the local log folder for the following users:

  • macOS: “www”
  • Windows: “IUSR_<servername>”
  • Linux: “nobody”

3. Setting the detail level

The level of detail that is logged on server level is configured through the DEBUGLEVELS option.

By default, this is done for all client applications on all IP-addresses. When problematic work stations need to be identified, logging can be specified for only their IP-address that these applications are working on. The log files are then bundled in a dedicated folder for that IP-address.

Note: For an explanation of the log level values, see Logging server activity in Studio Server 10.14 or higher – Concept.)

  • Option: DEBUGLEVELS
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible values:
  • NONE
  • ERROR
  • WARN
  • DEPRECATED
  • INFO
  • DEBUG

Info: For production environments it is advisable to configure the DEPRECATED or WARN log level. For development and testing environments it is advisable to configure the DEBUG log level.

  • Default value: NONE
  • Example:
define ('DEBUGLEVELS', serialize( array(
	// CLIENT IP => DEBUGLEVEL
	'default' => 'INFO', // 'default' entry is mandatory
	'127.0.0.1' => 'DEBUG',
)));

Note: There must be one item named 'default' which is used for all clients that are not explicitly configured.

By default, some high-level information is logged for all clients. This is indicated by the 'default' key, which is mandatory:

define ('DEBUGLEVELS', serialize( array(
	'default' => 'INFO', 
)));

When you want to monitor a client application in great detail (while not being too interested in other clients), add the IP address that the client is using:

define ('DEBUGLEVELS', serialize( array(
	'default' => 'INFO', 
	'123.123.123.123' => 'DEBUG',
)));

In this example, some high-level INFO logging is written for all clients, while for the client applications running on IP-address 123.123.123.123 the most detailed DEBUG logging is written. It is assumed here that the acting users that are using these client applications all have Log Level NONE set (see 'Setting the log level for users' below'.)

4. Setting the log level for users

When a user experiences technical issues with the system, log files can be generated for that user only.

This is done by temporarily setting the level of detail that should be logged for that user in the Log Level field on the Maintenance page for that user:

  • ERROR
  • WARN
  • DEPRECATED
  • INFO
  • DEBUG

When the issue is resolved, the log level for that user can be set to NONE again so that no logging is performed for that user.

Note: When an error (especially a fatal error) happens at the very beginning of a web service execution where a session is not yet initialized, the acting user is still unknown. Because of this, the log level of the user is also not yet known. The system therefore falls back to the log level defined in the DEBUGLEVELS option.

In very rare occasions, this can result in no log files being generated.

Assume for example that the log level for a user is set to DEBUG, while the log level in the DEBUGLEVELS option is set to NONE. When the above mentioned scenario occurs and the acting user cannot yet be resolved, the system falls back to NONE and no logs are generated.

Although this situation is rare, it may be wise to temporarily set the DEBUGLEVELS option to DEBUG when the system is not working as expected and no log files are generated.

5. Centralized logging

When multiple instances of Studio Server are used, centralized logging can be enabled in order to output or stream errors, warnings and information about the use of deprecated features to a central location. This makes it easier and more efficient to detect problems from multiple servers from just one location.

To enable this, do the following:

Step 1. Enable centralized logging by setting the following option to true:

  • Option: LOG_CENTRALIZED
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value:
  • true. Centralized logging is enabled.
  • false. Centralized logging is disabled.
  • Default value: false
  • Example:

define ('LOG_CENTRALIZED', true);

Step 2. Set the DEBUGLEVEL option to DEPRECATED, WARN or ERROR (see 'Setting the detail level' earlier in this article).

Step 3. Define the location to output to by configuring the PHP error_log option.

Note: For each log message, Studio Server calls the PHP error_log() function. When calling this function, the default option is used for the $message_type parameter. This means that log messages are sent to PHP's system logger, using the operating system's system logging mechanism or a file, depending on what the error_log configuration directive is set to. This makes it possible for system integrators to stream the log messages to their centralized logging system.

Example: A Docker container can be set up in such way that Apache, PHP and Studio Server stream their log messages to the default output which then gets streamed to the standard Docker logs.

6. Defining the log file format

To define the format in which log files are saved, configure the following option:

  • Option: LOGFILE_FORMAT
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value:
  • html
  • plain
  • Default value: html
  • Example:

define ('LOGFILE_FORMAT', 'html');

Notes: 

  • The log file always contains UTF-8 characters.
  • The HTML format is better readable in a Web browser.
  • The plain-text format can be easily searched by using command line tools such as GREP.
  • Files that are output to centralized logging are always in JSON format.

7. Profiling PHP code

When PHP code needs to be profiled (for analyzing its performance and locating bottlenecks), set a profiling level ranging from 0 (zero, no profiling) to 5 (most detailed profiling) in the following option:

  • Option: PROFILELEVEL
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value: 0 to 5, (0: no profiling, 5: most detailed profiling).
  • Default value: 1
  • Example:

define ('PROFILELEVEL', 1);

8. Logging SQL statements

When all SQL statements need to be logged to the main log file, configure the following option:

  • Option: LOGSQL
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value:
  • null. (Default) Logs SQL statements when the applied log level is set to DEBUG.
  • true. Logs SQL statements when the applied log level is set to INFO or DEBUG.
  • false. No SQL statements are logged.
  • Default value: false
  • Example:

define ('LOGSQL', false);

Note: Setting the option to true or null is especially useful in combination with setting the log level at user level (see earlier in this article). This way, the SQL logging setting can be set once and then controlled by setting the INFO or DEBUG level for a particular user on the User Maintenance page.

9. Logging RabbitMQ services

When RabbitMQ requests that are fired by Studio Server to RabbitMQ Server as well as the corresponding responses need to be logged to the main log file, configure the following option:

  • Option: LOG_RABBITMQ_SERVICES
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value:
  • null. Logs requests and responses when the applied log level is set to DEBUG.
  • true. Logs requests and responses when the applied log level is set to INFO or DEBUG.
  • false. (Default) No requests and responses are logged.
  • Default value: false
  • Example:

define ('LOG_RABBITMQ_SERVICES', false);

10. Logging internal Web services

When internal Web services need to be logged (a PHP dump of request and response data), configure the following option:

  • Option: LOG_INTERNAL_SERVICES
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value:
  • null. Logs requests and responses when the applied log level is set to DEBUG.
  • true. Logs requests and responses when the applied log level is set to INFO or DEBUG.
  • false. (Default) No requests and responses are logged.
  • Default value: false
  • Example:

define ('LOG_INTERNAL_SERVICES', false);

11. Logging the full stack of calling functions

Info: This feature requires Studio Server 10.20.0, or any higher version of Studio Server.

When an alert is logged, it can be defined if the whole stack of calling functions should be included.

Including such log stacks can be of great help to diagnose a problem.

Note: An alert is a log message of level Error (ERROR), Warning (WARN), or Deprecated (DEPRECATED).

The following functionality is available:

  • Only include stacks in the log file when the applied log level is set to DEBUG.
  • Include stacks in the log file on alerts, regardless of the applied log level.
  • Never include stacks in the log file.

The default setting is to include stacks in the log file when the applied log level is set to DEBUG.

However, because changing the applied log level to DEBUG has a performance impact, this is typically not done in a production environment. It is therefore also possible to always include stacks in the log file, regardless of the applied log level.

This may help to diagnose a problem in a production environment.

Configure the following option:

  • Option: LOG_STACK_ON_ALERT
  • File: configserver.php file (recommended: config_overrule.php file)
  • Possible value:
  • null. Default value. Stacks are included in the log file on alerts when the applied log level is set to DEBUG.
  • true. Stacks are included in the log file on alerts, regardless of the applied log level.
  • false. Stacks are never included in the log file.
  • Default value: null
  • Example:

define( 'LOG_STACK_ON_ALERT', null );

Related articles

Comments

0 comments

Please sign in to leave a comment.