Checkbox is capable of producing two kinds of logs: regular system logs, which can help you (and Support) to identify problems, and audit logs, which can be used by your organization to provide a "paper trail" of actions taken within the system. Both are easy to set up by modifying configuration files inside your Checkbox installation.
System Logs
To enable system logs on Checkbox 8, you'll need to modify a configuration file in two places, since Checkbox has two sub-systems that write their own distinct logs: The API and the Service. We'll begin with the API, since most errors would be logged there.
You'll find the API configuration file in your Checkbox installation directory on the server. The default location of the file is "C:\inetpub\wwwroot\Checkbox\api-core\Configs\Logging.json", but if you have not installed Checkbox in the default location this may be a bit different. This file can be opened in any text editor, and the contents will look like this:
{
"logging": {
"minLogLevel": "Debug",
"fileSinks": [],
"seqSinks": [],
"msSqlServerSinks": []
}
}
This file is defining "sinks," or destinations, to write the logs to. There are three valid kinds of destinations, and all three are currently empty collections, denoted by "[]". We can see that logs may be written to a file, an SEQ central logging server, or a MSSQL server database.
To change the configuration to write to a log file, alter the configuration file like so:
{
"logging": {
"minLogLevel": "Warning",
"fileSinks": [
{
"fileSizeLimitBytes": 1048576,
"logDirectory": "c:\\inetpub\\wwwroot\\Checkbox\\api-core\\App_Data\\Logs",
"rollingInterval": "Day",
"loggerType": "Default",
"minLogLevel": "Warning"
}
],
"seqSinks": [],
"msSqlServerSinks": []
}
}
This will set up logging to begin writing log files to the default directory. As configured in this sample, they will be written to "C:\inetpub\wwwroot\Checkbox\api-core\App_Data\Logs". Note that the path separator is written as "\\" in the configuration file - this is intentional and path separators must be doubled-up in the configuration. Take care that the directory exists, that there is hard drive space available, and that the IIS process has permission to write to this directory.
Any combination of the three sinks may be used. For instance, to write both to a file and to MSSQL server (but not SEQ), you would set the configuration file up like this:
{
"logging": {
"minLogLevel": "Warning",
"fileSinks": [
{
"fileSizeLimitBytes": 1048576,
"logDirectory": "c:\\inetpub\\wwwroot\\Checkbox\\api-core\\App_Data\\Logs",
"rollingInterval": "Day",
"loggerType": "Default",
"minLogLevel": "Warning"
}
],
"seqSinks": [],
"msSqlServerSinks": [
{
"connectionString": "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;",
"tableName": "SystemLogs",
"loggerType": "Default",
"minLogLevel": "Warning"
}
]
}
}
Note that you must replace the values inside curly braces "{ }" with the values for your server. In the above example I have replaced those values with sample data; you must replace them with your own information.
In order to log system errors from the Checkbox Service - which handles background tasks like sending e-mail and generating report PDFs - you would edit its configuration file, which is in a separate location. In a default installation, it would be at "C:\inetpub\wwwroot\Checkbox\checkbox-service-core\Configs\Logging.json". This configuration file is identical and can be edited in the same way as the API configuration.
To ensure that your changed settings take effect, you should restart the application on the server by restarting the site or recycling the app pool.
Audit Logs
To enable audit logs on Checkbox 8, only one configuration file needs to be edited, because the Checkbox Service does not produce audit events. This configuration file can be found at "C:\inetpub\wwwroot\Checkbox\api-core\Configs\Audit.json" and it looks very similar to the system logging configuration file, although SEQ is not supported.
{
"audit": {
"fileSinks": [
{
"logDirectory": "c:\\inetpub\\wwwroot\\Checkbox\\api-core\\App_Data\\AuditLogs",
"rollingInterval": "Day",
"fileSizeLimitBytes": 1048576
}
],
"msSqlSinks": []
}
}
The same rules as used for the System Logs apply here, though the only value for a SQL Server sink is the connection string. This is because it will always write to the "ckbx_AuditLog" table, and it is created automatically when the first log entry is written.
To ensure that your changed settings take effect, you should restart the application on the server by restarting the site or recycling the app pool.
It should be noted that the best practice for legal or regulatory compliance via audit logging is to periodically store your audit logs to write-once media, which is then stored in a secure physical location. This prevents tampering and proves custody in a way that writable digital storage does not. To accomplish this, the "file" output should be used and should be copied to your write-once media at an interval established by your policy. Of course, if your needs are not strict enough to dictate write-once media, the audit log can be used without any further work on your part.
Troubleshooting
"My logs are not being written to the file output."
This is likely occurring because the IIS worker process does not have write access to the directory that you have defined as the location to write logs. Carefully double-check write access to this directory.
"My logs are not being written to SQL Server/SEQ."
Doublecheck your connection information. If this information is incorrect, the logging attempt will fail silently rather than halting the application, although if you also have file logging turned on it may capture the connection error.
0 Comments