Troubleshooting – Logging

The purpose of diagnostic logging is to make more information available as the application executes. Errors and warnings logged can help pinpoint failures within the system that might not be immediately obvious to an end-user. More verbose logging can be enabled temporarily to provide a useful picture of how an application is behaving when troubleshooting a problem.

Blue Prism uses a proven and reliable library called NLog to output and record log information. A user can fine-tune the amount of information logged, either globally or in specific areas of the application. It is also possible to select from a variety of log output destinations, including the Windows Event Log and text files.

Logging levels

Log entries are categorized by level. Entries with a level of Info or above are usually recorded as standard. Lower, more detailed levels like Debug and Trace provide more verbose information but need to be enabled.

NLog defines the following levels from lowest to highest:

  • Trace – Very detailed logs, which may include high-volume information such as protocol payloads. This log level is typically only enabled during development.
  • Debug – Debugging information, less detailed than Trace, typically not enabled in production environments due to a possible impact on performance.
  • Info – Information messages, which are normally enabled in production environments.
  • Warn – Warning messages, typically for non-critical issues, which can be recovered or which are temporary failures.
  • Error – Error messages - most of the time these are exceptions.
  • Fatal – Very serious errors.

Standard logging configuration

Standard NLog XML configuration files are used to configure NLog. Two separate configuration files are used:

  • Automate.NLog.config – Used by Automate (interactive client and resource PC), AutomateC, and AppMan
  • Server.NLog.config – Used by the server (running as BPServer.exe and as a Windows Service)

When Blue Prism is installed, the default log configuration files are installed in a Blue Prism specific folder, for default installations this is: C:\ProgramData\Blue Prism Limited\Blue Prism.

The log configuration files include two main log destinations:

The default configuration directs log entries at "informational" level and above (including warnings, errors, and fatal errors) to the Windows event log. Text file logging is also configured but is only used for fatal errors by default, i.e., unhandled exceptions that resulted in an application crash. This ensures that crash information is available, even if recording the error in the Windows Event Log fails.

You should not need to amend the log configuration files yourself during normal usage of Blue Prism. Customer Services would normally provide alternative log configuration files when investigating a problem with the product.

Note that amending the logging configuration can affect the performance of the application and special care should be taken if amending within a production environment.

For technically minded customers, the following links may provide useful further information.

Windows event log

Log entries with a level of Info and above will be directed to the Windows Event Log.

The event log settings are defined within the <target name="app-eventlog" ... element. This is enabled via the following element at the end of the configuration:

<logger name="*" minlevel="Info" writeTo="app-eventlog" />

The main log is called Blue Prism. The event log sources vary according to whether the information is logged by a resource PC, the server. or interactive client.

Text log files

Log files are written to a Blue Prism specific directory. For default installations, this is: C:\ProgramData\Blue Prism Limited\Blue Prism\Logs. This location also applies to Blue Prism API log files. Control Room log files are written to C:\Program Files (x86)\Blue Prism\, the default location of Blue Prism Hub log files. Separate log files are generated based on the application that is running (interactive client, server, or resource PC), with a unique filename generated for each resource PC.

Text file logging is limited to fatal errors by default, such as, unhandled exceptions that resulted in an application crash. This ensures that crash information is available, even if recording the error in the Windows Event Log fails.

Detailed text file logging should only be enabled when more detailed debug information is required. Blue Prism Customer Support will advise on the configuration changes required.

The parameters for text file logging are defined within the <target name="app-logfile" ... element and controlled by the following element at the end of the configuration file:

<logger name="*" minlevel="Fatal" writeTo="app-logfile" />

The standard configuration includes a log archiving and rotation mechanism, which archives files when they reach 10 MB and retains a maximum of 50 archived files.

Below is an example of a line from the log file:

2019-01-14 13:07:59.2395 DEBUG BluePrism.AutomateAppCore.clsResourceConnection BP0188:8182 - Beginning update. Current state: Offline

The format of this text, which is defined in the standard configuration, contains the following elements:

  • Date and time (UTC)
  • Log level (DEBUG, INFO, WARN, ERROR, FATAL)
  • Logger name – this usually identifies the class and namespace from which the log entry originates
  • The log message
  • Error information (only available if exception information is logged) – full details will be logged on a separate line below

Enable logging

Text file logging for the entire application can be enabled by editing the configuration and specifying your chosen level:

<logger name="*" minlevel="Debug" writeTo="app-logfile" />

Fine-tuning text file logging

It is also possible to enable debug level text file logging to one or more particular areas of the application by adding additional logger elements, for example:

<logger name="*" minlevel="Info" writeTo="app-logfile" />

<logger name="BluePrism.AutomateAppCore.*" minlevel="Debug" writeTo="app-logfile" />

<logger name="BluePrism.AutomateUI.*" minlevel="Debug" writeTo="app-logfile" />

Wildcards can be used to specify multiple loggers below a namespace level.

Text file logging can also be disabled in certain areas of the application by using an empty writeTo attribute, for example:

<logger name="BluePrism.AutomateAppCore.*" minlevel="Debug" maxLevel="Fatal" writeTo="" final="true" />

<logger name="BluePrism.AutomateUI.*" minlevel="Debug" maxLevel="Fatal" writeTo="" final="true" />

<logger name="*" minlevel="Debug" writeTo="app-logfile" />

Configuration troubleshooting

NLog is designed to fail silently, rather than bring your application down due to errors encountered while logging. This can make it difficult to see why your logging configuration isn't working.

Potential problems include:

  • Elevated permissions are required to create Windows Event Log logs and sources
  • Text file logging requires permissions on the target directory

There are some useful diagnostic options available in the standard XML configuration:

  • Find the throwExceptions="false" attribute in standard configuration and amend the value to "true" to enable any logging exceptions that might reveal an error with your configuration.
  • You can also enable NLog's internal logging. This is switched off by default in the standard configuration but can be enabled by editing the following attributes: internalLogLevel="Off" internalLogFile="C:\temp\nlog-internal.log".