# example-logformat.conf
# Custom log format examples for web analytics
# Use these in your Apache or Nginx configuration to capture richer data
# in your server access logs — no application code required.


# ============================================================
# APACHE — LogFormat Directives
# ============================================================

# --- Standard Combined Log Format (the default on most servers) ---
# Fields: IP, ident, user, timestamp, request, status, bytes, referer, user-agent
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined

# --- Extended Analytics Format ---
# Adds: response time (microseconds), Accept-Language, session cookie
# %D  = time to serve the request in microseconds
# %{Header}i = value of the named request header
# %{Cookie}C = value of the named cookie
LogFormat "%h %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\" \"%{Accept-Language}i\" \"%{_session}C\"" analytics

# --- Client Hints Format ---
# Captures structured device/network data from Client Hints headers
# Requires the server to send: Accept-CH: Sec-CH-UA, Sec-CH-UA-Platform, Sec-CH-UA-Mobile, ECT, Downlink, RTT
LogFormat "%h %t \"%r\" %>s \"%{Sec-CH-UA}i\" \"%{Sec-CH-UA-Platform}i\" \"%{Sec-CH-UA-Mobile}i\" \"%{ECT}i\" \"%{Downlink}i\" \"%{RTT}i\"" hints

# --- Viewport Cookie Format ---
# Logs the viewport size stored in a cookie by client-side JavaScript
# Client JS:  document.cookie = 'vp=' + innerWidth + 'x' + innerHeight + ';path=/;max-age=1800;SameSite=Lax';
LogFormat "%h %t \"%r\" %>s \"%{vp}C\"" viewport-log

# --- Activate a custom format ---
# Place inside a <VirtualHost> block or in the main server config
# CustomLog /var/log/apache2/analytics.log analytics

# --- Format Directive Reference ---
# %h        Remote host (client IP address)
# %l        Remote logname (from identd, almost always "-")
# %u        Authenticated username (or "-")
# %t        Timestamp in standard format [dd/Mon/yyyy:HH:mm:ss +zone]
# %r        First line of request (e.g., "GET /page.html HTTP/1.1")
# %>s       Final HTTP status code (after internal redirects)
# %b        Response body size in bytes (or "-" if zero)
# %D        Time to serve the request in microseconds
# %T        Time to serve the request in seconds
# %{Foobar}i   Value of the "Foobar" request header
# %{Foobar}o   Value of the "Foobar" response header
# %{Foobar}C   Value of the "Foobar" cookie


# ============================================================
# NGINX — log_format Directives
# ============================================================

# --- Standard Combined Format (Nginx default) ---
log_format combined '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

# --- Extended Analytics Format ---
# Adds: Accept-Language, request time (seconds), X-Forwarded-For
# $request_time = response time in seconds with ms precision (e.g., 0.042)
# $http_x_forwarded_for = original client IP behind a reverse proxy
log_format analytics '$remote_addr - $remote_user [$time_local] '
                     '"$request" $status $body_bytes_sent '
                     '"$http_referer" "$http_user_agent" '
                     '"$http_accept_language" '
                     '$request_time '
                     '"$http_x_forwarded_for"';

# --- Client Hints Format ---
# Captures Client Hints headers (requires Accept-CH response header)
log_format hints '$remote_addr [$time_local] '
                 '"$request" $status '
                 '"$http_sec_ch_ua" '
                 '"$http_sec_ch_ua_platform" '
                 '"$http_sec_ch_ua_mobile" '
                 '"$http_ect" '
                 '"$http_downlink" '
                 '"$http_rtt"';

# --- Viewport Cookie Format ---
# Logs viewport cookie set by client-side JavaScript
# $cookie_vp = value of the "vp" cookie
log_format viewport '$remote_addr [$time_local] '
                    '"$request" $status '
                    '"$cookie_vp"';

# --- Activate a custom format ---
# Place inside a server {} block
# access_log /var/log/nginx/analytics.log analytics;

# --- Variable Reference ---
# $remote_addr          Client IP address
# $remote_user          Authenticated username (or "-")
# $time_local           Timestamp in standard format
# $request              Full request line (method + URI + protocol)
# $status               HTTP response status code
# $body_bytes_sent      Response body size in bytes
# $http_<header>        Value of any request header (lowercase, dashes become underscores)
# $request_time         Time to process request in seconds (with ms precision)
# $upstream_response_time   Time spent waiting for upstream (proxy) response
# $cookie_<name>        Value of the named cookie
# $arg_<name>           Value of the named query string parameter