Querying Audit Records
How to Work with Audit Records
The following topics describe tasks that involve running queries against the audit records. Before undertaking these tasks, be familiar with the AuditMaster interface, as described in Using AuditMaster Viewer.
Displaying Audit Records
AuditMaster monitors application data records for various changes and operations. As it audits these events, it writes audit records to a log file. To access the new records, they are moved to a view file.
Audit records are displayed by queries. A query can include the current view file, one or more archived files, or both current view and archived files. Before querying the current view file, you first should update it to retrieve any new audit records from the log file.
This section covers the following tasks:
1
In the data tree, right-click the current view file and select Update Current View File, or in the toolbar, select the update current view file icon .
An icon shows that the update is in progress.
2
The tree expands to show information like the following:
You may now query the file for audit records.
Note The Update Status step is optional. However, since the time to finish the update depends on the size of the log file, it may be helpful to check that the update has finished. For large updates, to be sure that all records are ready to query, update the status and then use Admin > View Status Log to look for the “end of current view file update” message.
1
2
Select the File > Query command.
3
The Files tab shows the view files available for audit record query.
By default, the current view file is selected.
4
Click the Execute button at the bottom of the window.
The result of the query appears in the audit record grid.
Figure 1 Sample Audit Record Grid
To change which record columns are visible and the order in which they are displayed, see Working with the Audit Record Grid. To view an individual record in detail, see Viewing Audit Record Details.
Working with the Audit Record Grid
Queries display audit data in the audit record grid. Each column in the grid shows information for each audit record, such as its capture date and time, table name, operation, and user name. The following table provides options for working with and customizing the audit record grid display.
 
See Audit Record Columns for more information about individual columns.
Audit Record Columns
The following table lists all possible columns for an audit record. The Visible Columns setting determines which ones are displayed in the audit record grid. Column order also can be rearranged in Visible Columns, or you can drag and drop columns with the mouse.
 
Note: MAC addresses are not available from remote clients in the current release.
Viewing Audit Record Details
To see the details of an audit record, click the record in the audit grid to display it in the lower part of the viewer window. If the audit record captures before-and-after changes to an application data record, the detail view shows both versions of the data record with the change highlighted in red.
If the database schema is used, then the changes are readable, as in the following Demodata example.
If no schema is used, then the changes are shown in hexadecimal, resembling the following example.
Working with Archived Audit Records
Auditing can generate large numbers of audit records. To manage them, AuditMaster periodically empties the audit log to an archived file. The default archive file size is 75 MB. To reset the default size or choose archiving by date, see Automated Archiving.
Archived files for each server appear in the data tree. The file name uses creation time in the format yyyymmdd.nn, where yyyy is the year, mm is the month, dd is the day, and nn is the number of the archive file created that day, starting with zero.
Compressing archived files saves as much as 90 percent disk space. AuditMaster encrypts compressed archived files to restrict access to users within the AuditMaster system. Moving an archived file out of its folder (i.e., \Arch or \Comp in the installation directory) grays out its entry in the data tree. Moving it back restores the entry and enables queries again. Permanently deleted files cannot be restored.
The data tree provides several archived file commands. As shown in the following table, right-clicking an archived file offers commands depending on whether the file is compressed. Some comments, such as queries, may be run only on uncompressed files.
Query. Run a query against the file.
Execute Saved Query. Run a saved query.
Compress. Compress the file.
Decompress. Decompress the file.
Delete. Remove the file permanently.
Get File Information. Expand the data tree to show compression status, number of records, file size, last record in archive, and date range of included records.
AuditMaster provides two ways to create archived files:
Using the Data Tree to Archive Audit Records
When you first install an AuditMaster event handler and its server appears in the data tree, no audit records have been archived. If you expand Archived Files, the number of archived files is zero.
After you begin logging, audit records may be archived. The system automatically creates an archived file when the audit log reaches a set limit by size or by date and time. You can also archive manually.
Note In the data tree, you may sometimes need to right-click the Archived Files icon and select Refresh All to update the list.
This section covers the following tasks:
To automate archiving, see Automated Archiving.
You may want to archive manually for the following reasons:
In the data tree, select the current view file and do one of two things:
Select Server > Archive Current View File, or right-click the file and select Archive.
Select Server > Archive & Compress Current View File, or right-click the file and select Archive & Compress. Large numbers of records can take time, so you may want to use Admin > View Status Log command to check for the “finished compressing” message.
You cannot run a query against a compressed archive file. You must first decompress it by right-clicking and selecting Decompress.
You can control the number of archived files listed in the data tree, which displays both uncompressed and compressed archived files.
The default setting for the number of archived files displayed in the list is 15. Displaying a shorter list does not delete archived files but only removes them from the display. They remain in the \Arch and \Comp folders in the AuditMaster root directory (e.g., default C:\<installation directory>\Audit). Raising the number in the setting displays them again.
1
Select View > Set Archives to Show to open the Archives to Show dialog.
2
In the data tree, you may need to right-click the Archived Files icon and select Refresh All. Refreshing a data tree where the number of archives to show has been reduced, new icons appear in the tree to enable you to scroll the list to the next or previous group, or to go directly to the bottom or back to the top to see the last or first grouping.
Using Archive Manager
Archive Manager is a tool for handling audit archives. Before using it, first read Working with Archived Audit Records.
In the data tree, you handle one archived file at a time, but Archive Manager allows you to work with several archived files as a group. The Tools > Archive Manager command displays its window.
This example corresponds to Archived Files in the data tree:
After auditing has occurred, the data tree might appear like this:
And the Uncompressed tab would show this:
While the Compressed tab would show this:
In each case, the appropriate buttons are available at the bottom of the Archive Manager window:
 
Compress. Compress the file.
Decompress. Decompress the file.
Delete. Remove the file permanently.
Select All. Highlight all files in the list.
Clear All. Clear highlighting on selected files.
Close. Close Archive Manager.
To use Archive Manager, click a button command after clicking a file to highlight it. Use the SHIFT key to select a range of files or the CTRL key to add a single file to the currently highlighted selection.
Note The larger the file, the longer it takes to decompress and become ready to query. For large files, to be sure all records are ready, select Admin > View Status Log to check the log for the “finished decompressing” message, even if the file icon shows as uncompressed. You may also want to right-click Archived Files in the data tree and select Refresh All to update the display.
Running Queries
To display audit records from a current view or archived file, you must first run a query using AuditMaster Query Builder. You may query for all available audit records in the files you select, or you may restrict the query to Who, Did What, From Where, When, or How. For example, you can search for audited events on a particular date, events from a selected table, or changes that were made by only one particular user.
Figure 2 Query Builder Window
This section covers the following topics:
Displaying All Audit Records
The simplest query in the Query Builder window is to display all audit records:
1
2
Select File > Query, or right-click and select Query.
The Query Builder window appears.
3
Audit records are displayed in the grid in the upper right-hand pane of the viewer.
Restricting a Query
Query Builder provides tabs for restricting a query to who, did what, from where, when, how, and in which audit record files to look.
1
 
Users
All records that contain a specific user or users
4.
If needed, you can add a user by clicking Add and typing in the specific user.
Operations, Groups, and Tables
Specific operations, such as an insert or a delete, in a specific type of table, in a specific group
1.
To find a specific type of operation, clear the All Operations option. You can also clear the All Groups or All Tables option. The list is now available.
Machine Names
Any information originating from a specific machine name.
1.
To find a specific machine name, clear the All Machine Names check box. The list of machine names is now available.
Specific Dates
Any activity on a specific date and within a time range
Note: The time range applies to each individual day in the date range (e.g., 8:00 a.m. to 5:00 p.m. on each day).
Processes or Programs
The program or process identified by AuditMaster in the Process Name column of the audit record grid
1.
To find a specific program or process, clear the All Processes option. The processes are now available.
2
In the save dialog box, provide a descriptive name for the query and click OK. For details on using a saved query, see Running a Saved Query or Last Query Executed.
3
The audit record grid displays the query result.
Building an Advanced Query
The Advanced tab is used to build complex queries that cannot be built using the other tabs. This tab can set expressions to evaluate for specific events and can also be used to query at the column level in an audited table if its schema has been imported.
The following example shows the creation of a query to search for all inserts into the database on a specific day.
1
2
To customize your query, select the Use Advanced Expression Builder check box.
The expression area becomes active.
3
In the Type column, double-click Select Type to activate a drop-down list for the following query attributes:
 
Note All text values entered for Select Type are case-sensitive. For example, using defaultdb as the database name returns no result, since it does not match case with the name DefaultDB.
4
A calendar dialog box appears with the current date selected.
5
Click OK to accept the default date.
The date appears in the Value column.
6
In the Operation column, select a logical operator, or leave the default equal sign = as is.
The expression should resemble the following:
7
8
This option will select for records meeting the defined conditions but display only those for which alerts have tripped.
For more details, see Working with Alerts.
9
The Saved Queries window opens to enable you to give the query a name and save it for future use. See also Running a Saved Query or Last Query Executed.
10
The Query Builder executes the query and displays the results in the audit record grid.
Using the Files Tab
The Files tab allows you to select the current view and uncompressed archived files to include in a query.
1
2
You can query only uncompressed files. To see a file that is not listed, you must decompress it.
Note The larger the file, the longer it takes to decompress and become ready to query. For large files, to be sure that all records are ready, use the Admin > View Status Log command to check the status log for the “finished decompressing” message, even if the file icon shows as uncompressed. You may also want to right-click the Archived Files branch of the data tree and select Refresh All to update the display.
Running a Saved Query or Last Query Executed
For each AuditMaster server, queries are stored in the data tree under Saved Queries and Last Query Executed. This section covers the following topics:
1
2
The query is added to the list of existing queries and will now appear in the data tree.
3
Click Close.
1
In the data tree, right-click a query under Saved Queries to see a list of choices:
Query Current View File. Run the query against the current view file.
Query Multiple View Files. Display the Files tab in the Query Builder to select the files against which to run the query.
Rename. Change the name of the query.
Delete. Remove the query permanently from the list.
If you run a query, any result appears in the audit record grid. You may simply double-click a saved query to run it against the current view file.
Only uncompressed files can be queried. If a file used in a query has been compressed, you must decompress to run the query.
Note The larger the file, the longer it takes to decompress and become ready to query. For large files, to be sure that all records are ready, use the Admin > View Status Log command to check the status log for the “finished decompressing” message, even if the file icon shows as uncompressed. You may also want to right-click the Archived Files branch of the data tree and select Refresh All to update the display.
In the data tree, double-click the Last Query Executed.
Any result appears in the audit record grid.
Working with Alerts
AuditMaster provides an alert capability. The Alerts window enables you to create an alert to a specific event in a PSQL database. Once an alert is set, AuditMaster checks each new audit record for the alert condition. When found, AuditMaster executes an alert action. For example, when a data record is deleted, the system can send an alert to notify you by email. In the audit record grid, tripped alerts are flagged with an icon .
Caution Dramatic and undesirable consequences may arise from an alert with a broad query likely to match a large number of audit records, especially when the alert action sends email.
This section covers the following topics:
Note After creating or changing an alert, close AuditMaster Viewer and restart the AuditMaster event handler so that the alert takes effect. See Restarting the AuditMaster Event Handler.
Adding a New Alert
1
2
Select File > Alerts to open the Alerts window.
3
Click New to open a New Alert window.
4
In this example, we create an alert for new students in the PSQL Demodata database.
5
We recommend you describe the event the alert is to monitor.
6
Click Continue to open the Query Builder window.
7
For details on using these tabs, see Running Queries.
8
When you are finished, click OK to open the Action for Alert window.
9
The Alerts window shows the alert that was just added.
10
Setting an Action for an Alert
Once you have added an alert, you need to set an action to be performed each time AuditMaster finds a match for the alert condition.
You can set one or both of two actions for each alert:
Note From a viewer client on the server where AuditMaster is running, you can set actions both to send email or run a program on the server; however, from a remote viewer client you are unable to set an action to run a program on the server and can set only email alerts.
1
Select File > Alerts if the Alerts window is not open, and select an alert to configure.
2
Click Edit.
The Action for Alert window appears.
3
EmailAlert
The EmailAlert action sends an email to a specified group of addresses when an alert condition is met. To configure the email alert action, proceed to Setting an EmailAlert Action.
RunProgram
The RunProgram action runs a specified program on the server when an alert condition is met. To configure the program, proceed to Setting a RunProgram Action.
4
Selected actions are now set for the alert and will be performed if the alert condition is met.
Note After creating or changing an alert, close AuditMaster Viewer and restart the AuditMaster event handler so that the alert takes effect. See Restarting the AuditMaster Event Handler.
Setting an EmailAlert Action
1
If the Alerts window is not open, select File > Alerts, select the alert to configure, click the Action button, click EmailAlert, and click the Select button.
The EmailAlert action moves to the Selected Actions column.
2
The Configure EmailAlert window appears.
3
When the alert condition is met, addresses in this group will receive email.
4
5
For example, if your out-going mail server is named smtp-server.companyname.com, then enter smtp-server in this field.
6
7
Add the domain name and click OK. Continuing with the example from the last step, here you would enter companyname.com.
8
The Configure Groups window appears. For this demonstration, sample values have been filled in.
9
 
Click Add New Group, enter a name for the new group, and click OK.
Select a group name, click Edit Group Name, enter a new name for this group, and click OK.
Select a group name, click Delete Group, and click Yes to confirm. The group is deleted only for this alert and remains in the system for use in other alerts.
With a group selected, click Add New E-mail Address, enter the email address, and click OK.
With a group selected, select an email address, click Remove E-mail Address, and click Yes to confirm.
The following sample email alert was tripped by an insert in the Demodata database. If AuditMaster monitors a database without a schema, the application record data in the alert does not display the hexadecimal content. If the schema has been imported, then column names are displayed.
Setting a RunProgram Action
1
If the Alerts window is not open, select File > Alerts, select the alert to configure, click the Action button, click RunProgram, and click the Select button.
The RunProgram action moves to the Selected Actions column.
2
The Configure Programs window appears.
3
 
1.
Click the Add button.
2.
Click Remove.
3.
Click Yes to confirm.
2.
Click Set Parameters.
3.
Click the buttons to Add, Remove, or Change parameters for the program to be run.
4
5
Click Close to exit from the Alerts window.
Editing an Existing Alert
You can edit the name and description of an alert. However, you cannot change the conditions for the alert. To monitor for a different event, delete the old alert and enter a new one.
1
The Edit Alert window appears.
Figure 3 Edit Alert Window
2
Stopping an Alert
To stop an alert from running, you can disable its action or delete the alert entirely.
Note Deleting an alert does not delete any email group associated with its action. Email groups associated with an EmailAlert action remain in the system for use with other alerts.
1
The Edit Alert window appears.
2
Clear the Enabled check box, and click OK.
The alert action is disabled. You can enable it again later.
1
Click the alert to select it.
2
Click the Delete button.
A window prompts you to confirm the deletion.
3
Click Yes to confirm.
The alert is deleted and can no longer run.
Printing Reports
AuditMaster lets you print reports from the audit record grid.
1
2
Select File > Report.
The Report Builder window appears.
Figure 4 Report Builder after Running a Query and Selecting Audit Records
3
If you want to load and customize a saved report, click the Open Report File button and select the settings file for an existing report.
The report is loaded.
4
In the Report Title field, enter a name for this report.
This name will appear at the top of your printout.
5
You may select up to 30 columns. If you already selected a range of columns and rows, these are listed under Selected Columns. You may double-click other column names to move them to Selected Columns. Clicking Select All moves over all columns.
6
Select the Rows to Print.
All Rows. Click to select all rows of the columns you selected.
A Range of Rows. Click to define a range of rows and change the row numbers shown, which by default are the rows you highlighted in the audit record grid before you opened Report Builder.
7
Table Border. If you want the tables to have borders, select the border type from the list.
Print Page Numbers. Check the box beside the option to include the page number. Select whether to print the page number in the Left Footer or Left Header of the printout, as well as whether to include Date and Time.
Print Report Title. Select whether you want the report title to appear On Every Page or On the First Page Only.
Print Date and Time. Select if you want the date and time to appear in the footer of each printed report page.
8
The Report Print Preview window displays the report on-screen as it will be printed.
9
From the File menu in the Report Print Preview window, you may do the following:
Select Save Report As to save the current report settings for future reuse.
Select Open Report to use the settings in a saved report.
Select Page Setup to adjust standard page settings.
Select Print Setup to adjust standard printer settings.
Select Print to print the report.
Select Exit to return to Report Builder.
Searching Audit Records
You can use the search command to find particular users, operation types, or values for the current audit records grid view. AuditMaster uses a sophisticated search engine, so it is easy to use different search options and directions. Searches can also be made case-sensitive.
Note Depending on the number of records and the complexity of the search criteria, it may take some time to complete your search. Whenever possible, try to narrow your criteria.
1
Run a query, if needed.
2
Select Tools > Search.
The Search window appears. Also, if you have clicked in the audit record grid, the field you clicked is highlighted in blue as the current column and its row is highlighted in yellow.
3
Your search entries are saved in the drop-down list for the current session.
4
In the Direction drop-down list, select a direction to start the search. These include, From Top row down, the Next row down, and the Previous row down.
In the Position drop-down list, select a search position. Select Anywhere or Beginning of cell, as appropriate.
5
Select Entire Grid to search all columns.
Select Current Column to search only the column selected, which is indicated as a blue field in the yellow highlighted field that you have clicked. If this column is not the one you want to set as the current column to search, close the Search window, click the desired column, and search again.
Select Specific Column and select a column name from the drop-down list.
6
Found items, if any, appear highlighted in the audit record grid. Otherwise, the status bar at the bottom of the Search window displays the message, “The text was not found.”
Sorting Audit Records
Audit records can be sorted on up to three visible data fields. If needed, reset Visible Columns to add columns for sorting.
1
Run a query, if needed.
2
3
Select Tools > Sort.
The Sort window appears.
4
For example, User Name to order records alphabetically by user.
5
Select Ascending or Descending order for sorting.
For example, if you are sorting by Time, to start the list with the most recent records, choose Descending.
6
To sort again using a second and third column, select from each Then By drop-down list, including Ascending or Descending.
7
The audit record grid displays the sorted records.
Exporting Audit Records to Other Applications
AuditMaster can export any query result to a comma- or tab-delimited text file for importing into other applications.
Note Only records and fields visible in the query result are exported.
1
Run a query, if needed.
2
Select Tools > Export.
The Export window appears.
3
4
5
Click OK to export the file to filename.txt.
The export file is saved to the location and name you provided.
Note You can also extract audit data directly by copying from the AuditMaster audit record grid and pasting the rows and columns into another application, such as a spreadsheet.
Displaying Audit Records under PSQL Security
If you run AuditMaster with PSQL security enabled, field values in the User Name and Database Name columns vary with the DefaultDB database security policy and the type of database operation as shown in the following table.
Audited Btrieve operations include Select/Read, Insert, Update, Delete, Login, and Logout. For Begin Transaction, End Transaction, Abort Transaction, and Reset operations, which are not associated with a specific database, the database name is not available.
Login errors are listed with the invalid user name and/or database name. For SQL logins, the host name is not known at login time but afterward the host name becomes available and is displayed for SQL operations.
Under Mixed security, database logins match OS or network logins.
Note For more information on database operations in a PSQL security environment, find out more about in PSQL Advanced Operations Guide.
Using AuditMaster Undo
The AuditMaster Undo command makes it possible to reverse certain database events. A successful undo depends on the operation and the current state of the record involved, which may have changed again since the event occurred. In the case of updates to application data fields, the Before and After columns in the detail view identify what data value AuditMaster can attempt to restore to the Before state.
 
Caution Before attempting an undo, consider the following:
Note: Remote client logins do not support undo.
1
2
When prompted to confirm the undo attempt, click Yes, or Cancel if you change your mind.
If you selected multiple records to undo, you may select Yes to All to attempt to undo all of them without further interaction, or use the Skip and Yes buttons to work through them one at a time.
Note Each undo operation is captured as an audit record and can be reversed by an additional undo.