Version 2 log format

This table details version 2 of Fastly's custom log formats. All variables should be prefixed by a percent sign (%), as indicated in the table.

Format String

Description

%%

The percent sign.

%a

The client IP address of the request.

%A

The local IP address.

%B

The size of response in bytes, excluding HTTP headers.

%b

The size of response in bytes, excluding HTTP headers. In Common Log Format (CLF), that means a "-" rather than a 0 when no bytes are sent.

%{Foobar}C

The contents of cookie Foobar in the request sent to the server.

%D

The time taken to serve the request, in microseconds.

%{FOOBAR}e

The contents of the environment variable FOOBAR. Always returns NIL.

%f

The filename.

%h

The remote hostname.

%H

The request protocol.

%{Foobar}i

The contents of Foobar: header lines in the request sent to the server.

%I

Bytes received, including request and headers. Cannot be zero.

%k

The number of keepalive requests handled on this connection. Always returns 0.

%l

The remote logname (from identd, if supplied). This will return a dash unless mod_ident is present and IdentityCheck is set On. Always returns "-".

%m

The request method.

%{Foobar}n

The contents of note Foobar from another module. Always returns NIL.

%{Foobar}o

The contents of Foobar: header lines in the reply.

%O

Bytes sent, including headers. Cannot be zero.

%p

The canonical port of the server serving the request. Always returns 80.

%{format}p

The canonical port of the server serving the request. Valid formats are canonical, local, or remote. Returns 80 for HTTP requests and 443 for HTTPS requests.

%P

The process ID of the child that serviced the request. Always returns NIL.

%{format}P

The process ID or thread ID of the child that serviced the request. Valid formats are pid, tid, and hextid. Always returns NIL.

%q

The query string (prepended with a ? if a query string exists, otherwise an empty string).

%r

The first line of the request.

%R

The handler generating the response (if any).

%s

The status. For requests that got internally redirected, this is the status of the original request. Use %>s for the final status.

%t

The time the request was received, in Standard English format (e.g., 01/Jan/1970:00:00:00 -0700). The last number indicates the timezone offset from GMT.

%{format}t

The time, in the form given by format, which should be in strftime(3) format (potentially localized). If the format starts with begin: (the default) the time is taken at the beginning of the request processing. If it starts with end: it is the time when the log entry gets written, close to the end of the request processing. In addition to the formats supported by strftime(3), the following format tokens are supported: sec (number of seconds since the Epoch), msec (number of milliseconds since the Epoch), usec (number of microseconds since the Epoch), msec_frac (millisecond fraction), and usec_frac (microsecond fraction).

%T

The time taken to serve the request, in seconds.

%u

The remote user if the request was authenticated. May be bogus if return status (%s) is 401 (unauthorized). Always returns "-".

%U

The URL path requested, not including any query string.

%v

The domain name of the request. Equal to %{req.http.host}V.

%V

The same as %v.

%{vcl}V

The literal VCL to include without quoting. This can be used to write VCL variables to your logs (e.g., %{client.geo.country_code}V or %{tls.client.cipher}V). This %-directive is a Fastly extension and is not found in Apache.

%X

The connection status when response is completed. Statuses include X (connection aborted before the response completed), + (connection may be kept alive after the response is sent), and - (connection will be closed after the response is sent).

Version 1 log format

This table details version 1 of Fastly's custom log formats. All variables should be prefixed by a percent sign (%), as indicated in the table.

Format String

Description

%b

The content size of the response, calculated using the Content-Length header rather than actually checking the length of the response (and may therefore be wrong).

%h

The remote IP address.

%l

The remote log name. Always returns the hardcoded value "-".

%r

The HTTP verb and request path (e.g., GET /index.html). Unlike Apache and version 2 log formats, the protocol version is not included.

%>s

The status of the last request.

%t

The time the request was received, in Unix ctime format (e.g., Thu, 01 Jan 1970 00:00:00 GMT) rather than Apache's Standard English format (e.g., 01/Jan/1970:00:00:00 -0700).

%u

The remote user. Always returns the hardcoded value "-".

Upgrading endpoints to use version 2 log format

WARNING: Upgrading is a permanent change. Logging objects using version 2 formatting cannot be downgraded to version 1.

Follow these instructions to upgrade a logging endpoint to the version 2 custom log format:

Log in to the Fastly web interface and click the Configure link.

From the service menu, select the appropriate service.

Click the Configuration button and then select Clone active. The Domains page appears.

Click the Logging link. The Logging endpoints page appears. If you have any logging endpoints using the version 1 custom log format, a message appears indicating that they can be updated.

Click the name of a logging endpoint to edit it. The Edit this endpoint page appears.

Click the Convert to Log Format Version 2 button. The Convert to log format version 2 window appears.

Select an output format:

Use compatible output is the recommended setting. This setting won't modify your timestamp format string, but your logs will be formatted differently. The new format will be compatible with Apache's log format.

Maintain legacy output uses the version 2 parser, but the generated log string will be the same. This means that any instances of %t need to be turned into %{now}V, any instances of %r need to be turned into %{req.url}V, and any instances of %b need to be turned into %{resp.http.Content-Length}V.

Click the Select button. The Edit this endpoint page appears.

Click the Update button to upgrade the logging endpoint to the version 2 custom log format.

Click the Activate button to deploy your configuration changes.

Using the API to upgrade

To upgrade a logging endpoint using the Fastly API, either clone the active version of the service you need upgraded or choose a version of the service that is unlocked and not active, then run the following command on that in development version:

Keep in mind that the format_version field is a per-object field. Updating it on one logging object will not change it on any other objects. For example, to upgrade a Google Cloud Storage endpoint the cURL command would look something like this if the endpoint was named "GCS Test":

The format_version field displays either a 1 or a 2 as appropriate for the custom log format being used.

Advantages of using the version 2 custom log format

The key advantages of using the version 2 custom log format include the following:

Log lines are generated in vcl_log instead of vcl_deliver to allow us to accurately set the various size variables because vcl_log is run after the object has been delivered to the browser.

The %t time directive is compatible with Apache log format. In version 1, we used a non-standard time format.

The %r "first line of request" directive is compatible with Apache log format. In version 1, we incorrectly left off the protocol.

When using the %b directive, which represents the size of a response in bytes, excluding HTTP headers is more accurate. In version 1, we used the reported Content-Length from the origin, which could be inaccurate (especially with ESI).

We've added all Apache logging directives that make sense. In version 1, we used a smaller subset.

Making version 2 logs look like version 1

The default logging format for version 1 is as follows:

%h %l %u %t %r %>s

Most of the directives in version 2 are exactly the same - only %t and %r are different. After you upgrade to version 2 log formats, you can recreate the appearance of version 1 logs using the new %{...}V directive, which allows you to specifically include VCL in logging directives:

%h %l %u %{now}V %{req.request}V %{req.url}V %>s

In addition, if you are using the %b directive in version 1, then you can use this directive instead: