Custom logs give you the flexibility as to what data is captured, the manner in which it is displayed, and the ability to have multiple conditional logs.
Custom logs can be configured by using rules. Each rule has a condition and an action, and are used to determine the conditions upon which log actions are executed. The condition must be met in order for the corresponding action to be taken. In order to add a rule, use the manageODR.py script. Custom property objects are allowed at the ruleset, rule, and action level.
An expression field is used to determine the requests and responses to log. This expression uses the standard HTTP language operands, plus custom log operand response.code to filter by HTTP response codes, such as 404, 503, and so on. For example, response.code = 200 would get all responses of response code 200. The HTTP custom log operand targetserver is used to show the server where the request was sent in a WebSphere Application Server format. The HTTP custom log operand service.time is the time frame between when the request is sent to the application server, and when a response is received from the application server. The HTTP custom log operand response.time is the timeframe between when the request in the ODR is received, and when the request until the response from the ODR is sent. The following table describes the operands that can be used in rule expressions.
Operand | Syntax | Description |
---|---|---|
Client host |
clienthost | The fully-qualified client host name. This is the value of the internet protocol (IP) command host name. This operand does not support numeric operators such as >, >=, <, <=. |
Client IPV4 |
clientipv4 | The IP address of the client using the Internet Protocol version 4 (IPv4) dotted quad address type n.n.n.n. |
Client IPV6 |
clientipv6 | The Internet Protocol version 6 (IPv6) 128-bit address type of x:x:x:x:x:x:x:x following Request for Comments 1924 (RFC 1924) of the client computer. |
Cookie name |
cookie$<name> | A cookie name. For example, the expression cookie$My_Cookie_Name='My_Cookie_Value' tests
a request to see if it contains a cookie named My_Cookie_Name with
a value of My_Cookie_Value. To test for the
presence or absence of a particular cookie, use one of the following
expressions:
cookie$MyCookieName IS NOT NULL cookie$MyCookieName IS NULL |
Header name |
header $<name> | A header name and value. For example, the
expression header$Host='localhost' tests a request to see
if it contains an HTTP host header with a value of localhost.
To test for presence or absence of the host header, use one of the
following expressions:
header$Host IS NOT NULL header$Host IS NULL |
HTTP method |
HTTPMethod | The HTTP method for the request. Possible values are POST, GET, PUT, and DELETE. |
MIME type |
MIMEType | The MIME type of the request. |
Percentage |
percentage$<val> | The percentage operand evaluates to true,
a fixed percentage of the time. For example, percentage$50 evaluates to true on average 50% of the time. |
Port |
port | The listening port on which the request was received. |
Protocol |
protocol | The communications protocol that transmits the request. Currently supported protocols are HTTP, HTTPS, SOAP, and SOAPS. |
Query parameter |
queryparm$<name> | A header name and value. For example, the
expression queryparm$timezone='EST' tests a request to see
if the request contains an HTTP query parameter named timezone with
a value of EST. To test for presence or absence
of a query parameter, use one of the following forms:
queryparm$timezone IS NOT NULL queryparm$timezone IS NULL |
Rampup |
rampup$<startTime>$<completionTime> | The rampup operand evaluates to true a
variable percentage of the time. It always evaluates to false before <startTime> and
to true after <completionTime>.
As time progresses from <startTime> to <completionTime>,
it evaluates to true, a linearly increasing percentage. The format of <startTime> and <completionTime> is day/month/year::hour:min:sec. where day is the day of the month, month is one of the twelve months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec, year is the 4 digit year, hour is the 2 digit hour of the 24 hour clock, and min and sec are 2 digit values for minute and second, respectively.For example, rampup$01/Jan/2007::08:00:00$01/Jan/2007::17:00:00 begins to occasionally evaluate to true at 8 AM on Jan 1, 2007 and always evaluates to true by ramp up completion time at 5 PM of the same day. |
Response code |
response.code | Filters by HTTP response codes, such as 404, 503, and so on. |
Response time |
response.time | The number of milliseconds between when the request in the ODR is received, and until the response from the ODR is sent. |
Response write error |
response.write.error | Logs errors that can occur when writing a response to a client. |
Service time |
service.time | The number of milliseconds between when the request is sent to the application server, and when a response is received from the application server. |
Target server |
targetserver | Shows the server where the request was sent, in a WebSphere® Application Server format. For example, mycell/mynode/myserver. |
Scheme of URI |
request.uri.scheme | The scheme of the URI. |
Server host |
serverhost | The fully-qualified host name of the server. This operand does not support numeric operators such as >, >=, <, <=. |
Server IPV4 |
serveripv4 | The IP address of the server computer using the IPv4 dotted quad address type n.n.n.n. |
Server IPV6 |
serveripv6 | The IPv6 128-bit address type of x:x:x:x:x:x:x:x following RFC 1924 of the server computer. |
Service |
service | The name of a Web service. |
Time |
time | Used to define the date and time of day that a given request must be honored. Two optional fields are StartTime and EndTime. If a request is received outside of that defined window, the request will not be processed. The Start Time and End Time fields each have the following format: dayOfWeek/dayOfMonth/month/year::hour:minute:second. For example, Thursday, the 11th of April, year 2007 at 1:03:45 PM is specified as: Thu/11/Apr/2007::13:03:45 Any field can use a wild card with the value *. For example, the 1st of each month is specified as */1. The dayofWeek values are Sun, Mon, Tue, Wed, Thu, Fri, Sat, and the dayOfMonth values range from 1-31. The month value is a non-numeric value that represents the twelve months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. The year value is comprised of the year's four digits. For example, 2007. The hour value is the hour of day in the 24-hour clock. For example, 8am is represented as ::8. The minute and second are integers ranging from 0-59. The forward slash (/) is used to separate date parameters, the double colon (::) is used to separate the date parameters, and the colon (:) is used to separate the time of day parameters. Note that it is the Boolean result of the entire rule in which the time operand is used that determines the routing action taken. |
URI |
uri | Uniform Resource Identifier |
Virtual Host |
virtualhost | Virtual host target of the request, used for configuring Web applications to a particular host name. |
Virtual Port |
numeric | Virtual port target of the request, used for configuring Web applications to a particular port. |
Virtual Portal |
virtualportal | Virtual portals are created within WebSphere Portal Server, and WebSphere Virtual Enterprise supports this operand for better integration with WebSphere Portal Server. The virtual portal is the request URL minus the context root for the WebSphere Portal application's Web module. If a given request matches the virtual portal defined, then the routing action defined for that rule is taken. |
The action's value attribute contains a set of arguments to indicate the filename and format of the log. To create multiple logs in the value attribute, delimit the arguments with a @. The first argument for the log action is the name of the log file, relative to the ODR 's logs directory. The following arguments are parameters to specify what information to place into the log. The data is shown in the order that the parameters are specified.
Parameter | Description |
---|---|
%a | Remote IP -address. |
%A | Local IP - address. |
%B | Bytes sent, excluding HTTP headers. |
%b | Bytes sent, excluding HTTP headers. In CLF format, that is, a '-' rather than a zero when no bytes are sent. |
%{FOOBAR}C | The contents of the cookie in the request sent to the server. |
%{FOOBAR}i | The contents of Foobar: header line(s) in the request sent to the server. |
% I | Bytes received, including request and headers, cannot be zero. |
%{FOOBAR}e | The contents of the debug argument ("-D") FOOBAR specified for the JVM of the ODR process. |
%h | Remote host. |
%H | The request protocol HTTP or HTTPS. |
%m | The request method. |
%{FOOBAR}o | The contents of Foobar, header line(s) in the reply. |
%O | Bytes sent, including headers; the number cannot be zero. |
%p | The canonical port of the server serving the request. |
%q | The query string, pepended with a ? if a query string exists. Otherwise, it is an empty string. |
%r | First line of request. |
%R | Response time in milliseconds. Combined time spent in ODR and application server. |
%s | Status, HTTP response code, that is, 503, 404, 200. |
%t | Time, in common log format time format, standard English format. |
%{format}t | The time, in the form given by format, which should be in strftime(3) format. Potentially localized. |
%T | The time taken to serve the request, in milliseconds. |
%U | The URL path requested, not including any query string. |
%v | The canonical ServerName of the server serving the request. |
%z | Destination IP-address. |
%Z | Destination server name (cell/node/server). |
The following example shows how to add a custom log rule to put all requests whose service time is longer than 2 seconds in the slow.log custom log, and include the application server to which the request was sent and the service time:
wsadmin.sh -f manageODR.py -lang jython insertCustomLogRule myNode02:odr1 1 "service.time > 2000" "slow.log %t %r %Z %T"The following example shows how to add a custom log rule to put all 503 responses in 503.log. The rule is added at position 2. If there is an existing rule at position 2, the new rule is inserted before the existing rule.
wsadmin.sh -f manageODR.py -lang jython insertCustomLogRule myNode02:odr1 2 "response.code = 503" "503.log %t %r %s