Content Distribution Network Interconnection (CDNI) Logging Interface
Extracted elements (32)
A file-based transfer model was chosen for CDNI Logging because it is the most common practice for exchange of logging information within and across CDNs today. Near-real-time (sub-minute) exchange is explicitly out of scope and left for further study.
The CDNI Logging File format is intentionally inspired by the W3C Extended Log File Format to keep the CDNI format close to intra-CDN log formats commonly used today, minimizing the need for systematic translation at the CDN/CDNI boundary. Where the two formats differ, the present document takes precedence.
The cdni_http_request_v1 record type is defined for HTTP/1.0, HTTP/1.1, and HTTPS delivery, and is expected to apply to HTTP/2 given HTTP/2's preservation of HTTP/1.1 semantics. Additional HTTP/2-specific fields (stream ID, priority, flow control) and HTTPS/TLS-specific fields are outside scope and deferred to a future record-type version.
A CDNI Logging File MUST contain a sequence of lines of US-ASCII characters terminated by CRLF. Each line MUST contain either a directive or a CDNI Logging Record.
A dCDN-side implementation MUST implement the cdni_http_request_v1 record type and MUST support providing valid values for all mandatory fields: date, time, time-taken, c-groupid, s-ip, s-hostname, s-port, cs-method, cs-uri, u-uri, protocol, sc-status, sc-total-bytes, sc-entity-bytes, cs(*), sc(*), and s-cached.
Adding a new CDNI Logging Directive requires registering both the new directive name in the CDNI Logging Directive Names registry and a new CDNI Logging File version in the CDNI Logging File version registry.
Adding a new CDNI Logging Field requires registering the new field name in the CDNI Logging Field Names registry and a new record-type in the CDNI Logging record-types registry; existing record-types are immutable.
CDNI Logging fields within a record MUST be separated by the horizontal tabulation (HTAB) character, and field values MUST appear in the order defined by the preceding fields directive.
Log text MUST be sanitized before being logged: null, bare CR, bare LF, and HTAB MUST be removed by escaping them through percent encoding to avoid confusion with Logging Record separators.
The c-groupid aggregation SHOULD be chosen so that each aggregate contains more than one client. When a single-client aggregate is used (e.g., for performance-based penalty analysis), the client identifier SHOULD be algorithmically generated in a way that is NOT linkable to the global addressing context, SHOULD vary over time, and its use as personally identifiable information is NOT RECOMMENDED.
The first line of a CDNI Logging File MUST be the version directive, and the entity transmitting the file MUST set its value to 'cdni/1.0'. There MUST be one and only one version directive per file.
The SHA256-hash directive SHOULD be present in every CDNI Logging File; when present, it MUST be the last line and MUST be computed over all preceding content using SHA-256. If the uCDN adds an established-origin directive, it MUST recompute the SHA256-hash.
The UUID directive MUST appear exactly once per CDNI Logging File. Its value is a URN from the UUID URN namespace (RFC 4122) that uniquely identifies the file.
Unknown directives MUST be ignored. A uCDN-side implementation MUST ignore a CDNI Logging File that does not comply with the occurrence rules for each directive (e.g., zero or two SHA256-hash directives).
When a field name is listed in the fields directive but the value is unavailable, this MUST be conveyed via a dash character ('-'). When a field name is not listed in the fields directive, the corresponding value MUST NOT be included in the record.
Logging HTTP request/response header fields (especially cookies and authorization tokens) centralizes long-lived credentials in CDNI Logging Files, creating significant risk. Implementations SHOULD restrict logged headers to a configured allowlist and SHOULD NOT support wildcard selection of header fields.
The c-groupid field is designed to protect end-user privacy by grouping clients into aggregates (e.g., by geolocation or AS number). Single-client aggregates are NOT RECOMMENDED because they are equivalent in identification power to a raw IP address and may constitute personally identifiable information under applicable law.
The cdni_http_request_v1 record type captures HTTP content delivery events. Mandatory fields are: date, time, time-taken, c-groupid, cs-method, u-uri, protocol, sc-status, sc-total-bytes. Optional fields include s-ip, s-hostname, s-port, cs-uri, sc-entity-bytes, cs(*), sc(*), s-cached, s-ccid, and s-sid.
The CDNI Logging Feed is an Atom feed published by the dCDN that advertises available CDNI Logging Files. The uCDN polls this feed and then pulls individual log files via HTTP GET (Section 4.2). This constitutes the post-collection exchange mechanism.
The CDNI Logging File is organized as one or more groups of directive lines (DIRGROUP) each followed by a group of zero or more record lines (RECGROUP). The file structure is: 1*(DIRGROUP RECGROUP).
The s-cached field (1DIGIT) indicates cache hit ('1') or miss ('0'). '1' MUST only be used when the Surrogate served the request exclusively from its local cache; '0' covers partial-cache and full-miss scenarios without distinguishing dCDN-level cache state.
The s-ccid and s-sid fields (both QSTRING) carry the Content Collection IDentifier from CDNI Metadata and a dCDN-generated Session IDentifier respectively, intended to correlate per-chunk HAS delivery records into per-session aggregates.
IANA created the 'CDNI Logging Directive Names' registry (Section 6.1) with Expert Review policy, seeding it with: version, UUID, claimed-origin, established-origin, remark, record-type, fields, and SHA256-hash.
IANA created the 'CDNI Logging Field Names' registry (Section 6.4) with Expert Review policy, seeding it with all fields defined in Section 3.4.1: date, time, time-taken, c-groupid, s-ip, s-hostname, s-port, cs-method, cs-uri, u-uri, protocol, sc-status, sc-total-bytes, sc-entity-bytes, cs(*), sc(*), s-ccid, s-sid, and s-cached.
IANA created the 'CDNI Logging File version' registry (Section 6.2) with IETF Review policy, seeding it with version 'cdni/1.0' referencing this document.
IANA created the 'CDNI Logging record-types' registry (Section 6.3) with Expert Review policy, seeding it with record-type 'cdni_http_request_v1' referencing Section 3.4.1 of this document.
IANA registered a 'CDNI Logging Payload Type' (Section 6.5) for the MIME media type used when exchanging CDNI Logging Files over the CDNI Logging interface.
CDNI Logging File exchanges MUST be protected using authentication, authorization, confidentiality, and integrity mechanisms. TLS is the recommended transport-layer mechanism; the established-origin directive can record the authenticated identity of the transmitting entity.
The Atom-feed pull model exposes the dCDN to denial-of-service attacks via excessive polling by the uCDN; rate limiting and authentication at the HTTP layer are recommended mitigations.
A CDNI Logging File uses a W3C Extended Log File Format-inspired text encoding: directives are lines beginning with '#' followed by DIRNAME ':' HTAB DIRVAL CRLF; records are lines of HTAB-separated field values in the order listed by the preceding fields directive, terminated by CRLF.
The c-groupid field is an opaque NHTABSTRING derived from the client IPv4 or IPv6 address; it MAY be structured (e.g., 'US/TN/MEM/38138'). The cs(header) and sc(header) fields use QSTRING encoding with percent-encoding for embedded DQUOTEs.
The SHA256-hash directive value is a 64-digit hexadecimal number (US-ASCII) representing the SHA-256 hash of the CDNI Logging File content up to, but not including, the SHA256-hash directive line itself.