[sip-clf] Logging Optional Fields in the SIP CLF

[Gonzalo Salgueiro <[e-mail]>]

Folks - 

According to the discussions in Prague we decided that a single format be used to log optional fields. The current format draft presents two separate formats; one for logging Pre-defined optional fields and another to log vendor-specific elements. The discussions in Prague have indicated that a universally agreed upon list of Pre-Defined optional fields is too restrictive. Rather, the ability to log ANY SIP header (or header element) as well as body (or body element) should be optionally allowed by this format.

I'd like to propose the following format to log optional elements:

byte 1 0x09 (Tab)
byte 2-5 Tag (Hex)
byte 6 0x40 ('@')
byte 7-10 Vendor-ID (PEN)
byte 11 0x2C (comma)
byte 12-15 Length (Hex)
byte 16 0x2C (comma)
byte 17-... Value (variable length)

Note: This format is represented graphically in the diagram at the end of this message (view with fixed-width font).

This is a TLV format for logging optional fields that can be represented as:

tag@PEN,Length,Value

where:

I.  PEN=0x0000 is used to log the entire SIP message, message body, or any non-mandatory SIP header fields plus the Reason-Phrase

tag=0x0000 Log SIP Header Field or Reason-Phrase
tag=0x0001 Log message body
tag=0x0002 Log entire SIP message
    
- For the case of 0000@0000 the associated "Value" field MUST be populated by the entire header field being logged. That is, the field-name, the associated colon (":") and the field-value. This mechanism provides the capability to optionally log ANY SIP header field by identifying the field being logged in the "Value" field.
- Because the Reason-Phrase in a response is part of the Status-Line and is not identified with a field-name, it is a special case. In this instance, the the associated "Value" field MUST be populated by the name "Reason-Phrase" followed by a colon (":") and a single space (SP) between the colon and the logged reason phrase value.
- The corresponding "Length" field includes the length of the entire "Value" field. This includes the field-name, the colon, and any LWS separator.
- The cases of logging the message body (0001@0000) or the entire SIP message (0002@0000) are subject to the same field length limitation of 4k as detailed in the Problem Statement. 
    
Example:

Consider the SIP response:

SIP/2.0 180 Ringing
Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bKnashds8
 ;received=192.0.2.1
To: Bob <sip:[e-mail]>;tag=a6c85cf
From: Alice <sip:[e-mail]>;tag=1928301774
Call-ID: a84b4c76e66710
Contact: <sip:bob@192.0.2.4>
CSeq: 314159 INVITE
Content-Length: 0

The Contact header field and the reason phrase would be logged respectively as optional fields in the following manner:

0@0,1C,Contact: <sip:bob@192.0.2.4>
0@0,16,Reason-Phrase: Ringing


II. PEN=Vendor-ID is used to log everything else (i.e. any vendor specified element of a SIP header or body)

tag=vendor-specified tags

Example:

Consider the SIP message:

INVITE sip:[e-mail] SIP/2.0
Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bKnashds8
To: Bob <[e-mail]>
From: Alice <[e-mail]>;tag=1928301774
Call-ID: a84b4c76e66710
CSeq: 314159 INVITE
Max-Forwards: 70
Date: Thu, 21 Feb 2002 13:02:03 GMT
Contact: <sip:[e-mail]>
Content-Type: application/sdp
Content-Length: 147

v=0
o=UserA 2890844526 2890844526 IN IP4 here.com
s=Session SDP
c=IN IP4 pc33.atlanta.com
t=0 0
m=audio 49172 RTP/AVP 0
a=rtpmap:0 PCMU/8000
      

A vendor may choose to log the codec information from the SDP body. This would be formatted as follows:

3@32473,14,a=rtpmap:0 PCMU/8000

or perhaps a vendor wants to log that this message is the n^th message received from a peering partner.  To do so, it would log this information as:

7@32473,16,1877 example.com

which would signify that this is the 1,877^th message from the peering partner example.com

Please provide any feedback on this proposal as it is one the very few remaining open issues ti finalize the format draft.

Regards,

Gonzalo


 

        0          7 8        15 16       23 24         31
        +-----------+-----------+-----------+-----------+
        |    0x09   |             Tag (Hex)             |\
        +-----------+-----------+-----------+-----------+ \
        | Tag (cont)|    0x40   |       Vendor-ID       |  \   
        +-----------+-----------+-----------+-----------+   \  Repeated
        |    Vendor-ID (cont)   |    0x2C   |   Length  |    \ as many
        +-----------+-----------+-----------+-----------+    / times as
        |        Length (Hex) (cont)        |   0x2C    |   /  necessary
        +-----------+-----------+-----------+-----------+  /
        |            Value (variable length)            | /
        +-----------+-----------+-----------+-----------+/