Network Working Group A. B. Roach
Internet-Draft Tekelec
Expires: September 26, 2009 March 25, 2009
Binary Syntax for SIP Common Log Format
draft-roach-sipping-clf-syntax-00
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 26, 2009.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Roach Expires September 26, 2009 [Page 1]
Internet-Draft Binary Syntax for SIP Common Log Format March 2009
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Abstract
This document proposes a binary syntax for the SIP common log format
(CLF). It does not cover semantic issues, and is meant to be
evaluated in the context of the other efforts discussing SIP CLF.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Normative References . . . . . . . . . . . . . . . . . . . . . 7
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7
Roach Expires September 26, 2009 [Page 2]
Internet-Draft Binary Syntax for SIP Common Log Format March 2009
1. Introduction
The Common Log File (CLF) format for the Session Initiation Protocol
(SIP) [I-D.gurbani-sipping-clf] proposes a syntax for logging SIP
messages received and sent by SIP clients, servers, and proxies. The
syntax proposed by that document has been inspired by the common HTTP
log format. However, experience with that format has shown that
dealing with large quantities of log data can be very processor
intensive, as doing so necessary requires reading and parsing every
byte in the log file(s) of interest.
This document counterpropses a format that is no more difficult to
generate by logging entites, while being radically faster to process.
In particular, the format is optimized for both rapidly scanning
through log records, as well as quickly locating commonly-accessed
data fields. Both operations can be performed in constant time (as
compared with O(n) time associated with the current format, where n
is the length of the log record).
2. Format
Each data record is encoded according to the following format:
Roach Expires September 26, 2009 [Page 3]
Internet-Draft Binary Syntax for SIP Common Log Format March 2009
0 7 8 15 16 23 24 31
+--------+--------+--------+--------+
| Flags | Record Length | 0 - 3
+--------+--------+--------+--------+
| Date/Time (bits 32-63) | 4 - 7
+ + + + +
| Date/Time (bits 0-31) | 8 - 11
+--------+--------+--------+--------+
| Time (nanoseconds) | 12 - 15
+--------+--------+--------+--------+
| CSeq Number | 16 - 19
+--------+--------+--------+--------+
| Response Code | TLV Start Ptr | 20 - 23
+--------+--------+--------+--------+
| Server Txn Ptr | Server Txn Len | 24 - 27
+--------+--------+--------+--------+
| Client Txn Ptr | Client Txn Len | 28 - 31
+--------+--------+--------+--------+
| Method Pointer | Method Length | 32 - 35
+--------+--------+--------+--------+
| To Value Ptr | To Value Len | 36 - 39
+--------+--------+--------+--------+
| To Tag Ptr | To Tag Len | 40 - 43
+--------+--------+--------+--------+
| From Value Ptr | From Value Len | 44 - 47
+--------+--------+--------+--------+
| From Tag Ptr | From Tag Len | 48 - 51
+--------+--------+--------+--------+
| Call-Id Pointer | Call-Id Length | 52 - 55
+--------+--------+--------+--------+
| |
| |
| Mandatory Field Data |
| |
| |
+--------+--------+--------+--------+ \
| Tag | Length | \
+--------+--------+--------+--------+ \ Repeated as
| | > many times
| Value | / as necessary
| | /
+--------+--------+--------+--------+ /
Flags Field (1 byte):
Roach Expires September 26, 2009 [Page 4]
Internet-Draft Binary Syntax for SIP Common Log Format March 2009
0x80 - Request/Response flag (0 = request, 1 = response)
0x40 - Retransmission flag (Always set to 0 if server is
stateless)
0x20 - Sent/Recieved flag (0 = message received, 1 = message
sent)
0x10 - Reserved
0x08 - Reserved
0x04 - Reserved
0x02 - Reserved
0x01 - Reserved
Record Length (3 bytes): Total length of this log record, including
"Flags" and "Record Length" fields
Date/Time (8 bytes): Seconds since midnight, January 1st, 1970, GMT
Time (4 bytes): Nanoseconds since the time in Date/Time field (<=
999,999,999)
CSeq Number (4 bytes): CSeq number from the SIP message
Response Code (2 bytes): Set to the value of the response code for
responses. Should be set to 0 for requests.
TLV Start Ptr (2 bytes): Indicates an absolute byte value for the
start of tag/length/value (TLV) groups. Set to 0 if no TLVs are
present.
Bytes 24 trough 55 contain pointer/length pairs that point to the
values of variable-length mandatory fields. The "Pointer" fields
indicate absolute byte values within the record, and must be >= 56
bytes. They point to the start of the corresponding value within the
"Mandatory Field Data" area. The "Length" fields indicate the length
of the corresponding value.
Server Txn: The transaction identifier associated with the server
transaction. Implementations MAY reuse the server transaction
identifier (the topmost branch-id of the incoming request, with or
without the magic cookie), or they MAY generate a unique
identification string for a server transaction (this identifier
needs to be locally unique to the server only.) This identifier
is used to correlate ACKs and CANCELs to an INVITE transaction; it
is also used to aid in forking.
Roach Expires September 26, 2009 [Page 5]
Internet-Draft Binary Syntax for SIP Common Log Format March 2009
Client Txn: This field is used to associate client transactions with
a server transaction for forking proxies or B2BUAs.
Method: In requests, the method from the start line. In responses,
the method found in the CSeq header field.
To Value: Value of the To header field, possibly with the tag
parameter removed. (Whether to remove the tag paramter is left up
to the logging entity).
To Tag: Value of the To header field tag parameter. If no To header
field tag parameter is present, the pointer field is ignored, and
the length field is set to 0.
From Value: Value of the From header field, possibly with the tag
parameter removed. (Whether to remove the tag paramter is left up
to the logging entity)
From Tag: Value of the From header field tag parameter.
Call-Id: The value of the Call-ID header field
Mandatory Field Data: Contains actual values for the preceding
fields. Note that this data is not necessarily in order, and is
not necessarily non-overlapping. In particular, loggers may
usefully choose to overlap the "To Tag" field with the "To Value"
field (and the "From Tag" field with the "From Value" field).
The Tag/Length/Value groups appear zero or more times, at the
location indicated by the "TLV Start Ptr" field. They are used to
log information that is not mandatory for all messages (although
specific TLVs are mandatory in request logs).
Tag Field (2 bytes): indicates the type of value coded by this TLV.
Currently defined tags are:
0 - Contact value (can be repeated)
Contains entire value of Contact header field
1 - Request URI (mandatory in request)
Contains Request URI in start line
2 - Remote Host (mandatory in request)
The DNS name of IP address from which the message was received
(if "sent/received flag" is 0) of the IP address to which the
message is being send (if "sent/received flag" is 1)
Roach Expires September 26, 2009 [Page 6]
Internet-Draft Binary Syntax for SIP Common Log Format March 2009
3 - Authenticated User
Contans the user name by which the user has been authenticated
4 - Complete SIP Message (optional, should be omitted by default)
Contains complete SIP message. Can be repeated multiple times
to accomodate SIP messages that exceed 65535 bytes in length.
Length Field (2 bytes): indicates the length of the value coded in
this TLV. This length does NOT include the TLV header.
Value Field (0 to 65535 bytes): contains the actual value of this
TLV.
3. Normative References
[I-D.gurbani-sipping-clf]
Gurbani, V., Burger, E., Anjali, T., Abdelnur, H., and O.
Festor, "The Common Log File (CLF) format for the Session
Initiation Protocol (SIP)", draft-gurbani-sipping-clf-01
(work in progress), March 2009.
Appendix A. Acknowledgements
Cullen put me up to this.
Author's Address
Adam Roach
Tekelec
17210 Campbell Rd.
Suite 250
Dallas, TX 75252
US
Email: adam@nostrum.com
Roach Expires September 26, 2009 [Page 7]