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. 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. 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.

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 27, 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

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
2.  Format
3.  Normative References
Appendix A.  Acknowledgements
§  Author's Address

1.  Introduction

The Common Log File (CLF) format for the Session Initiation Protocol (SIP) [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),” March 2009.) 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:

 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):

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.

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)

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

Appendix A.  Acknowledgements

Cullen put me up to this.

Author's Address