Formats¶

To create a format object, store the result of the format function in a variable. The function takes a table with two attributes: a mandatory string Format which defines the output format string for every event; and an optional number Interval defining the aggregation interval for summary logs.

-- A one-line-per-event format that just prints event timestamps.
myformat = format {
  Format = '%<cqtq>'
}
-- An aggregation/summary format that prints the last event timestamp from
-- the interval along with the total count of events in the same interval.
-- (Doing so every 30 seconds.)
mysummaryformat = format {
  Format = '%<LAST(cqtq)> %<COUNT(*)>',
  Interval = 30
}

You may define as many and as varied a collection of format objects as you desire.

Format Specification¶

Flexible enough to not only emulate the logging formats of most other proxy and HTTP servers, but also to provide even finer detail than many of them, the logging fields are very easy to use. Within the format string, logging fields are indicated by enclosing their name within angle brackets (< and >), preceded by a percent symbol (%). For example, returning to the altogether too simple format shown earlier, the following format string:

'%<cqtq>'

Defines a format in which nothing but the value of the logging field cqtq is interpolated for each event's entry in the log. We could include some literal characters in the log output by updating the format specification as so:

'Event received at %<cqtq>'

Because the string "Event received at " (including the trailing space) is just a bunch of characters, not enclosed in %<...>, it is repeated verbatim in the logging output.

Multiple logging fields may of course be used:

'%<cqtq> %<chi> %<cqhm> %<cqtx>'

Each logging field is separately enclosed in its own percent-brace set.

There are a small number of logging fields which extend this simple format, primarily those dealing with request and response headers. Instead of defining a separate logging field name for every single possible HTTP header (an impossible task, given that arbitrary vendor/application headers may be present in both requests and responses), there are instead single logging fields for each of the major stages of an event lifecycle that permit access to named headers, such as:

'%<{User-Agent}cqh>'

Which emits to the log the value of the client request's User-Agent HTTP header. Other stages of the event lifecycle have similar logging fields: pqh (proxy requests), ssh (origin server responses), and psh (proxy responses).

You will find a complete listing of the available fields in admin-logging-fields.

Aggregation Interval¶

These types of logs are described in more detail in admin-logging-type-summary.

Formats have no interval by default, and will generate event-based logs unless given one.

Filters¶

Filter objects are created by calling one of the following functions:

For both accept and wipe filters, the string passed defines a rule in the following format:

<field> <operator> <value>

Filter Fields¶

Filter Operators¶

Filter Values¶

Wiping Filters¶

Multiple query parameters may be listed, separated by spaces, though only the first occurence of each will be wiped from the query string if any individual parameter appears more than once in the URL.

Logs¶

There is no need to capture the return values of these functions. Which type of logging output you choose depends largely on how you intend to process the logs with other tools, and a discussion of the merits of each is covered elsewhere, in admin-logging-ascii-v-binary.

The following subsections cover the contents of the table which should be passed when creating your logging object. Only Filename and Format are required.

Enabling log rolling may be done globally in records.config, or on a per-log basis by passing appropriate values for the RollingEnabled key. The latter method may also be used to effect different rolling settings for individual logs. The numeric values that may be passed are the same as used by proxy.config.log.rolling_enabled. For convenience and readability, the following predefined variables may also be used in logging.config: