Format for the Session Initiation Protocol (SIP) Common Log Format (CLF)
updated by
- rfc-7355 — Indicating WebSocket Protocol as a Transport in the Session Initiation Protocol (SIP) Common Log Format (CLF)
Extracted elements (29)
Tab characters in field data are replaced with spaces rather than using a more complex escaping scheme because tabs in SIP headers carry no meaning beyond whitespace. This choice has known consequences: it makes impossible the reconstruction of cryptographic signatures over logged fields and may corrupt tab semantics in message bodies.
The indexed text format was chosen to address the high processor cost of purely text-based log formats (like Apache CLF). By prepending fixed-size hexadecimal pointers to each record, readers can skip directly to desired fields without scanning the entire record, achieving radically faster processing while retaining human readability and compatibility with Unix text tools (sed, awk, grep, cut, perl).
The optional field identifier format (Tag@Vendor-ID) is modeled after the syslog protocol's private use option (RFC 5424 Section 6.3.2) and uses IANA Private Enterprise Numbers (PEN) to create a globally unique namespace for vendor-specific SIP CLF extensions, avoiding collision without requiring central registration of each field.
Index lines in a SIP CLF file always start with an alphabetical character, while field data lines always start with a numerical character. This allows text processing tools (sed, awk, grep) to rapidly discard index lines without understanding the pointer format, and to split fields at tab characters for the 12 positional mandatory fields.
The SIP CLF format intentionally does not faithfully recreate the bit-exact SIP message. The formatting rules, encoding, and character escaping requirements (tab replacement, dash/question-mark substitution, CRLF omission) may introduce information loss relative to the original SIP message; log readers should never unescape SIP CLF records.
CRLFs in optionally logged SIP message bodies (Tag=01 and Tag=02) MUST be escaped using URI-encoded '%0D%0A'. Base64 encoding (BEB=01) MUST be applied before any character escaping.
If an optional SIP header field occurs more than once in a SIP message (e.g., Via, Contact, Route), each occurrence MUST be logged as a distinct optional field entry (each with Tag=00), preserving the ordinal position of repeated header fields.
Mandatory fields MUST appear in the order listed in Index Pointers, and each field MUST be present. Fields are subject to the maximum SIP CLF field size of 4096 bytes.
Tab characters (0x09) present in mandatory field data MUST be replaced by a UTF-8 space character (0x20) prior to logging. This substitution also applies to optional SIP header fields (Tag=00), full message bodies (Tag=01 and Tag=02).
The Optional Fields Start Pointer MUST point to the terminating line-feed (0x0A) at the end of the record if the optional fields group is not implemented. When optional fields are present, it points to the Tab (0x09) character beginning the first optional entry.
The SIP CLF Version MUST be incremented for any new SIP CLF specification that changes any part of the SIP CLF record format, including addition or removal of fields or a change in syntax or semantics. Version values are registered via the Standards Action method.
The terminating CRLF after a header field value MUST NOT be logged. Mandatory fields MUST NOT contain a CRLF when logged; no escaping is required for CRLF in mandatory fields since bare CRLF is not permitted within SIP header field values.
When a mandatory field is absent, it MUST be encoded as a single horizontal dash ('-'). If a field failed to parse, it MUST be encoded as a single question mark ('?'). If the actual field value is a single '-' or '?', the implementation SHOULD insert the percent-encoded equivalent (%2D or %3F).
When an optional message body (Tag=01) or entire SIP message (Tag=02) exceeds the 4096-byte maximum SIP CLF field size, the logged content MUST be truncated to meet this size limitation.
Client-Txn is used to associate client transactions with a server transaction for forking proxies or B2BUAs. Implementations may reuse the topmost Via branch parameter value or generate a unique string per client transaction.
Optional fields with Vendor-ID=00000000 support three standard tag values: Tag=00 logs a SIP header field or Reason-Phrase; Tag=01 logs the SIP message body (Content-Type prepended, separated by a space); Tag=02 logs the entire SIP message including headers and body.
Server-Txn is the server transaction identifier, which may reuse the topmost branch-id of the incoming request (with or without the magic cookie) or be a locally unique string. It is used to correlate ACKs and CANCELs to an INVITE and to track forking.
The Base64 Encoded Byte (BEB) field indicates whether an optional field's value is Base64 encoded. BEB=0x01 means the value is Base64 encoded; BEB=0x00 means it is not. Encoding is required when the value contains octets in range 0–31, 127, or invalid UTF-8 sequences (≥128).
The mandatory fields logged in the SIP CLF record (in pointer order) are: CSeq, Response Status-Code, R-URI, Destination IP:port, Source IP:port, To URI, To Tag, From URI, From Tag, Call-Id, Server-Txn (server transaction ID), and Client-Txn (client transaction ID). Each field is tab-delimited and subject to a 4096-byte maximum size.
The Version field (1 byte, UTF-8 encoded) ranges from 'A' (0x41) to 'Z' (0x5A). Version 'A' (0x41) is defined by this document. Since it is per-record, a single log file may contain records with different versions.
IANA established the 'Session Initiation Protocol (SIP) Common Log Format (CLF) Parameters' registry with two sub-registries: 'SIP CLF Version Values' (Standards Action policy, initial value 0x41/'A') and 'SIP CLF Transport Flag Values' (IETF Review policy, initial values U=UDP, T=TCP, S=SCTP).
The 'SIP CLF Transport Flag Values' registry uses the IETF Review registration policy. Initial registered values are: 'U' for UDP, 'T' for TCP, and 'S' for SCTP.
The 'SIP CLF Version Values' registry uses the Standards Action registration policy. The initial registered value is Version 0x41 ('A'), defined by RFC 6873. New versions must be registered for any format change.
This document does not introduce new security considerations beyond those in RFC 6872. Sensitive information in SIP CLF files may need to be obfuscated for privacy when files are exchanged between domains. If a Base64 encoded string contains non-obfuscated values, those values must also be obfuscated before Base64 encoding.
A SIP CLF record consists of three logical sections: a 60-byte Index Pointers header, a tab-delimited Mandatory Fields section, and an optional Optional Fields section, terminated by a line-feed (0x0A). The record begins with a 1-byte Version field followed by a 6-byte hexadecimal-encoded Record Length.
Each Optional Fields entry uses the format: Tab (0x09) + Tag (2 bytes decimal) + '@' (0x40) + Vendor-ID (8 bytes decimal) + ',' + Length (4 bytes hex) + ',' + BEB (1 byte: 0x00 or 0x01) + ',' + Value (0–4096 bytes). This group may be repeated as many times as necessary.
The Flags Field is 5 bytes encoding: byte 1 = Request ('R') or Response ('r'); byte 2 = Original ('O'), Duplicate ('D'), or Stateless ('S') transmission; byte 3 = Sent ('S') or Received ('R'); byte 4 = Transport (U=UDP, T=TCP, S=SCTP, IANA-assigned); byte 5 = Encrypted ('E') or Unencrypted ('U').
The Index Pointers section occupies bytes 0–59 of each SIP CLF record. It contains the Version (1 byte), Record Length (6 bytes), and 13 hexadecimal-encoded 4-byte field pointers (CSeq, Response Status-Code, R-URI, Destination IP:port, Source IP:port, To URI, To Tag, From URI, From Tag, Call-Id, Server-Txn, Client-Txn, Optional Fields Start), packed without delimiters as a 52-character hex string.
The Mandatory Fields section begins at byte 60 with a 0x0A (LF) delimiter, followed by a 10-byte decimal Timestamp (Unix epoch seconds), a 0x2E separator, a 3-byte decimal Fractional Seconds field (millisecond precision), a 0x09 tab, and a 5-byte Flags Field encoding Request/Response, Retransmission, Sent/Received, Transport, and Encryption state.