Search

Version: 4.3.0 +

Applicable to: Futurama Editor/Futurama Website/Futurama Webservice/Futurama Export/Futurama Vision

 

Description

Futurama and Futurama Vision offer an wide range of possibilities to log errors, warnings, information messages and developers messages. The logging of information is applicable for all the instances of Futurama (Futurama Editor, Futurama Website, Futurama Webservice, Futurama Export and Futurama Vision). When troubleshooting make sure that the logging in the configuration file of the relevant Futurama instance is enabled. In most of the cases this gives enough information to troubleshoot.

It is possible to log messages to:

  • text files
  • Windows Event Log
  • trace (if possible)
  • SQL database

At this page explanation is given about the next subjects:

  • how to configure the logging of messages
  • compatibility with previous versions of Futurama (versions below 4.1.0)
  • technical background information about writing messages to the Windows Event Log

Configuration

Settings

Within the configuration element the next code has to be included:

<configSections>
	<sectionGroup name="futuramaSettings">
		<section name="log" type="ActuIT.Futurama.Library.LogSection, ActuIT.Futurama.Library, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
	</sectionGroup>
</configSections>

Next to this code, also within the configuration element the next code has to be included:

<futuramaSettings>
	<log>
		<trace enabled="{true/false}" format="{text/xml}">
			<errors level="{integer}" stacktrace="{true/false}" value="{true/false}"/>
			<warnings value="{true/false}"/>
			<messages value="{true/false}"/>
			<debug category="{categorySelector}" value="{true/false}"/>
		</trace>
		<eventlog enabled="false" format="xml">
			<errors level="{integer}" stacktrace="{true/false}" value="{true/false}"/>
			<warnings value="{true/false}"/>
			<messages value="{true/false}"/>
			<debug category="{categorySelector}" value="{true/false}"/>
		</eventlog>
		<files>
			<file enabled="{true/false}" format="{text/xml}" path="{path}">
				<errors level="{integer}" stacktrace="{true/false}" value="{true/false}"/>
				<warnings value="{true/false}"/>
				<messages value="{true/false}"/>
				<debug category="{categorySelector}" value="{true/false}"/>
			</file>
		</files>
		<sql connectionstring="{name of connectionstring to use}" enabled="{true/false}" instanceKey="{name of log instance}">
			<errors level="{integer}" stacktrace="{true/false}" value="{true/false}"/>
			<warnings value="{true/false}"/>
			<messages value="{true/false}"/>
			<debug category="{categorySelector}" value="{true/false}"/>
		</sql>
	</log>
</futuramaSettings>

The futuramaSettings element is the general part for more configuration settings. Within this element the log element is set. Note: for the configuration files belonging to a Futurama Vision release it is necessary to use visionSettings instead of futuramaSettings. So the name attribute of the sectionGroup element has to be visionSettings instead of futuramaSettings. Next to that the log section must be included within the visionSettings element instead of the futuramaSettings element.

It is not required to include all the elements (trace, eventlog, files, sql, oracle). You can either remove the elements you don't want to use for logging or set the enabled attribute to 'false'.

Explanation

Within the log element some elements and attributes of these elements can be defined. The elements differ in the location where the information is logged. For each of the locations it is possible to configure what type of information has to be logged. See the paragraph 'Type of information' for this configuration. Below the possible values of the locations:

<trace enabled="{true/false}" format="{xml/text}"></trace>

When using Futurama in Website mode or Batch mode (using Futurama Export) it is possible to use the trace to log information. In Batch mode the log information will be logged to the console window. Notes:

  • default value of enabled is 'false';
  • this element is optional. If this element is not included the default value is used;
  • this attribute is only used in Website and Batch mode;
  • enabled='true' means that information is logged to the trace, when enabled='false' information is not logged to the trace. Using logging in Website mode implicates that also in the configuration file within the system.web section trace is enabled (<trace enabled="true">);
  • format (optional, default value 'text'): Indicates in which format the messages will be logged ('xml' or 'text');
<eventlog enabled="{true/false}" format="{xml/text}"></eventlog>

Indicates which information has to be logged to the eventlog. Notes:

  • the default value of enabled is 'false';
  • this element is optional. If this element is not included the default value is used;
  • enabled='true' means that information is logged to the eventlog, when enabled='false' information is not logged to the eventlog. This will only work out if Futurama has the permission to write information to the eventlog. If you are logged in as Administrator this will work automatically, in other cases the rights should be assigned manually . See the last chapter for more information.
  • format (optional, default value 'text'): Indicates in which format the messages will be logged ('xml' or 'text').
<files></files>

It is possible to log information to a file. The location and the name of the file can be chose. Notes:

  • the 'files' element is optional. If this element is not included, then no information is logged to files;
  • it is possible to log information to one or more (different) files. For each of the files an element file has to be defined. Within this file element the specifications of the location and the name of the file can be configured. See below for the way to configure this:
<file enabled="{true/false}" format="{xml/text}" path="{path}"></file>

Indicates what should be logged to a file. Notes:

  • the default value of enabled is 'false';
  • enabled='true' means it will log to the file specified, when enabled='false' not. Note: make sure that Futurama has the permission to write information to the file location that is chosen;
  • path: defines the path (including the file name) where the logging information is logged. If the directory doesn't exist, Futurama will make automatically a new directory based on the given path. In case if the path has not been defined, it will be written in the installation-directory/log.
  • it is possible to save dynamic information in the file name (Note: the braces are required, and the name is case sensitive):
    • {PROCESSID}: for the ID of the process
    • {PROCESSNAME}: for the name of the process (for example Futurama.Website);
    • {JOBID}: for the ID of the job (only for Futurama Export);
    • {SERVERNAME}: for the name of the server;
    • {HOST}: for the HOST name of the server, as it is used in the first request (available starting with Futurama 16.11); If an item is logged before the first request has been made the hostname is not yet available. Then the Application pool name is used instead.
    • {STARTTIME:ddMMyyyy_HHmm}: for the starttime and format (the date format can be chosen. For example ddMMyyyy for only the date, for example ddMMyyyy_HHmm if also the time in minutes is relevant, or even more detailed for example ddMMyyyy_HHmm_ss_ms in order to have the time in milliseconds in the filename)
    • Note: Using dynamic filenames (using either PROCESSID, JOBID or STARTTIME) is highly recommended, as it auto-creates a new file on each process restart. Existing logs are never overwritten so without periodic new file names, log files can only grow, to unlimited size.
  • it is required to fill in the entire path (including the file name). The dynamical information mentioned above can be used as well in the name of the directory as in the file names;
  • format (optional, default value 'text'): Indicates in which format the messages will be logged ('xml' or 'text').

Example of the configuration of a logging file to the directory c:\log with the starttime of the process in the name of the log file:

<file enabled="true" format="xml" path="C:\Log\{STARTTIME:ddMMyyyy_HHmm}_log_futurama.xml"></file>
<sql connectionstring="{name of a configured connection string}" enabled="{true/false}" instanceKey="{name of log instance}"></sql>

It’s possible to log information to an SQL Server database (Futurama 19.04+). Any database-logging method before this version of Futurama is no longer supported.

Configuration properties:

  • the default value of enabled is 'false'. This element is optional. If this element is not included the default value is used;
  • enabled='true' means information will be logged to a database (SQL), when enable='false' means no information is logged to a database.
  • connectionstring: This field contains the name of a connectionstring within the same config file, where the required logging database  is specified. For more information about embedding a connectionstring in a configuration file, view this page.
  • instanceKey: Just like logging to a file, dynamic information can be included in the instancekey field, which will be replaced during application startup. However in contradiction to the file logging method, we would advise to keep this instancekey as simple as possible (for instance, the application name), because it is easier to filter the log-entries in the database according to timestamp and entry-type.

An example for a connectionstring to a logging database with ‘logdb’ to be used as name is as follows:

<connectionStrings>
	<add connectionString="Server={MySQLServerHostname};Database={My logging database};Integrated Security=true;" name="logdb">
	</add>
</connectionStrings>

For Futurama version 19.04 we re-envisioned the database logging functionality, and supply Futurama Vision and Futurama Web with a method of viewing this log-information from the Browser. Please view this support document for more information.

Type of information

It is possible to choose what type of information has to be logged (errors, warnings, messages, debug). Within each of the elements described in the previous paragraph the relevant type(s) can be configured. Below the explanation of this configuration.

<errors level="{integer>=0}" stacktrace="{true/false}" value="{true/false}"></errors>

With this element it is possible to configure whether errors has to be logged. Also the type of errors to be logged can be configured. Notes:

  • the default value of the attribute 'value' is 'false';
  • this element is optional. If this element is not included the default value is used;
  • value='true' means that errors will be logged, value='false' not;
  • level (optional, default value 1): indicates the degree of innerexception logging (when an error occurs it is possible that other errors causes this error. Subsequently these errors can be triggered by other errors, etc. This creates a tree of errors from top to bottom where the bottom error is the trigger for all the errors). It is possible to log how deep in the tree of errors information has to be logged. 0 means infinity (this means until there are no more innerexceptions) 1 means only on root level (thus no innerexceptions) etc.
  • stacktrace (optional, default value 'false'): indicates if the stacktrace (information regarding the procedure and the line of the source code where the error occurs) will be logged;
<warnings value="{true/false}"></warnings>

Indicates if warnings have to be logged:

  • the default value is 'false';
  • this element is optional. If this element is not included the default value is used;
  • value='true' means warnings will be logged, value='false' not;
<messages value="{true/false}"></messages>

Indicates if information messages have to be logged:

  • the default value is 'false';
  • this element is optional. If this element is not included the default value is used;
  • value='true' means it will log information messages, value='false' not;
<debug value="{true/false}"></debug>

In the Futurama Editor all the objects do have a property 'DebugLogMode'. If this property is set, it is possible to log information about this object. It is for example possible to see the value and the properties of an object. Logging information at object level can be used by the Futurama developer when troubleshooting. This so-called debug information can be logged. Notes:

  • the default value is 'false';
  • this element is optional. If this element is not included the default value is used;
  • value='true' means debug information will be logged, value='false' not;

Within the Debug element you can specify a Category (starting from version 2016.11 ). If you do not supply a Category all Debug messages will be logged. You can specify a category via a comma separated list of the Categories you want.

The following Categories are allowed:

  • Sessions: logs messages related to the start and finish of sessions in Futurama Web.
  • FormulaExecution: logs messages related to the execution of formulas.
  • WebReference: logs messages related to the execution of WebReferences.
  • PageLoad: logs messages related to loading webpages.
  • CSRF: logs messages related to the Cross Site Request Forgery token generation and validation. (Futurama 2016.12+)
  • WebService: logs messages related to the request and response of a Futurama WebService. (Futurama 2017.09+)
  • * : log all debug messages.

For now these are all the categories. In the future more categories will be added.

You can use these Categories to specify a {categorySelector} string: a comma separated list of the categories you want. You can use a “!” to specify the exclusion of a Category. For example:

  • Category=”” : log all debug messages
  • Category=”PageLoad,Sessions” : log only PageLoad and Sessions debug messages
  • Category=”*,!PageLoad” : log all debug messages except messages with the PageLoad Category

Show error notifier in Web application

It is also possible to show an errorstatus notification-icon in the Futurama Web application. The configuration of this notifier can be found on the debug configuration page.

EventLog permissions

To make sure that Futurama can log information in the Windows EventLog, it is necessary to set the right permissions. In this paragraph you can find information how to configure these permissions. When ,then Futurama will try to log information to the eventlog. The application that is used to log this information depends on the Futurama instance that is used (Futurama Website, Futurama Editor, Futurama Webservice, Futurama Export, Futurama Vision). These applications must have permission to write information to the Eventlog. Distinction can be made into two types of permissions:

  1. the permission to create an application (register) in the eventlog
  2. the permission to write messages to the eventlog

Especially the first point can cause some problems. All applications which have access to the eventlog are summed up in the registry (to be opened with 'REGEDIT.EXE') under the key 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\'. To provide Futurama in Website mode access to the eventlog is it necessary that the key 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Futurama.Website' exists. Usually, in the case that in the configuration file logging to the eventlog is set, this key is automatically created at the moment that the first message is written. This is only possible in the situation that the account wherein Futurama is running (in IIS) does have the permission of a LocalAdmin. Creating this key is an action that has to be executed once (initial). This is separate from the actual logging of messages. If the creating of this key gives any problems, there are two ways to solve this problem:

  1. let Futurama run once within an account with LocalAdmin permissions. This will create the desired key. After this, you can set the configuration of the account within IIS back to its old values. This solution is recommended.
  2. for advanced users: add the key manually in the registry editor

To manually add the key follow the next steps:

  1. start REGEDIT.EXE
  2. go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application
  3. create Futurama.WebSite
  4. in REGEDIT, select the new key and go (with the right mouse button) to Security and select Permissions
  5. add the ASP.NET user and give it read and write permissions.

 

Permissions for Futurama Webservice and Vision

The same can be done for other Futurama product, but instead of the registerkey “Futurama.Website”, the following values should be used:

  • Futurama.Vision
  • Futurama.Webservice
  • Futurama.Editor
  • Futurama.Batch
  • Futurama.Server

Logging webservices messages

It is possible to log every message that is sent to a webservice or is received by a webservice. To log these messages within the 'configuration' section of the configuration file the next code has to be included:

<system.diagnostics>
	<sources>
		<source name="System.ServiceModel"
                    switchValue="Error, Critical"
                    propagateActivity="true">
			<listeners>
				<add name="traceListener"
                   type="System.Diagnostics.XmlWriterTraceListener"
                   initializeData= "c:\test\log\Traces.svclog" />
			</listeners>
		</source>
		<source name="System.ServiceModel.MessageLogging">
			<listeners>
				<add name="messages"
                 type="System.Diagnostics.XmlWriterTraceListener"
                 initializeData="c:\test\log\messages.svclog" />
			</listeners>
		</source>
	</sources>
	<trace autoflush="true" indentsize="3" />
</system.diagnostics>
<system.serviceModel>
	<diagnostics>
		<messageLogging
         logEntireMessage="true"
         logMalformedMessages="true"
         logMessagesAtServiceLevel="false"
         logMessagesAtTransportLevel="true"
         maxMessagesToLog="3000"
         maxSizeOfMessageToLog="20000"/>
	</diagnostics>
</system.serviceModel>

Where c:\test\log is the location where the log files with information about the webservice messages is saved. In the code above the errors are logged to a file 'Traces.svclog' and the messages are logged to a file 'Messages.svclog'. These .svclog files can be read with a Service Trace Viewer.

Related Topics

- Cache: Settings regarding the caching of Futurama documents

- Debug: Settings to debug while developing with Futurama

- Format: Format settings of Futurama

- Identity provider: Settings how to use an external identity provider for determining the access to a website

- Mail: Definition of the mailserver that is used to send e-mails with Futurama Vision

- Mapping: Settings for default locations of Futurama files

- Monitor: Settings for getting session information

- Rendering: Settings to allow Futurama to generate customized HTML

- Security: Additional possible security settings when using Futurama Website

- Server: Settings when using Futurama Export either in server or in batch mode

- Vision: Configuration of the connection between Futurama and Futurama Vision

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2019-06-11