> ## Documentation Index
> Fetch the complete documentation index at: https://gcore-doc-1894.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Logs uploader
Logs uploader automatically exports CDN resource logs to configured storage destinations in near real time, providing continuous visibility into request activity and cache behavior. Exported logs can also contain requests processed by mid-tier cache servers when [Origin shielding](/cdn/cdn-resource-options/general/enable-and-configure-origin-shielding) is enabled and the policy includes these logs.
Logs uploader must be enabled for the account before the configuration UI is available. Contact [Gcore Support](mailto:support@gcore.com) or use **Contact support** on the Logs uploader page in the [Gcore Customer Portal](https://portal.gcore.com).
## Logs uploader configuration
In the Customer Portal, open **CDN**, click **Logs**, and select **Logs uploader**.
Control which fields are exported, how frequently the logs are delivered, and which storage service they are sent to. Supported destinations include Gcore Object Storage, S3-compatible storage, FTP and SFTP servers, and HTTP(S) endpoints. Use these exports for observability, analytics, or compliance workflows while managing data volume and processing requirements.
The **Logs uploader** screen has three tabs:
* **Configurations** — link policies and targets to deliver logs
* **Policies** — set export rules and schedules
* **Targets** — connect upload destinations
A configuration requires an existing policy and target.
### First-time setup
A configuration links a policy and a target. Create them in this order before creating the configuration.
Go to the **Policies** tab and click **Add policy**. Select the log fields, set the time interval, and configure the file name format and size limit.
Go to the **Targets** tab and click **Add target**. Select a destination type, such as S3, FTP, SFTP, or HTTP(S), and enter the connection details. A green `Authentication complete` status confirms the target is reachable.
Go to the **Configurations** tab and click **Add configuration**. Link the policy and target created in the previous steps, then click **Add configuration** to activate.
Generate CDN traffic to a resource covered by the configuration. After the configured time interval has elapsed, check the destination for a new log file. Confirm that the file contains request entries with the expected fields.
Select the **Configurations** tab to view a table of configurations:
* Configuration **ID**\
Click the column header to sort the table by configuration IDs.
* **Configuration** name
* Click the column header to sort the table by configuration names.
* Click a configuration name to edit the configuration.
Use the search box at the top of the table to filter configurations by name or ID.
* **Policy**\
Click a policy name to edit the linked policy.
* **Target**\
Click a target name to edit the linked target.
* **Status**\
Linked target status is displayed in the **Status** column. To re-run the authentication check, click (refresh) at the end of the status message.
* **More options**\
Click **⋯** (more options) in the last column to **Edit**, **Disable**, or **Delete** the configuration in that row.
* **Add configuration**\
Click **Add configuration** (top right) to create a new configuration.
Navigate to **Logs uploader**, select the **Configurations** tab, and click **Add configuration**.
The **Enable configuration** switch appears at the top of the **Add configuration** window; to disable the configuration, toggle the switch to the left.
Select the resources for this configuration:
For all resources, including newly created:
1. Enter a **Name** for the configuration.
For the specified CDN resources only:
1. Enter a **Name** for the configuration.
2. Select the **CDN resources** to link from the drop-down list.
Use the search box at the top of the drop-down list to filter resources by CNAME and ID.
1. Select a **Policy** to link from the drop-down list.
2. Select a **Target** to link from the drop-down list.
Click **Add configuration** again to finish and return to the Logs uploader. The new configuration appears in the table on the **Configurations** tab.
Configurations with correctly configured targets show `Authentication complete` in the **Status** column; to re-run the authentication check, click (refresh) at the end of the status message.
1. Navigate to **Logs uploader** and select the **Configurations** tab.
2. Click the configuration name in the **Configurations** column, or click **⋯** (more options) at the end of that row and select **Edit**.
The **Enable configuration** switch appears at the top of the **Edit configuration** window; to disable the configuration, toggle the switch to the left.
Select the resources for this configuration:
For all resources, including newly created:
1. Edit the **Name** field.
For the specified CDN resources only:
1. Edit the **Name** field.
2. Select the **CDN resources** to link from the drop-down list.
Use the search box at the top of the drop-down list to filter the list by CNAME and ID.
1. Select a **Policy** to link from the drop-down list.
2. Select a **Target** to link from the drop-down list.
Click **Save changes** (top right) to return to the Logs uploader.
Configurations with correctly configured targets show `Authentication complete` in the **Status** column; to re-run the authentication check, click (refresh) at the end of the status message.
Navigate to **Logs uploader** and select the **Configurations** tab.
In the row with the configuration name, click **⋯** (more options) in the last column and select **Enable**, **Disable**, or **Delete**.
A configuration can also be enabled or disabled using the **Enable configuration** switch in **Edit configuration** or **Add configuration** windows.
Select the **Policies** tab for a table of policies:
* Policy **ID**\
Click the column header to order the table by policy IDs.
* **Policy** name
* Click the column header to order the table by policy names.
* Click a policy name to edit the policy.
Use the search box at the top of the table to filter policies by name or ID.
* **Configuration**\
Click a configuration name to edit the linked configuration.
Click **Select configuration** at the top of the table, then select one or more linked configurations from the drop-down list to filter the policies table. Use the search box at the top of this drop-down list to filter list results by configuration name or ID.
* **More options**\
Click **⋯** (more options) in the last column to **Edit** or **Delete** the policy in that row.
* **Add policy**\
Click **Add policy** (top right) to create a new policy.
Navigate to **Logs uploader**, select the **Policies** tab, and click **Add policy**.
1. Enter a **Name** for the policy.
2. Clear the **Include empty logs** checkbox to exclude empty logs.
3. Select **Include logs from origin shielding** to receive these logs.
This option is only available if Origin shielding is [enabled](/cdn/cdn-resource-options/general/enable-and-configure-origin-shielding) for the account.
Use the multi-select picker to select the **Log fields** to include:
1. To remove a log field, click **✕** (close) on the chip with the field label. To remove all fields, click **Clear** at the bottom right of the picker field.
2. To add a log field, click in the empty area of the picker field and select a log field to add from the drop-down list.
Enter one or more characters from the field label to filter the list.
1. To reorder fields, click **Edit order** at the bottom left to open the reorder panel, drag the **⋮⋮** handles to rearrange the fields in the list, and click **Apply changes**.
2. Change the **Delimiter** and the **Separator**, if needed.
3. Change or customize the log **File name format** template, if needed.
4. Change the logging **Time interval**, if needed.
5. Set the **Log file size limit**.
The **Log file size limit** applies before compression. The compressed file delivered to the endpoint may be up to 99% smaller.
Click **Add policy** again to finish and return to the Logs uploader. The new policy appears in the table on the **Policies** tab.
1. Navigate to **Logs uploader** and select the **Policies** tab.
2. Click the policy name in the **Policy** column, or click **⋯** (more options) at the end of that row and select **Edit**.
1. Edit the **Name** field.
2. Select the **Include empty logs** checkbox to receive empty logs.
3. Select **Include logs from origin shielding** to receive these logs.
This option is only available if Origin shielding is [enabled](/cdn/cdn-resource-options/general/enable-and-configure-origin-shielding) for the account.
Use the multi-select picker to edit the **Log fields** to include:
1. To remove a log field, click **✕** (close) on the chip with the field label. To remove all fields, click **Clear** at the bottom right of the picker field.
2. To add a log field, click in the empty area of the picker field and select a log field to add from the drop-down list.
Enter one or more characters from the field label to filter the list.
1. To reorder fields, click **Edit order** at the bottom left to open the reorder panel, drag the **⋮⋮** handles to rearrange the fields in the list, and click **Apply changes**.
2. Edit the **Delimiter** and the **Separator**.
3. Edit or customize the log **File name format** template.
4. Edit the logging **Time interval**.
5. Edit the **Log file size limit**.
The **Log file size limit** applies before compression. The compressed file delivered to the endpoint may be up to 99% smaller.
Click **Save changes** (top right) to return to the **Policies** tab.
Navigate to **Logs uploader** and select the **Policies** tab.
In the row with the policy name, click **⋯** (more options) in the last column and select **Delete**.
Select the **Targets** tab to view a table of targets:
* Target **ID**\
Click the column header to sort the table by target IDs.
* **Target** name
* Click the column header to sort the table by target names.
* Click a target name to edit configuration or connection details.
Use the search box at the top of the table to filter targets by name or ID.
* **Configuration**
* Click a configuration name to edit the linked configuration.
Click **Select configuration** at the top of the table, then select one or more linked configurations from the drop-down list to filter the targets table. Use the search box at the top of this drop-down list to filter list results by configuration name or ID.
* **Status**\
Target authentication status is displayed in the **Status** column. To re-run the authentication check, click (refresh) at the end of the status message.
* **More options**\
Click **⋯** (more options) in the last column to **Edit** or **Delete** the target in that row.
* **Add target**\
Click **Add target** (top right) to connect a new target.
1. Navigate to **Logs uploader**, select the **Targets** tab, and click **Add target**.
2. Enter a **Name** for the target.
Select and configure a destination or delivery protocol and connection details for log export:
[Gcore Object Storage](https://gcore.com/storage)
1. Select **HTTP** or **HTTPS** protocol and specify the **Endpoint** for the storage target.
2. Enter the **Access key ID** and the **Secret Access Key**.
3. Enter the storage **region** (location) and the name of an existing **bucket**.
4. Optionally, specify an existing **folder** within the bucket for receiving the logs.
Complete connection details are displayed when the storage is [created](/storage/create-an-s3-or-sftp-storage#object-storage).
Storage endpoint (hostname) and region (location) can be viewed and new keys generated by clicking **⋯** (more options) in the **Actions** column of the [Object Storages](/storage/create-an-s3-or-sftp-storage#object-storage) table.
[Alibaba Cloud OSS](https://www.alibabacloud.com/en/product/object-storage-service?_p_lc=1)
1. Enter the **Access Key ID** and the **Secret Access Key** for the storage target.
2. Enter the **cloud region** and the name of an existing **bucket**.
3. Optionally, specify an existing folder within the bucket for receiving the logs.
Alibaba documents [OSS AccessKey](https://www.alibabacloud.com/help/en/sls/developer-reference/access-key) pair creation.
Generic S3-compatible object storage
1. Select **HTTP** or **HTTPS** protocol and specify the **Endpoint** for the storage target.
2. Enter the **Access Key ID** and the **Secret Access Key**, provided by the storage provider.
3. Enter the storage **region** and the name of an existing **bucket**.
4. Optionally, specify an existing folder within the bucket for receiving the logs.
FTP target
FTP transmits credentials and log data without transport encryption. Use SFTP or HTTPS targets when logs contain sensitive data such as IP addresses, cookies, or request URLs.
1. Enter the **Hostname** for the storage target.
2. Enter the **Login** and **Password** for the storage.
3. Optionally, specify an existing prepend (destination) directory for receiving the logs.
SFTP target
1. Enter the **Hostname** and **Login** for the storage target.
2. Select an **Authentication method**:
* Password — enter the **Password**.
* Private key — enter the **Private Key** and **Passphrase**.
3. Optionally, specify an existing prepend (destination) folder for receiving the logs.
HTTP(S) target
Plain HTTP transmits log data without transport encryption. Use HTTPS to protect log content in transit, especially when logs contain IP addresses, cookies, or request URLs.
1. Select **POST** or **PUT** HTTP method.
2. Select **HTTP** or **HTTPS** protocol and specify the **Endpoint** for the storage target.
3. Add a custom header if needed; click **Add header** for additional key–value pairs.
4. Turn on the **Authentication** switch to enable token-based authentication using HTTP headers.
5. Turn on the **Use compression** switch to enable JSON log file compression.
Use compression to reduce log file size by up to 99%.
Click **Add target** again to finish configuration and return to the Logs uploader. The new target appears in the table on the **Targets** tab.
Correctly configured targets show `Authentication complete` in the **Status** column; to re-run the authentication check, click (refresh) at the end of the status message.
1. Navigate to **Logs uploader** and select the **Targets** tab.
2. Click the target name in the **Target** column, or click **⋯** (more options) at the end of that row and select **Edit**.
Target authentication status appears at the top of the **Edit target** window. To re-run the authentication check, click (refresh) next to the status message.
Edit the **Name** field, then select or configure the destination or delivery protocol and connection details for log export:
[Gcore Object Storage](https://gcore.com/storage)
1. Select **HTTP** or **HTTPS** protocol and specify the **Endpoint** for the storage target.
2. Enter the **Access key ID** and the **Secret Access Key**.
3. Enter the storage **region** (location) and the name of an existing **bucket**.
4. Optionally, specify an existing **folder** within the bucket for receiving the logs.
Complete connection details are displayed when the storage is [created](/storage/create-an-s3-or-sftp-storage#object-storage).
Storage endpoint (hostname) and region (location) can be viewed and new keys generated by clicking **⋯** (more options) in the **Actions** column of the [Object Storages](/storage/create-an-s3-or-sftp-storage#object-storage) table.
[Alibaba Cloud OSS](https://www.alibabacloud.com/en/product/object-storage-service?_p_lc=1)
1. Enter the **Access Key ID** and the **Secret Access Key** for the storage target.
2. Enter the **cloud region** and the name of an existing **bucket**.
3. Optionally, specify an existing folder within the bucket for receiving the logs.
Alibaba documents [OSS AccessKey](https://www.alibabacloud.com/help/en/sls/developer-reference/access-key) pair creation.
Generic S3-compatible object storage
1. Select **HTTP** or **HTTPS** protocol and specify the **Endpoint** for the storage target.
2. Enter the **Access Key ID** and the **Secret Access Key**, provided by the storage provider.
3. Enter the storage **region** and the name of an existing **bucket**.
4. Optionally, specify an existing folder within the bucket for receiving the logs.
FTP target
FTP transmits credentials and log data without transport encryption. Use SFTP or HTTPS targets when logs contain sensitive data such as IP addresses, cookies, or request URLs.
1. Enter the **Hostname** for the storage target.
2. Enter the **Login** and **Password** for the storage.
3. Optionally, specify an existing prepend (destination) directory for receiving the logs.
SFTP target
1. Enter the **Hostname** and **Login** for the storage target.
2. Select an **Authentication method**:
* Password — enter the **Password**.
* Private key — enter the **Private Key** and **Passphrase**.
3. Optionally, specify an existing prepend (destination) folder for receiving the logs.
HTTP(S) target
Plain HTTP transmits log data without transport encryption. Use HTTPS to protect log content in transit, especially when logs contain IP addresses, cookies, or request URLs.
1. Select **POST** or **PUT** HTTP method.
2. Select **HTTP** or **HTTPS** protocol and specify the **Endpoint** for the storage target.
3. Add a custom header if needed; click **Add header** for additional key–value pairs.
4. Turn on the **Authentication** switch to enable token-based authentication using HTTP headers.
5. Turn on the **Use compression** switch to enable JSON log file compression.
Use compression to reduce log file size by up to 99%.
Click **Save changes** (top right) to return to the Logs uploader **Targets** tab.
Correctly configured targets show `Authentication complete` in the **Status** column; to re-run the authentication check, click (refresh) at the end of the status message.
Navigate to **Logs uploader** and select the **Targets** tab.
In the row with the target name, click **⋯** (more options) in the last column and select **Delete**.
## Log schema and field definitions
The exported log schema includes standard CDN request fields, internal status codes, and format examples.
The format below is a non-exhaustive example. It does not include every available field — for instance, `$timestamp_request_start`, `$masked_remote_addr`, `$query_string`, and `$quic` are in the field table but not shown here. The actual log output depends on which fields are selected, their order, and the delimiter and separator configured in the policy.
New fields may appear at the end of the line. When fields are added to logs, an email notification is sent about the update.
```text theme={null}
"$remote_addr" "-" "$remote_user" "[$time_local]" "$request" "$status"
"$body_bytes_sent" "$http_referer" "$http_user_agent" "$bytes_sent"
"$edgename" "$scheme" "$host" "$request_time"
"$upstream_response_time" "$request_length" "$http_range" "[$responding_node]"
"$upstream_cache_status" "$upstream_response_length" "$upstream_addr"
"$gcdn_api_client_id" "$gcdn_api_resource_id" "$uid_got" "$uid_set"
"$geoip_country_code" "$geoip_city" "$shield_type" "$server_addr" "$server_port"
"$upstream_status" "-" "$upstream_connect_time" "$upstream_header_time"
"$shard_addr" "$geoip2_data_asnumber" "$connection" "$connection_requests"
"$http_traceparent" "$http_x_forwarded_proto" "$gcdn_internal_status_code" "$ssl_cipher"
"$ssl_session_id" "$ssl_session_reused" "$sent_http_content_type" "$tcpinfo_rtt"
"$server_country_code" "$gcdn_tcpinfo_snd_cwnd" "$gcdn_tcpinfo_total_retrans" "$gcdn_rule_id"
```
The following table contains a complete list of available log fields. Fields labeled “internal system variable” relate to the internal CDN system and can be ignored for most analytics use cases.
Other fields can help with traffic analysis or statistics.
The `$timestamp` variable always produces an empty value. Use `[$time_local]` for a Common Log Format timestamp or `$timestamp_request_start` for request-start time in Unix epoch milliseconds. No client port field is available.
| Field | Log value example | Description |
| :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$remote_addr` | `203.0.113.45` | User’s IP address |
| `$masked_remote_addr` | `4.d18b5cafa3d1c016d8194583f593a87e89271e6dc8e2ba44f851fdd5a8be1ccb` | Privacy-preserving alternative to `$remote_addr`. Replaces the client IP address with a deterministic SHA-256 hash. Output format: `.` |
| `$remote_user`
(internal system variable) | `-` | Username used in Basic authentication |
| `[$time_local]` | `[26/Apr/2019:09:47:40 +0000]` | Local time in Common Log Format |
| `$timestamp_request_start` | `1772707791454` | Request start time as Unix epoch in milliseconds |
| `$request` | `GET /ContentCommon/images/image.png HTTP/1.1` | HTTP method, requested file path, and HTTP version |
| `$status` | `200` | Response status code from a CDN server |
| `$body_bytes_sent` | `1514283` | Number of bytes sent to a user, excluding the response header size |
| `$http_referer` | `https://example.com/videos/10` | Value of the Referer request header, which usually identifies the page that initiated the request |
| `$http_user_agent` | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.116 YaBrowser/16.10.0.2309 Safari/537.36` | User agent that was used to send a request (browser or other application) |
| `$bytes_sent` | `1514848` | Number of bytes sent to a user |
| `$edgename` | `[dh-up-gc18]` | CDN server that forwarded the requested file |
| `$scheme` | `https` | Protocol (HTTP or HTTPS) of a request |
| `$host` | `cdn.example.com` | Requested hostname of a CDN resource |
| `$cname`
(internal system variable) | `cdn.example.com` | Similar to the `$host` field, but derived from internal systems rather than the incoming HTTP request |
| `$gcdn_vhost`
(internal system variable) | `cdn.example.com[_cache_sharded]` | The vhost value as used internally in CDN |
| `$request_time` | `1.500` | Request processing time in seconds (accurate to milliseconds); time elapsed between the first bytes of a request being processed and logging after the last bytes were sent to a user |
| `$upstream_response_time` | `0.445` | Number of seconds (accurate to milliseconds) it took to receive a response from an origin. In case of multiple responses, commas and colons are used |
| `$request_length` | `157` | Request length (including request line, header, and request body) |
| `$http_range` | `bytes=0-1901653` | File fragment size in a Range request |
| `[$responding_node]` | `dh` | Responding data center |
| `$upstream_cache_status` | `MISS` | Status of a requested file in CDN cache:
`HIT`: response served from the CDN cache.
`STALE`: outdated response that failed to update (origin not responding or responding incorrectly).
`UPDATING`: outdated response still updating from a previous request.
`REVALIDATED`: response matching one on an origin (based on the `proxy_cache_revalidate` directive).
`EXPIRED`: response that has expired in cache but still matches one on an origin; a request was sent to re-cache it.
`MISS`: response served directly from an origin rather than from cache.
`BYPASS`: response for the first file request after clearing the cache (the first request from each CDN server results in `BYPASS`; subsequent requests on that server result in `HIT`) |
| `$upstream_response_length` | `10485760` | Response length from an origin in bytes. In case of multiple responses, commas and colons are used |
| `$upstream_addr` | `192.0.2.1:80` | Origin’s IP address and port |
| `$gcdn_api_client_id`
(internal system variable) | `123` | Account ID in the Gcore system |
| `$gcdn_api_resource_id`
(internal system variable) | `01` | CDN resource ID in the Gcore system |
| `$uid_got`
(internal system variable) | `-` | Cookie name and received user ID |
| `$uid_set`
(internal system variable) | `-` | Cookie name and provided user ID |
| `$geoip_country_code` | `KZ` | User’s ISO 3166-1 alpha-2 country code |
| `$geoip_city` | `-` | User’s city code |
| `$shield_type`
(internal system variable) | `shield_no` | Indicates whether [Origin Shielding](/cdn/cdn-resource-options/general/enable-and-configure-origin-shielding) is enabled:
`shield_old` – enabled
`shield_no` – disabled |
| `$server_addr`
(internal system variable) / `real_server_addr` | `198.51.100.1` | IP address of an Anycast zone or CDN server |
| `$server_port`
(internal system variable) | `80` | Requested port |
| `$upstream_status` | `206` | Origin response code |
| `$upstream_connect_time` | `0.000` | Number of seconds (accurate to milliseconds) it took to access an origin server |
| `$upstream_header_time` | `0.200` | Number of seconds (accurate to milliseconds) it took to receive a response header from an origin server |
| `$shard_addr`
(internal system variable) | `198.51.100.2` | IP address of a CDN server that was first to accept a request if the Cache Sharding feature is enabled |
| `$geoip2_data_asnumber` | `asnumber` | Number of an autonomous system that sent a request |
| `$connection`
(internal system variable) | `2897494295` | Connection serial number |
| `$connection_requests`
(internal system variable) | `1` | Current number of requests made through a connection |
| `$http_traceparent`
(internal system variable) | `00-d5fe1dc9035165ce36952daf29686b6c-14330be33197dd1a-01` | Incoming client `traceparent` request header. If the client omits the header, the field contains `-`; if the value is invalid, the field preserves that value. The CDN-generated replacement is not stored here. See [Traceparent header for troubleshooting](/cdn/troubleshooting/traceparent-header-for-troubleshooting). |
| `$http_x_forwarded_proto` | `-` | Initial protocol of an incoming request (HTTP or HTTPS) |
| `$gcdn_internal_status_code`
(internal system variable) | `-` | Initial status code. Possible values are `-` or one of the internal codes listed below |
| `$ssl_cipher`
(internal system variable) | `ECDHE-RSA-AES256-GCM-SHA384` | Cipher name used for an established SSL connection |
| `$ssl_session_id`
(internal system variable) | `28a4184139cb43cdc79006cf2d1a4ac93bdc****` | Session ID of an established SSL connection |
| `$ssl_session_reused`
(internal system variable) | `r` | Shows whether a session was reused (`r`) or not (`.`) |
| `$sent_http_content_type` | `application/json` | Value of the `Content-Type` HTTP header, indicating the MIME type of a transmitted file |
| `$tcpinfo_rtt` | `21` | Average time (latency) it takes to transfer a packet to/from a server. The unit of time is microseconds |
| `$server_country_code` | `PL` | Server’s ISO 3166-1 alpha-2 country code |
| `$gcdn_tcpinfo_snd_cwnd` | `45` | Size of the TCP Congestion window, i.e., the maximum number of TCP segments that the connection can send before an acknowledgment is required |
| `$gcdn_tcpinfo_total_retrans` | `10` | Total number of retransmitted packets over the life of the connection |
| `$gcdn_rule_id` | `100700` | Initial rule ID (beta). Possible values are: `-`, or `100700` |
| `$query_string` | `id=123&sort=asc&filter=active` | Contains the raw query parameters from the request URI |
| `$timestamp`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$ip`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$country`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$media_type`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$size`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$duration`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$session_id`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$domain`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$name`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$edge`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$code`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$region`
(internal system variable) | `-` | Internal system variable; always produces an empty value |
| `$http_x_forwarded_for` | `203.0.113.45, 198.51.100.17` | Contains the value of the X-Forwarded-For HTTP request header as sent by the client or added by upstream proxies/load balancers |
| `$http_cookie` | `session_id=abc123; theme=dark; csrftoken=9f8e7d` | Contains the raw value of the Cookie HTTP request header sent by the client |
| `$request_method` | `GET` | Contains the HTTP method used by the client for the request |
| `$request_uri_path` | `/api/v1/users` | Represents the path portion of the request URI, without any query string parameters |
| `$sent_http_cache_control` | `max-age=3600, public` | Contains the value of the Cache-Control HTTP response header as sent by NGINX to the client. It reflects the caching directives applied to the response, which control how browsers, proxies, and CDNs may cache and reuse the content |
| `$sent_http_content_length` | `53214` | Contains the value of the Content-Length HTTP response header as sent by NGINX to the client. It represents the size of the response body in bytes, as declared in the response headers |
| `$server_protocol` | `HTTP/1.1` | Contains the protocol version used by NGINX to communicate |
| `$upstream_http_content_length` | `1048576` | Contains the value of the Content-Length HTTP response header received from the upstream server |
| `$request_uri` | `/api/v1/users?id=42&sort=asc` | Contains the original request URI as sent by the client, including the path and the query string |
| `$fastedge_field1`
(internal system variable) | | Used for passing additional context from FastEdge into raw logs |
| `$http_last_modified` | `Wed, 21 Oct 2015 07:28:00 GMT` | Value of the Last-Modified request header sent by the client |
| `$http_accept` | `text/html,application/xhtml+xml` | Value of the Accept request header indicating acceptable response content types |
| `$http_age` | `3600` | Value of the Age request header, typically used by caches to indicate object age in seconds |
| `$http_head_size` | `512` | Size (in bytes) of the HTTP request headers received from the client |
| `$http_return_head_size` | `430` | Size (in bytes) of the HTTP response headers returned to the client |
| `$sent_http_content_range` | `bytes 0-1023/4096` | Value of the Content-Range response header sent to the client |
| `$upstream_http_location` | `/redirect/path` | Value of the Location response header received from the upstream server (commonly for redirects) |
| `$http_via` | `1.1 proxy.example.com` | Value of the Via request header, listing the proxies the request passed through |
| `$quic` | `H3` | QUIC protocol version negotiated for the connection. Possible values: `-`, or `H3` |
Internal status codes identify the CDN rule or feature that generated a response.
| Reason | HTTP code | Internal code | Comment |
| :------------------------------------------ | :-------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Country ACL | 403 | 1001 | |
| Referer ACL | 403 | 1002 | |
| IP ACL | 403 | 1003 | |
| User-Agent ACL | 403 | 1004 | |
| Secure Token | 403 | 1005 | If the requested link passes the authenticity check, the `$secure_link` variable is set to the link extracted from the request URI. Otherwise, `$secure_link` is set to an empty string |
| Secure Token | 410 | 1006 | If the link has a limited lifetime and the time has expired, the `$secure_link` variable is set to `"0"` |
| WAF | 403 | 1007 | Request blocked by WAF |
| Bot challenge / Testcookie | 307 | 1008 | Redirection sent by bot challenge (testcookie) |
| Blocklist | 403 | 1009 | Request blocked by bot protection blocklist |
| HTTP method | 405 | 1200 | Returned when `AllowedHttpMethods` is enabled and the request method is not in the allowed list |
| Streaming disabled (`.ts` or `.m3u8` files) | 402 | 1201 | Streaming feature disabled for the client |
| LE validation /.well-known/acme-challenge/ | 404 | 1202 | Returned when `http_user_agent` is not `cert-manager-challenges`, `acme.zerossl.com`, `Cpanel-HTTP-Client`, `Buypass validation client`, `Google-Certificates-Bridge`, `vercel-fetch`, `win-acme`, `Typhoeus`, or `Go-http-client` |
| Shield requestor header | 403 | 1203 | Unauthorized request to the shield |
| Force Return | ANY | 1204 | Response generated by the Force Return status code option |
For HTTP(S) targets, Logs uploader sends a JSON request payload whose `v` field identifies the schema version — for instance, `"v":"10"`. This metadata belongs to the JSON payload rather than the selectable CDN log fields, so it does not appear in the log format example or field table.
The version increments when fields are added, renamed, or removed. New fields are added in a backward-compatible way where possible, so most schema changes do not require parser updates. Breaking changes are announced in advance through standard CDN update notifications. Pin downstream parsers (SIEM, ETL) to a known version and check `v` to detect schema changes.
## WAAP log fields
When a CDN resource has [WAAP](/waap) enabled, the Logs uploader automatically appends WAAP security event fields to each request log line, alongside the CDN fields described above. Each request produces a single merged log entry, so CDN access data and the matching WAAP security verdict arrive correlated on the same delivery channel as existing CDN logs — no separate file and no extra configuration.
WAAP fields are added only for resources that have WAAP enabled and use the current edge protection architecture. For resources without WAAP, the existing CDN log line is unchanged.
DDoS protection logs are not exported through the Logs uploader. Only per-request WAAP security events are included. DDoS attack analytics remain available through the WAAP API and dashboard.
The following fields are appended to each request log line when WAAP is enabled on the resource.
| Field | Log value example | Description |
| :------------------------------ | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$waap_id` | `7f3c1e92-...` | Unique WAAP request identifier. Correlate a log line with the [WAAP Request Details](/api-reference/waap/analytics/get-request-details) API |
| `$waap_decision` | `blocked` | Final security decision computed by WAAP at the edge. See **Decision and optional action values** below for the full value list and semantics |
| `$waap_optional_action` | `captcha` | Additional action that was returned to the client alongside the decision (CAPTCHA or non-interactive challenge). See **Decision and optional action values** below |
| `$waap_passed_incident_id` | `9a8b4f70-...` | Identifier of a previous WAAP incident that the request passed — for instance after a successful CAPTCHA solve in an earlier request from the same session. Empty if not applicable |
| `$waap_request_type` | `regular` | WAAP request classification (`regular`, `injected`) |
| `$waap_country` | `DE` | ISO 3166-1 alpha-2 country code of the client IP, resolved by WAAP |
| `$waap_organization` | `Deutsche Telekom AG` | Network organization that owns the client IP, resolved by WAAP |
| `$waap_range` | `203.0.113.0/24` | Network range associated with the client IP |
| `$waap_session_id` | `8c1f0d2a-...` | WAAP session identifier. Groups successive requests that WAAP attributes to the same client |
| `$waap_session_request_number` | `42` | Sequence number of this request within the WAAP session |
| `$waap_conviction_action` | `block` | Action prescribed by the matched rule. Possible values include `allow`, `block`, `monitor`, `captcha`, `handshake`. Empty if no rule matched |
| `$waap_conviction_rule_id` | `100245` | ID of the WAAP rule that matched the request |
| `$waap_conviction_rule_name` | `SQLi attempt` | Human-readable name of the matched WAAP rule |
| `$waap_conviction_scope` | `policy` | Scope at which the rule was applied (`policy`, `global`, `custom`) |
| `$waap_conviction_reference_id` | `signature:sqli-101` | Reference identifier of the conviction (rule signature, tag, or template reference) |
| `$waap_conviction_incident_id` | `4d2e8b1c-...` | Identifier of the WAAP incident raised for this request |
| `$waap_conviction_template` | `OWASP CRS` | Template or ruleset family the matched rule belongs to |
All WAAP fields are best-effort: a field is empty (`""`) when WAAP did not compute a value for the request — no rule matched, or the request was served before WAAP analysis completed. Treat empty values as "not applicable", not "zero".
The `$waap_decision` field gives the final security verdict that WAAP applied at the edge:
| Value | Meaning |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `passed` | Request was allowed because it matched a previously cleared WAAP incident — the client had already solved a CAPTCHA for an earlier request in the same session. The original incident identifier is exported in `$waap_passed_incident_id` |
| `allowed` | Request was explicitly allowed by a matched WAAP rule |
| `monitored` | Request was logged in monitor mode without applying the rule action. Useful for shadow testing rules before enforcement |
| `blocked` | Request was blocked at the edge, or a challenge was issued and is pending client resolution (see the note below) |
| empty (`""`) | No WAAP verdict was produced for this request — traffic that did not go through WAAP analysis |
The `$waap_optional_action` field describes any additional action applied alongside the decision:
| Value | Meaning |
| :----------- | :------------------------------------------------------------------------ |
| `captcha` | A CAPTCHA challenge was served to the client |
| `challenge` | A non-interactive challenge was issued — a JavaScript or cookie handshake |
| empty (`""`) | No additional action was applied |
Challenged requests are recorded as `blocked`. Logs are written at the edge as soon as the response is sent, before WAAP knows whether the client will solve the challenge. When the client passes the challenge, subsequent requests from the same session are exported with `$waap_decision="passed"` and `$waap_passed_incident_id` pointing back to the original incident. Trace the final outcome by joining the two log lines on the session identifier. The full per-incident result is also available through the [WAAP Request Details](/api-reference/waap/analytics/get-request-details) API.
## Near real-time log export
The **Time interval** setting in a Policy defines how often logs are archived and exported. The default interval is 5 minutes and can be set between 5 and 60 minutes.
If CDN servers receive no requests during the selected interval and **Include empty logs** is selected, Logs uploader sends an empty file of approximately 20 bytes to the storage target.