For each WebSTAR transaction, the server displays a line in the monitor window and saves an entry in the log file. The Log Format panel lets you specify what kind of information to include in these entries. You can choose between the WebSTAR Log Format, the Common Log Format (CLF) and Extended Log Format (ExLF). They allow you to save data in formats compatible with many third-party log analysis programs. These applications will read through your log file or multiple files, and create statistical reports on web site usage. For information on compatible log analyzers, see
http://www.starnine.com/extendingwebstar.html
Log entries are composed of tokens --elementary pieces of data about a transaction, such as the date, time, result, and client host name. Each of these tokens is separated from the next by a Tab character. Each entry (all tokens for a single transaction) is on one line, separated from the next by a Carriage Return character. You can import these files into spreadsheet and database applications.
Beyond the standard formats, you can add additional data to your log, to give yourself more information to understand use of your site. Many log analyzers will ignore the additional tokens, but some will not: be prepared to remove the data if necessary. In addition, some fields may not have values for some browsers.
You can change the WebSTAR Log Format and the Extended Log Format, but the Common Log Format is limited to standard tokens.
The DATE and TIME tokens use GMT (Greenwich Mean Time). This allows log analysis programs to compare logs from mirrored servers worldwide. If you need this functionality, be sure to set your Mac Date and Time control panel correctly, so WebSTAR can calculate the correct offset from GMT.
Don't forget to adjust your clock when Daylight Savings Time begins and ends. You can also use the Mac OS feature to do this automatically.
Initialization information, such as the list of the Plug-Ins installed and the Virtual Hosts, is not logged.
Some of the log tokens include the host name of the client or the server. These will only appear if you have selected the option to Caching . Otherwise, those log tokens will appear as dashes ("-"). Many log analysis programs can do batch host name lookups based on the IP address, which provides you with that information without slowing down your web server.
Every time you change the log format, the new format token names will be displayed in the monitor window in the WebSTAR Admin application, and saved in the log file. For example, the default WebSTAR Web server log format appears like this:
Log analysis applications use this header to map to their internal databases, so changing formats may confuse the analysis. To avoid this, start a new log file when changing formats: choose Suspend Logging from the server or Admin Options menu, rename or move your log file, change formats, then choose Start Logging to begin saving data to the log file again.
Only one log is kept for each host served by the WebSTAR Web server: virtual domains do not have separate files. The file name tokens do include the entire file path, including the virtual host root folder names, and the HOSTNAME token displays the host name requested by the browser. Many log analysis applications are starting to log display statistic information for the entire server, which of course takes into consideration multiple sites. If you want separate log files, you will need to use a third-party logging application.
The three standard formats are WebSTAR Log Format (WLF), the Common Log Format (CLF) and Extended Log Format (ExLF). Entries in the log file are separated by tabs, and individual entries are terminated with a carriage return. This format is the standard text-only import format used by most spreadsheet applications, such as Excel, by database applications like FileMaker, and by log file analysis applications.
The default value for the WebSTAR Log format (WLF) consists of the fields DATE TIME RESULT STATUS HOSTNAME AGENT REFERER HOSTFIELD URL BYTES_SENT . You can add, change or rearrange these fields. Many Mac-specific log analysis programs will handle these fields properly, although they may ignore other fields. WebSTAR Log format will make entries that look like this:
For information about these fields, see Log Tokens Table .
See Configuring the Log Format for information about adding additional fields.
The Common Log Format is a standard used by most web servers that provides basic logging of the information necessary to do statistical analysis of server usage. Many analysis tools support this format. CLF uses standard fields that are not user-selectable. The standard information for this format is available at:
http://www.w3.org/Daemon/User/Config/Logging.html#
common-logfile-format
It produces entries that consist of the following tokens:
There are no defaults for this format, but you can choose from any of the tokens available. This data is used by many cross-platform log analysis programs. For more information, see:
http://www.w3.org/pub/WWW/TR/WD-logfile.html
WebSTAR will display a header and the token names and store this information in the Log File. This allows log-file analysis programs to recognize and store the data correctly. The fields themselves are tab-delimited. Extended Log format files look like this:
WebSTAR allows you to customize your log data when using either WebSTAR or Extended log formats. Choose the tokens and the order that you prefer, as described in Configuring the Log Format .
The tokens beginning with " CS " are "client to server", where the information is mainly about the client.
" CS- " is used for information regarding the request itself, including the IP address, the client host name (if available), the HTTP request, and so on.
" CS() " tokens are used to designate data that is extracted from the HTTP header. Anything in the CS() parentheses will be the name of a header field.
For example, the client may send a Host: www.domain.com field in the header, so the CS(HOST) token will display www.domain.com . If you are using virtual hosts, the browser will send the host name of the Virtual Domain or that associated with the secondary IP address in the CS(HOST) token. This allows log analysis programs to track requests to the various hosts.
If data is missing, tokens with items in parentheses like CS(METHOD ) are logged as an empty quoted string ("") if they are empty or not present. All other tokens are logged as a single dash ("-") if not present.
"DNS" tokens will be filled in and "IP" tokens will be a dash if you set Use DNS for Server and Client Lookups . Otherwise, the "IP" tokens will be filled in and the "DNS" tokens will be a dash.
The Results token returns three codes: "OK", "ERR" (error, usually if a file was not found) or "PRIV" (user was not allowed access to a realm). However, these are limited to what the WebSTAR server knows about. For example, you might have a bad URL that is pointing to a non-existent file, but if it is handled by a Plug-In WebSTAR regards this as OK, because it just hands off that URL to the Plug-In. By the time the plug-in knows that the file can't be found, it's too late to change the Results, which will be recorded as OK. This is why it's usually more accurate to record SC-STATUS instead.
In this table, tokens which are included in the default WebSTAR Log format have a check in the "WLF" column, and tokens allowed in the Extended Log format have a checkmark in the "ExLF" column.
You can specify the Log format in the WebSTAR Admin application or in the Browser Admin pages (Settings > Log Format). When you change from one format to another, make sure you Suspend Logging, and copy the current logfile. This is particularly important if you are using a log analysis application.
Choose WebSTAR, Common or Extended Log format from the popup menu. If you're using the Browser admin, be sure to click the "Save Format Type" button.
You can use the default fields or customize your log fields (for WebSTAR and Extended Log Formats). WebSTAR will display the existing log format and allow you to add or remove tokens from the format.
The obsolete CS-HOST and CS-IP are no longer available in this list.
In the WebSTAR Admin, the "Log Format List" on the right displays your current log tokens. The "Log Format Tokens" list on the left displays additional tokens, in alphabetical order. Drag a token from that list to the Log Format List to add this token to your log format. To remove a token from your list, drag it back to the Log Format Tokens list (don't worry about the order).
In the Browser Admin, the Log Format page displays 31 fields, each with a popup menu of the available log tokens. You can change each field to the format you prefer.
When you click the Save button, the server will display the header for the new format in the log file, and will use the new format for all transactions.