Event Logging Parameters

• Information regarding basic connection management between the Web Gateway and InterSystems IRIS (Start and Close points for each connection).

• Transmission interrupts received from the browser.

• Cases where connections to InterSystems IRIS are forcefully closed (due to a lack of response from InterSystems IRIS or other errors where the connection cannot be recovered).

• Access violations in state-aware (preserve mode 1) sessions (For example, Invalid Session ID).

Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.

Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.

In addition to the information specified for previous levels, this level records the contents of data buffers received from, and sent to, InterSystems IRIS via the WebSocket protocol. All data framing (where applicable) is also recorded. Finally, further information about the nature of the WebSocket created is also recorded at initial connection time. For example:

• WebSocket Connection

• WebSocket Connection Accepted by InterSystems IRIS: WSClassProtocolVersion=2; SharedConnection=0; NoDataFraming=2; BinaryData=1;

Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.

• Headers to the data blocks sent to InterSystems IRIS.

• Request Data from the web server (except multipart attachments).

• Headers to the data blocks received from InterSystems IRIS.

Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.

Note: When this logging level is specified for an individual server, request headers are not logged, but response headers and other data will be.

• v9r: In addition to logging all HTTP requests, record all HTTP responses.

• v9a: Record all HTTP requests to http.log in the Web Gateway home directory.

• v9b: Record all HTTP requests on a per-session basis. Log files of the form http[session_id].log is created in the Web Gateway home directory, where session_id is the 10-Byte session ID.

• v9m: Log all multi-part posts in the Web Gateway home directory. The raw incoming HTTP request are recorded together with the individual components in both their encoded and decoded form.

Note: The forms V9, V9r, V9a, and V9b have no effect when specified for individual servers. These forms of logging can be enabled only at the default level.

Sessions: Record information about the management of session tokens:

• The point at which new session IDs are allocated.

• For existing sessions: an indication as to whether the session token was extracted from a cookie or the form/URL variable CSPCHD.

• For all requests: the final session ID transmitted to InterSystems IRIS.

Note: This logging option has no effect when specified for individual servers. This option can be enabled only at the default level.

Connections: Record information about connections made using the Kerberos Library (IRISCONNECT).

Include a log level of lowercase c to instruct the Web Gateway to record a complete audit of all IRISCONNECT functions called, together with the input parameters supplied and the result returned. For the sake of brevity, the content of the input and output buffers to and from InterSystems IRIS are not recorded at this level. Set a log level of uppercase C to record, in addition to the IRISCONNECT function calls, the contents of the input and output buffers.

In addition to the logging facilities provided by the Web Gateway, it is possible to instruct the IRISCONNECT library to generate a detailed trace recording its internal processes. To additionally request that a IRISCONNECT trace be generated, add a digit to the c directive to indicate the type of trace required.

For example, a log level of c3, in addition to the standard Gateway log entries, generates a level 3 IRISCONNECT trace. Valid IRISCONNECT trace levels are 1 to 6 and are defined as follows:

• 6 — errors

• 5 — warnings

• 4 — informational message

• 3 — output data

• 2 — input data

• 1 — normal events

Unlike the Web Gateway log levels, the IRISCONNECT trace is less verbose at the higher log levels. Log level 1, therefore, provides the most detailed trace file. The Web Gateway instructs the IRISCONNECT library to maintain its trace in a file called irisconnect.log located in the Web Gateway home directory. The security considerations and permissions for this file are the same as those for the Web Gateway Event Log.

Note: An IRISCONNECT trace can only be activated on a per-process basis, so it cannot be truly isolated to a server. Once configured, trace log generation is not triggered until a new SSL connection is attempted.

Transmission: Record the raw data buffers received by and dispatched by the Web Gateway. The format for this option is: t[x][y].

The value of x instructs the Web Gateway to record data buffers transmitted between the Web Gateway and InterSystems IRIS and the value of y instructs the Web Gateway to record data buffers transmitted between the Web Gateway and the client, via the hosting web server.

x and y can take the following values:

• 0: No transmission data to be recorded.

• 1: Record request data only.

• 2: Record response data only.

• 3: Record request and response data.

Using lowercase t results in the Web Gateway recording just the first 256 Bytes of transmitted data for each buffer. Using uppercase T results in the Web Gateway recording the full data buffer. All non-printable characters are recorded in their escaped form.Note: When this logging level is specified for an individual server, y options record response buffers sent to the client, but not incoming request buffers from the client.

Performance: Instructs Gateway to capture information to assess the performance of the CSP installation.

n is the number of seconds (total service time) below which data is not recorded for a request. For example, a directive of p records data for all requests, p2 records data for requests taking longer than 2 seconds to service.

The following information is recorded.

• Total time to service request: The total time spent in servicing the request (from the time it reaches the Web Gateway to the time at which the last Byte of response data leaves the Web Gateway environment.

• Obtain [NEW] connection to InterSystems IRIS: Time taken between the request reaching the Web Gateway and a connection to InterSystems IRIS being reserved for the purpose of servicing the request. The message recorded indicates if a new connection is created during this time (as opposed to an existing one being reused).

• Send request to InterSystems IRIS: Time taken between the first and last Byte of request data being read from the web server and dispatched to InterSystems IRIS.

• Processing request in InterSystems IRIS: Time taken between the last Byte of request data being dispatched to InterSystems IRIS and the first Byte of response data being received by the Web Gateway.

• Receive response from InterSystems IRIS: Time taken between the first and last Byte of response data being received from InterSystems IRIS and dispatched to the web server.

Provides the capability to conditionally activate verbose logging based on the results of the performance monitor. Useful in situations where you want to record further information about requests that take more than a certain time to process.

n is the optional lower time-to-service threshold (in seconds) for which performance data is recorded and v is the verbose log level required.

This mechanism applies to verbose Event Log and HTTP logging settings. A request to record error information, e is always applied to all requests regardless of whether or not they are recorded by the performance monitor.

For example: ep5(v9)This option records any errors encountered while processing requests for all requests (e). In addition, it records the HTTP request message (v9) but only for requests that take longer than 5 seconds to process (p5).

Gateway event logging is designed to have a minimal impact on performance and to occupy a small footprint in terms of system resources consumed. Therefore, the following limitations apply:

• Only one verbose log level can be specified per individual setting. In other words it is not possible to specify a v9 level for requests recorded by the performance monitor and a v2 level for all other requests. For example, if v2p5(v9) is specified then only the conditionally applied v9 level is honored.

• The Web Gateway configuration allows you to specify an Event Log level both globally and on a per server basis. When verbose logging is in force, some records are written before the target InterSystems IRIS server has been identified so, for best results, it is best to specify conditional logging at the global level under Default Parameters.

Provides detailed timing information as follows:

• Pre-processing of request: Time taken to identify the target InterSystems IRIS server; includes the initial handover from the web server and basic request processing to identify the server.

• Obtain [NEW] connection to InterSystems IRIS: Time taken to allocate a connection to the appropriate InterSystems IRIS server. Indicates whether a new connection is created (instead of an existing one reused).

• Format request: Time taken to parse and format the request message for transmission to InterSystems IRIS.

• Send request to InterSystems IRIS: Time taken between the first and last byte of request data read from the web server and dispatched to InterSystems IRIS.

• Processing request in InterSystems IRIS: Time taken between the last byte of request data dispatched to InterSystems IRIS and the first byte of response data received by the Web Gateway.

• Post-processing of response(b): When a content-length header is required, this reports the time taken for the dispatch of the response data back to the client via the web server.

• Post-processing of response(c): Time taken between the dispatch of the response and the Web Gateway being ready to read the response footer data from InterSystems IRIS. The footer data is part of the internal communication protocol between the Web Gateway and InterSystems IRIS and includes control information (For example: instructions to change the preserve setting for the session).

• Receive footers from InterSystems IRIS: Time taken to receive the response footer data from InterSystems IRIS.

• Post-processing of footers: Time taken to process footer data and respond to instructions received.

• Release connection to InterSystems IRIS: Time taken to release the active connection to InterSystems IRIS.

• Cleanup: Time taken to release resources used in servicing the request and return control back to the hosting web server.

On Windows, generates a memory dump if a crash occurs. This option is case insensitive.

On AIX, generates a core file using the gencore utility. This option is case insensitive.

On Linux or MacOS, this option is case sensitive. Specifying w generates a standard core dump using gcore. Specifying W dumps all memory mappings (including shared memory) into the core file by executing gcore -a.

On Unix systems, the following preconditions must hold:

• The gcore (Linux or MaxOS) or gencore (AIX) is present on the machine and is available through the PATH environment variable. On Linux and MacOS systems, the version of gcore must support the -a command line option.

• Web server worker processes need write permission to the directory where the Web Gateway modules are located. In default installations this directory is /opt/webgateway/bin.

• A non-root process needs permission to produce a core dump of another process running under the same user ID. On MacOS, System Integrity Protection must be disabled.

  On Linux, if the Yama security module is present (as on RHEL and Ubuntu systems), execute the following command to grant the required permission until the next reboot: echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope. To permanently grant this permission, create or edit the file /etc/sysctl.d/10–ptrace.conf. If there is a line starting with “kernel.yama.ptrace_scope”, change it to “kernel.yama.ptrace_scope = 0”. If no such line exists, add “kernel.yama.ptrace_scope = 0”, then execute sysctl —p.

  Note:

  For security reasons, it is recommended that such permission be granted only temporarily.