The table below lists all the built-in variables supported by the CDN Pro servers. You can use them in Edge Logic or Load Balancer Logic. All variables are supported in Edge Logic, and most variables are supported in Load Balancer Logic. The real-time log supports the same set of variables as the Edge Logic. Most variables here are read-only. The writable ones are indicated by R/W. The variables with numerical values are tagged with #.
If you use the CDN Pro portal to edit the property, typing $ at a position where a variable is allowed will list all the supported variables.
To use the variables properly, it is important to understand the request processing lifecycle. When Nginx processes a request, it goes through several stages. As the stages progress, Nginx variables are populated or updated dynamically. Accessing variables prematurely can lead to unexpected outcomes. For instance, upstream-related variables $upstream_* should not be accessed before a request is even passed to the upstream. Similarly, variables like $bytes_sent, $body_bytes_sent and $sc_completed, which are available only after the response is fully completed, should not be accessed before completion of the response (not even by add_header which is executed when response header is being constructed). These variables should only be accessed at log phase by custom_log_field or in realtime logs. In addition, variables like $request_time are updated continuously throughout the request lifecycle. If the variables are accessed before they are finalized, the values obtained early will differ from the ones at the request's completion.
Note: Due to upgrade of the edge node structure, the Load Balancer Logic will be deprecated soon. Please avoid using this field. All supported directives and variables should be configured in Edge Logic only. Refer to this article for more details.
| Variable Name | Description | Edge Logic | LB Logic |
|---|---|---|---|
| $arg_name | query parameter with the specified name | Yes | Yes |
| $args | the full query string from client | Yes | Yes |
| $body_bytes_sent | # body bytes sent to client | Yes | Yes |
| $bytes_sent | # total response bytes to client | Yes | Yes |
| $cache_misc | a writable variable to add parameters to the cache key | R/W | No |
| $cdn_cache_status | cache status: HIT, MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED. | Yes | Yes |
| $client_country_code | client’s ISO 3166 country code | Yes | Yes |
| $client_http_version | client's HTTP version, like "HTTP/1.1" | Yes | Yes |
| $client_ip_version | # client's IP version: 4 for IPv4; 6 for IPv6 | Yes | Yes |
| $client_isp | client's ISP information | Yes | Yes |
| $client_province_code | client's China province code | Yes | Yes |
| $client_real_ip | client's IP address | Yes | Yes |
| $connection_requests | # current number of requests in the connection | Yes | Yes |
| $content_code | a writable variable to assign a code to content for reporting and billing purposes | R/W | R/W |
| $content_length | # request's Content-Length header | Yes | Yes |
| $content_type | request's Content-Type header | Yes | Yes |
| $cookie_name | cookie with the specified name received from the client. The dot character (.) is allowed in this variable name to support cookie names that contain dots. You may need to use curly braces to separate this variable from a trailing literal dot. For example: $cookie_abc.test or ${cookie_abc.test} both refer to the value of the cookie "abc.test", but ${cookie_abc}.test gives you the value of the cookie "abc" followed by the literal ".test". | Yes | Yes |
| $cpu_time_ns | # CPU time in nanoseconds（1e-9s) spent on processing the request, before transferring the response body. | Yes | Yes |
| $dollar_sign | a literal dollar sign | Yes | Yes |
| $download_time | # the time in seconds from when CDN Pro receives the client request until CDN Pro sends the response body to the system buffer. The value should be equal to the sum of $request_end_time/$turn_around_time/$transfer_time. Another variable, $download_time_ms, shares the same meaning but is measured in milliseconds. The meaning of $download_time is the same as another variable, $request_time. | Yes | Yes |
| $error_code | error about client and origin | Yes | Yes |
| $extra_deliver_time_ms | # the estimated time in milliseconds needed to flush the TCP send buffer. | Yes | Yes |
| $host | host header, same as $http_host | Yes | Yes |
| $hostname | server's hostname | Yes | Yes |
| $http_name | request header with the specified name | Yes | Yes |
| $http_host | request's Host header | Yes | Yes |
| $ignored_body_in_cache_key | empty string when proxy_request_body_in_cache_key is off, '0' when the request body hash is included in the cache, or '1' otherwise | Yes | No |
| $invalid_referer | empty string if the “Referer” request header field value is considered valid; otherwise “1” | Yes | Yes |
| $is_args | empty or "?", when query string exists | Yes | Yes |
| $msec | # current Unix time in seconds with milliseconds resolution | Yes | Yes |
| $origin_host | origin's hostname | Yes | Yes |
| $origin_ip | IP and port of the origin. The format is IP:port | Yes | Yes |
| $origin_status_code | origin's status code | Yes | Yes |
| $pid | process ID of the service | Yes | Yes |
| $pipe | "p" if request is pipelined, or "." otherwise. | Yes | Yes |
| $property_ver | # the property version number | Yes | Yes |
| $qtl_cpu_cycle | Deprecated. Please use $cpu_time_ns instead. | Yes | Yes |
| $qtl_req_id | Deprecated. Please use $unique_req_id instead. | Yes | Yes |
| $qtl_upstream_cache_status | Deprecated. Please use $cdn_cache_status instead. | Yes | Yes |
| $random_N | # A random integer uniformly distributed in [0, N-1]. N can be an integer in [2, 1e9]. | Yes | Yes |
| $realtime_log_ds_factor | # RT log downsample factor. A value N means one log entry for every N requests. Users can use the directive realtime_log_downsample to override the default sample rate. | Yes | No |
| $realtime_log_ds_ratio | # RT log downsample ratio, the reciprocal of $realtime_log_ds_factor. The value should be a decimal number between 0 and 1. | Yes | No |
| $remote_user | user name extracted from the Authorization header if Basic authentication is used. | Yes | Yes |
| $request | full HTTP request line | Yes | Yes |
| $request_cpu_time | # CPU time in nanoseconds（1e-9s) spent on processing the request, before transferring the response body. Another variable $cpu_time_ns shares the same meaning. | Yes | Yes |
| $request_end_time | # the time in seconds it takes to receive the request header from the client and be ready to process or forward it. Another variable request_end_time_ms shares the same meaning but in milliseconds. | Yes | Yes |
| $request_length | # length of request line, header and body | Yes | Yes |
| $request_method | HTTP method: GET, POST, etc. | Yes | Yes |
| $request_scheme | "http" or "https" | Yes | Yes |
| $request_start_time | # the Unix time (in seconds with milliseconds resolution) when the first byte of the request is received from the client. | Yes | Yes |
| $request_time | # request processing time in seconds with a milliseconds resolution; time elapsed since the first bytes were read from the client. The value is equal to the sum of the values of 3 variables: $request_end_time, $turn_around_time and $transfer_time. When the request and response sizes are small, $request_end_time and $transfer_time may be 0 and $request_time may have the same value as $turn_around_time. | Yes | Yes |
| $request_uri | request URI from the client, beginning with '/' and including the query string | Yes | Yes |
| $sc_completed | # Value is 1 if the last byte was served to the client; 0 otherwise. | Yes | Yes |
| $sc_initial | # Value is 1 if the first byte was served to the client; 0 otherwise. | Yes | Yes |
| $sec | # current Unix time in integer seconds | Yes | Yes |
| $sent_http_name | header with the specified name sent to client | Yes | Yes |
| $sent_http_content_length | # Content-Length to client | Yes | Yes |
| $sent_http_content_type | Content-Type to client | Yes | Yes |
| $served_from_cache | # Value is 1 for a HIT on edge; 0 for a MISS. | Yes | Yes |
| $server_addr | IP address of the edge server | Yes | Yes |
| $server_level | # Level of the cache server. 1 means edge, and 2 means intermediate. | Yes | Yes |
| $server_name | The value specified in the property's hostnames that matched the incoming request. | Yes | Yes |
| $server_region | Country code of the edge server, e.g. CN, US | Yes | Yes |
| $server_province_code | The edge server's China province code | Yes | Yes |
| $server_protocol | HTTP/1.1, HTTP/2.0 or HTTP/3.0 | Yes | Yes |
| $service_port | # port number that received the request | Yes | Yes |
| $sorted_querystring_args | variable providing an ASCII-based sorted list of input query parameters; it can be modified by the "sorted_querystring_filter_parameter" directive | Yes | Yes |
| $ssl_cipher | TLS cipher suite used | Yes | Yes |
| $request_ssl_handshake_time | # CPU time, in nanoseconds, spent on TLS handshake | Yes | Yes |
| $ssl_protocol | returns protocol name like "TLSv1.1" | Yes | Yes |
| $ssl_server_name | TLS SNI servername | Yes | Yes |
| $status | HTTP status code to client | Yes | Yes |
| $tcpinfo_delivery_rate | # the rate, in bytes/s, at which the sent data is acknowledged by the client. | Yes | Yes |
| $tcpinfo_min_rtt | # minimum RTT, in microseconds, observed by TCP stack for the connection | Yes | Yes |
| $tcpinfo_rtt | # latest RTT, in microseconds, observed by TCP stack for the connection | Yes | Yes |
| $time_http | current time in RFC 7231 format that can be used for HTTP Date header | Yes | Yes |
| $transfer_time | # the time needed for CDN Pro to send the full requested object ( up to last byte ) to system buffer, in seconds. Another variable transfer_time_ms shares the same meaning but in milliseconds. | Yes | Yes |
| $turn_around_time | # the time needed for CDN Pro to receive first byte of response of origin, in seconds. Another variable turn_around_time_ms shares the same meaning but in milliseconds. | Yes | Yes |
| $unique_req_id | a unique ID for the request | Yes | Yes |
| $upstream_bytes_received | # number of bytes received from a parent or origin server | Yes | No |
| $upstream_bytes_sent | # number of bytes sent to a parent or origin server | Yes | No |
| $upstream_connect_time | # time spent in seconds with millisecond resolution establishing a connection with a parent or origin server | Yes | No |
| $upstream_cookie_name | cookie with the specified name received from the upstream server in the “Set-Cookie” response header field. May be served from the cache. The dot character (.) is allowed in this variable name to support cookie names that contain dots. You may need to use curly braces to separate this variable from a trailing literal dot. For example: $upstream_cookie_abc.test or ${upstream_cookie_abc.test} both refer to the value of the cookie "abc.test", but ${upstream_cookie_abc}.test gives you the value of the cookie "abc" followed by the literal ".test". | Yes | Yes |
| $upstream_header_time | # time spent in seconds with millisecond resolution receiving the response header from a parent or origin server | Yes | No |
| $upstream_http_name | header with the specified name received from the upstream server. May be served from the cache. | Yes | Yes |
| $upstream_response_status | status code from a parent or origin server. Value will be 0 for a cache HIT. | Yes | No |
| $upstream_response_time | # time spent in seconds with millisecond resolution receiving the complete response from a parent or origin server | Yes | No |
| $upstream_server_type | 'O' for origin server; 'C' for parent cache server. | Yes | No |
| $upstream_trailer_name | trailer with the specified name passed from the Edge Logic with the add_trailer directive. This variable is deprecated. | No | Yes |
| $uri | normalized request URI beginning with '/' and excluding the query string. The value may be modified by the "rewrite" directive in the Edge Logic. | Yes | Yes |