How to Use the Text Based Support Logging
This document describes the how the text based Technical Support logging works in SpecVet and how to add logging to a script.
The new logging system for SpecVet utilizes a text file in place of creating records in the Log table. This process is for Technical Support logs only. Client facing logs are still maintained in the Log table.
The main advantages of this method are:
- Reduced file size - Text files are significantly smaller than the log table.
- Logging process is offloaded from the server to the client. - This should reduce client load.
- Client facing log data can be separated from technical support log data.
- Support Logs can be easily purged via automatic scripting.
Log File Types
There are two types of log files that can be created.
- Event Logs - These contain the main log entry that is made whenever the log script is called. Event Logs contain the following data: TimeStamp, Site, Workstation, User, Module, Process, Result, ResultFileExists.
- Result Logs - These contain optional an optional entry that can hold diagnostic data related to the main Event Log e.g. XML resulting from a web service transaction. Result Log entries can be matched to Event Log entries by timestamp.
- Files are written as a standard text [.txt.] file.
- File data is pipe delimited [|] to aid in parsing.
- A new log file is created daily for each type.
- All entries for a given day are written to the same file.
- Files are named as the log type and date e.g. EventLog20160615.txt.
- Files are kept indefinitely unless the deletion process has been implemented. (See below)
An Event Log is always created when the log script is called. A Result Log may also be created if the script is configured to do so.
The text log files are written to the FileMaker Server Documents folder. Typical file paths are as follows:
- Windows - C:\Program Files\FileMaker\FileMaker Server\Data\Documents
- Macintosh - Macintosh HD/Library/FileMaker Server/Data/Documents
In addition to the base file paths, there are two extended file paths that are controlled via entries in the Settings table:
- log.path.event - typically set to: /Logs/Event
- log.path.result - typically set to : /Logs/Result
If paths are not specified in the Settings. Files will be written to the root Documents folder of the FMS.
It is not necessary to create any directories/folders on the operating system. The logging code will create the specified paths if they do not exist.
The following custom function is required for this logging process:
- CurrentHostTimestampMilliseconds - This function returns the current server timestamp with milliseconds.
There are four scripts related to this logging process:
- Server: Create/Append Log (Various) - This is the main logging script. It is completely abstract and does not need to be modified.
- Development: Write Server Log File - This script contains the code that can be copied and pasted into the script where the log process needs to be executed.
- Server: Delete Old Logs - This script is a server side script to automatically remove old log files.
- Development: Log Test - This script is only used for troubleshooting the main logging script. It is not used in normal development.
Do not modify the main logging script! This will break the logging function.
The logging process works as follows:
- The script calling for logging gathers the data to be logged.
- Calling script calls the logging script using Perform Script on Server and passing the logging data as script parameters.
- The server executes the logging process.
- The calling script does not wait for the logging process to complete before continuing.
- This process works the same for both Server and Client calling scripts.
To implement logging, use the following steps:
- Open the Development: Write Server Log File script.
- Copy the code located between the delineation markings.
3. Paste the copied code into the script where you want the logging to occur.
4. Modify the values of the four variables at the top of the pasted code:
- $Module - This is the main category.
- $Process - This is a subcategory.
- $ResultShort - This is a brief description of the result.
- $ResultLong - This is where result data should be place. This data will be written to the Result Log File.
It is advisable to use consistent values for the $Module and $Process variables to aid in parsing data.
The $ResultLog variable determines whether a Result Log is created. If the $ResultLong variable is defined, a Result Log will be created. Otherwise it will not.
Do not modify the names of the variables or any of the other pasted code--just the variable values.
Automatic log file deletion can be maintained via the Server: Delete Old Logs script.
There are two optional Settings used with the deletion process:
- log.delete.days.event - This specifies the number of days to keep Event Log files. Example setting: 30
- log.delete.days.result - This specifies the number of days to keep Result Log files. Example setting: 7
The Server: Delete Old Logs script must be set up as a Server Schedule on FileMaker Server.
If no Settings are specified for deletion days, the delete script automatically uses 30 for Events and 7 for Results.