test

Sun Java System Web Server 6.1 SP9 NSAPI Programmer's Guide

flex-init

Applicable in Init-class directives.

The flex-init function opens the named log file to be used for flexible logging and establishes a record format for it. The log format is recorded in the first line of the log file. You cannot change the log format while the log file is in use by the server.

The flex-log function (applicable in AddLog-class directives) writes entries into the log file during the AddLog stage of the request-handling process.

The log file stays open until the server is shut down or restarted (at which time all logs are closed and reopened).

Note –

If the server has AddLog-stage directives that call flex-log, the flexible log file must be initialized by flex-init during server initialization.

For more information about flex-log, see information about predefined SAFs in the obj.conf file in the Sun Java System Web Server 6.1 SP9 Administrator’s Configuration File Reference.

You may specify multiple log file names in the same flex-init function call. Then use multiple AddLog directives with the flex-log function to log transactions to each log file.

The flex-init function may be called more than once. Each new log file name and format will be added to the list of log files.

If you move, remove, or change the currently active log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup the currently active log file, you need to rename the file and then restart the server. The server first looks for the log file by name, and if it doesn’t find it, creates a new one (the renamed original log file is left for you to use).

For information on rotating log files, see flex-rotate-init.

The flex-init function has three parameters: one that names the log file, one that specifies the format of each record in that file, and one that specifies the logging mode.

Parameters

The following table describes parameters for the flex-init function.

Table 2–4 flex-init parameters

Parameter  

Description  

logFileName

Name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example:

access="/usr/netscape/server4/https-servername/logs/access"mylogfile = "log1"

You will use the log file name later, as a parameter to the flex-log function (applicable in AddLog-class directives).

buffer-size

Specifies the size of the global log buffer. The default is 8192. See the third flex-init example below.

buffers-per-file

Specifies the number of buffers for a given log file. The default value is determined by the server. 

Access log entries can be logged in strict chronological order by using a single buffer per log file. To accomplish this, add buffers-per-file="1" to the Init fn="flex-log-init" line in magnus.conf. This ensures that requests are logged in chronological order. Note that this approach will result in decreased performance when the server is under heavy load.

format.logFileName

Specifies the format of each log entry in the log file. 

For information about the format, see the flex-init

More on Log Format

The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in the server. (The one exception to this rule is the %SYSDATE% component, which delivers the current system date.) %SYSDATE% is formatted using the time format %d/%b/%Y:%H:%M:%S plus the offset from GMT.

(See Chapter 3, Creating Custom SAFs for more information about parameter blocks, and Chapter 7, NSAPI Function Reference.)

Any additional text is treated as literal text, so you can add to the line to make it more readable. Typical components of the formatting parameter are listed in the following table flex-init. Certain components might contain spaces, so they should be bounded by escaped quotes (\").

If no format parameter is specified for a log file, the common log format is used:

"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
\"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status%
%Req->srvhdrs.content-length%"

You can now log cookies by logging the Req->headers.cookie.name component.

In the following table, the components that are enclosed in escaped double quotes (\") are the ones that could potentially resolve to values that have white spaces.

Table 2–5 Typical Components of flex-init Formatting

Flex-log Option  

Component  

Client host name (unless iponly is specified in flex-log or DNS name is not available) or IP address

%Ses->client.ip%

Client DNS name 

%Ses->client.dns%

System date 

%SYSDATE%

Full HTTP request line 

\"%Req->reqpb.clf-request%\"

Status 

%Req->srvhdrs.clf-status%

Response content length 

%Req->srvhdrs.content-length%

Response content type 

%Req->srvhdrs.content-type%

Referer header 

\"%Req->headers.referer%\"

User-agent header 

\"%Req->headers.user-agent%\"

HTTP method 

%Req->reqpb.method%

HTTP URI 

%Req->reqpb.uri%

HTTP query string 

%Req->reqpb.query%

HTTP protocol version 

%Req->reqpb.protocol%

Accept header 

%Req->headers.accept%

Date header 

%Req->headers.date%

If-Modified-Since header 

%Req->headers.if-modified-since%

Authorization header 

%Req->headers.authorization%

Any header value 

%Req->headers.headername%

Name of authorized user 

%Req->vars.auth-user%

Value of a cookie 

%Req->headers.cookie.name%

Value of any variablein Req->vars

%Req->vars.varname%

Virtual server ID 

%vsid%

Duration 

%duration%

Records the time in microseconds the server spent handling the request. Statistics must be enabled for the server instance before %duration% can be used. For information about enabling statistics, see Sun Java System Web Server 6.1 SP9 Administrator’s Guide.

Examples

The first example below initializes flexible logging into the file /usr/sun/webserver61/server1/https-servername/logs/access.

Init fn=flex-init access="/usr/sun/webserver61/server1/https-servername
/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% 
[%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% 
%Req->srvhdrs.content-length%"

This will record the following items:

Init fn=flex-init extended="/usr/sun/webserver61/server1/https-servername
/logs/extended" format.extended="%Ses->client.ip% - %Req->vars.auth-user%
[%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status%
%Req->srvhdrs.content-length% %Req->headers.referer% \"%Req->
headers.user-agent%\" %Req->reqpb.method% %Req->reqpb.uri% %Req->
reqpb.query% %Req->reqpb.protocol%"

The third example shows how logging can be tuned to prevent request handling threads from making blocking calls when writing to log files, instead delegating these calls to the log flush thread.

Doubling the size of the buffer-size and num-buffers parameters from their defaults and lowering the value of the LogFlushInterval magnus.conf directive to 4 seconds (see Chapter 2, SAFs in the magnus.conf File 

Init fn=flex-init buffer-size=16384 num-buffers=2000 
access="/usr/sun/webserver61/server1/https-servername/logs/access" 
format.access="%Ses->client.ip% - %Req->vars.auth-user% 
[%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% 
%Req->srvhdrs.content-length%"

See Also

flex-rotate-init