Concerns: Web, Webservice, Batch, Vision
Edition: Futurama HTML / Futurama Export
Module: Futurama WebSite / Futurama Server
User: User Management Site
- Futurama Vision installation
- Futurama Server
Introduction to database logging, and usage of the LogViewer. To be used after executing a Futurama Server job (Futurama 16.12+), or to be used to debug Futurama Website (Futurama 17.01+). From Futurama 19.04 the Logviewer can be used for any Futurama application by writing to the database, and opening the logviewer from Vision.
All Futurama Editions can generate logfiles or write to logdatabases (Futurama 19.04+) during their execution, which can help with debugging problems that might occur during their lifetime. These logfiles can be analyzed with the LogViewer. First of all make sure that the logging section is enabled in the configuration file of the Futurama module.
During development of a Futurama Website application it is possible to get an instant message when during the browsing of your application an error occurs. This can help to detect possible errors in an early stadium (during development). To view these log, you must first enable the Error-status Notifier in the configuration file. As soon as this is done, an icon will appear in the top-right part of the browser. When an error occurs this will also be shown. Whenever this icon is clicked, a list of generated logfiles is shown, and the user can click on any of the logfiles to open the LogViewer for this particular file.
To debug Futurama Server jobs, the following steps must be followed:
After executing a Futurama Server job in the Management Site at the menu ‘Server/View status’ an overview is given of the jobs completed. For each of these jobs a clickable link to the LogViewer is given. For every logfile created, one link is available. After clicking this link the LogViewer will be opened with a user friendly display of the content of the logfile.
Logging to SQL Server (Futurama 19.04+)
Instead of logging information to logfiles, it is also possible to store this information in a Microsoft SQL Server database. One of the advantages is that multiple applications and processes can write to the same database (using different log-instance names), and a remote Futurama Vision installation can view the information for all these applications simultaneously, or filtered.
Create the logging database
In order to use this feature, a database must exist containing the appropriate logging schema and tables. In order to create these, an SQL script is provided in the Futurama distribution (“SupportFiles\CreateLoggingSchema.sql”). By executing this script in a new or existing database, a new “Logging” schema is created, containing some tables. This database can be self contained, or an existing Vision database can be used, because the new tables are part of a new database-schema called “logging”.
In order for the Futurama application to have access to this database, the credentials must be provided in the connectionstring. If integrated security is used, then the user that runs the Futurama Application (for instance, the applicationpool username) must have access to the created Logging Schema.
With the database in place, you can now configure your Futurama application (Web, Webservice, Batch or Vision) to write to this database. This is done by changing the configuration file for this application according to the instructions in this support document. An important aspect of this configuration is the inclusion of a connectionstring to the logging database within the connectionstrings element.
Viewing a Logging database using the Logviewer (Futurama 19.04+)
There are two ways the Logviewer can be accessed to view a configured logging database:
- From the Vision “Management-Logviewer” navigation menu. This is the preferred method when multiple applications writing to a single database should be monitored. To enable the Logviewer it is necessary to configure a connection to the relevant database in the configuration file of the Vision Management Site. This has to be done in a similar way as in the configuration file of the Futurama application mentioned above i.e. a connectionstring has to be defined as well as the <sql> element in de log-section. Note that the instanceKey has to be set differently than the one in the application configuration. See the instructions in this support document for more information.
- By using the DebugNotifier from a Futurama Web application. This is the logical method whenever a developer is debugging a Futurama Web application, and quickly wants to view any possible errors.
The LogViewer shows a single logfile by displaying a list of log entries that has been found in this file. Some information about the file is shown on top of the screen, such as the file size and the file name.If the logviewer is used to view a logging database, the shown information contains the current Instance-key filter, and the number of entries found for this instance.
In order to enable the logviewer, all that’s needed is a sql entry in the logging configuration, with a corresponding connectionstring to the desired database. For information about configuring database logging, view this page.
Should the number of log entries too large to fit in the screen, then it will be divided into multiple pages that can be switched by pressing the next- & previous page buttons. A slider is also present to move the current page to a certain percentage of the log-file. This percentage of the current page position within the file is shown in the slider tooltip.
When a row is selected in the list of entries,navigation through the list can be done using the keyboard. The Up- and Down-arrows move through the rows, while the Page-Up and Page-Down buttons move through the pages.
Filtering the list
The list of log-entries can be filtered for entry-type (for instance, info/debug/warning/error) by setting the checkboxes in the top of the screen. First make a selection of the types that must be displayed, second click the button next to make the selection.
Filtering by logging instance (Futurama 19.04+ with database logging)
Whenever the logviewer is used to view a database, another filtering field is present: Log-instance. This allows the logviewer to differentiate the log-entries from various applications writing to the same database using different instance-keys.
Searching for text
You can search the logfile for any kind of text by inputting it in the search field on the left side of the screen. By pressing the search-button next to the text-field the system will scan through the logfile until it has found a log-entry containing that text. Consecutive button presses should give the next results.
Viewing a log entry
A log entry can contain some simple messages, but some messages are a lot more involved. For instance, an error message can contain a huge amount of information about its source, and the path it took before it was stored in the log-file. For this reason, the log-entry is processed and provided to the user in three different levels of abstraction:
- Simple: This is the simplest form of log-entry abstraction, that hopefully shows the easiest understood form of error message.
- Advanced: This expands the simple error message with some stack-trace information, showing the path that the error has traversed.
- Raw data: This shows the raw data that would be shown for this log-entry if it was displayed in a simple text editor.
The advanced screen can only be used for Error messages. For log messages of another type this screen gives no additional information.
- The log-file viewer can only cope with the Futurama XML log-file format. Should the log-file be written in the text-format, or contain corrupted data, then every unreadable text line shall be shown as an “unknown” entry. These lines can still be viewed by switching to the “Raw data” tab screen, which will show the original data in the file-line.
- In order to view the log-files , the Futurama Vision installation needs to be able to access the log-files that are generated by the Futurama Batch installation. That means that the path in the Batch configuration must be accessible, and that Vision application pool has the appropriate file-system read-rights.
- Futurama Server Management Site: to start and analyze Futurama Server jobs
- Configuration – Log: the configuration of the Futurama logging
- Installation Futurama Server: the installation of Futurama Server
- Configuration - Debug: the configuration of the Futurama debug features
If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.