> #### Using a bookmark

> You create a bookmark and insert it into your log file to indicate the exact point from which the log file monitor is reading data. To accurately monitor and manage a log file, the log file monitor needs to know its exact position within the file and have a dependable means to reset its file position if it loses its place within the file due to truncation. If you opt not to set a bookmark, you choose which truncation action Fathom follows: searching only new data, or searching the entire file.

> You are strongly encouraged to use bookmarks with monitors you create for OpenEdge log files. However, using the bookmark feature in non-OpenEdge log files might cause problems using the log. If you have an application that parses out its own log file, it could get tripped up on information it considers foreign.

> You might detect a small performance gain in running the log file resource monitor when the log file is truncated; however, you will sacrifice accuracy within your log file data, exposing the data and monitoring operations to an unnecessary high level of risk and unpredictable accuracy in your log file reads.

> ##### Bookmark and truncation considerations

> Due to the volume of data stored, some log files have a potential to grow very large. A database administrator (DBA) will typically truncate these files periodically to minimize the amount of space they occupy on a system. The existence of bookmarks within a log file ensures that regardless of what happens to your file when it is truncated, your log file monitor always has a way to reposition itself accurately within the file.

> Data can be truncated at any point within a file. Consequently, when bookmarks are not used and a file has been truncated, the log file monitor has only a limited number of options to determine its new position. Bookmarks represent your most reliable means to reposition your log file monitor accurately so that the data you use is accurate.

> For example, if a DBA truncated 500 lines of data at the beginning of a log and, in the meantime, 1000 more data lines were added at the end of the file, the log file will reposition the new reference mark somewhere within the last 500 data lines; having "lost" 500 lines, the log file monitor only "knows" it has to read ahead 500 lines into the new data and reposition itself. Under this situation, the fact that 500 lines of data have been truncated has been obscured by the existence of the new data. Not having a bookmark to reference as a point of origin, the log file monitor can, and does, reposition itself 500 lines into the "newer" data lines that have been written. Unfortunately, this approach incorrectly allows the data to be misread, since the balance of the 500 newer data lines are left unread. Had bookmarks been used in this circumstance, this error would have been avoided.

> Note: Under certain circumstances, you might not be concerned with unread data. For example, if you are performing software testing activities, log files might be deleted frequently. Therefore, you might not need to set bookmarks to ensure accurate repositioning occurs after a file has been truncated.

> If the monitored log file has changed since the last poll and the bookmark feature is enabled, a new bookmark is inserted.

> ##### Setting a bookmark

> You can set a custom bookmark or use the last line as the bookmark.

> To set a bookmark from the Create Log File Monitor page:

> 1. In the Bookmark section, select Use bookmark.
> 2. Select one of the following two ways to set bookmark attributes:
> - Use custom bookmark (Specify bookmark)
> You can choose either to use the default bookmark named Fathom_Bookmark or define a new bookmark. If you define a bookmark, the value you enter is not restricted to a certain length. However, for practical purposes, you might want to consider keeping it a reasonable length.

> Additionally, you can choose to prepend a time stamp to your bookmark name selection. You should always select this option. The date and time value uniquely qualifies each bookmark that has this data prepended to its bookmark name. In situations where the log file monitor must reposition itself within the log file, this type of bookmark will always be found.

> - Use last line as bookmark
> This option records the last line of a given poll as a bookmark internally (Unlike the custom bookmark, this information is not written in the log file being monitored.)

> Choosing this option indicates that you want to use the last line as the bookmark. The last line is referenced as it is randomly defined in the file; it is likely that the line will not be unique. If your log file has a date and time stamp on each line, or other data that makes each line unique, select the Each line unique option. This refinement will increase the log file monitor's accuracy.

> If you do not use the Each Line Unique option, you must specify one of the possible two Truncate Action selections from the drop-down list.

> 3. Click Save. The Create Monitoring Plan definition page appears:

> ##### Truncating a log file

> If you choose to truncate a log file, the file will not use a defined bookmark to reference its position within the log file. Therefore, you must indicate how you want the log file monitor to interact with the log file when the file has been truncated.

> You might detect a small performance gain in running the log file resource monitor when the log file is truncated. However, you will sacrifice accuracy within your log file data, exposing the data and monitoring operations to an unnecessary high level of risk and unpredictable accuracy in your log file reads.

> You can choose either of the following truncation actions:

> - Search only new data
> Fathom resets the log file monitor's internal place marker to the end of the file on its first poll after the file has been truncated.

> - Search entire file
> Fathom searches the log file from beginning to end on its first poll after the file has been truncated. Remember that this technique will ensure that no data is missed when a file is truncated, but much of the file could be searched a second time. If the file is very large, this can be a slow operation.

Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095