I'm sponsoring this fast-track request for Girish Moodalbail. The
timer is set to 01/14/2008, but the submitter requests approval by
Friday of this week (01/11/2008) if at all possible.
The release binding is "patch/micro" and consolidation is "ON." The
stability level for the eight interfaces introduced is "Committed."
This project adds SIP traffic measurement and logging features to the
existing SIP stack, "SIP Library Integration" (PSARC 2006/402). With
this feature, applications using the SIP stack will be able to track:
(a) total number of bytes sent/recieved by the stack,
(b) total number of SIP requests/responses sent/received,
(c) number of SIP requests sent/received broken down by methods, and
(d) number of SIP responses sent/received broken down by response
codes.
The case "materials" directory has draft man pages for the new
interfaces.
SIP Traffic measurement
------------------------
Following are the eight new interfaces; the naming convention is in
keeping with existing SIP API:
/* SIP Traffic measurement interfaces */
(1) sip_enable_counters
(2) sip_disable_counters
(3) sip_get_counter_value
/* SIP transaction/dialog logging */
(4) sip_enable_trans_logging
(5) sip_enable_dialog_logging
(6) sip_disable_trans_logging
(7) sip_disable_dialog_logging
(8) sip_get_dialog_msgcnt
The following counters have been identified based on a stack user:
typedef enum sip_traffic_counter_names {
SIP_TOTAL_BYTES_RCVD = 0,
SIP_TOTAL_BYTES_SENT,
SIP_TOTAL_REQ_RCVD,
SIP_TOTAL_REQ_SENT,
SIP_TOTAL_RESP_RCVD,
SIP_TOTAL_RESP_SENT,
SIP_ACK_REQ_RCVD,
SIP_ACK_REQ_SENT,
SIP_BYE_REQ_RCVD,
SIP_BYE_REQ_SENT,
SIP_CANCEL_REQ_RCVD,
SIP_CANCEL_REQ_SENT,
SIP_INFO_REQ_RCVD,
SIP_INFO_REQ_SENT,
SIP_INVITE_REQ_RCVD,
SIP_INVITE_REQ_SENT,
SIP_NOTIFY_REQ_RCVD,
SIP_NOTIFY_REQ_SENT,
SIP_OPTIONS_REQ_RCVD,
SIP_OPTIONS_REQ_SENT,
SIP_PRACK_REQ_RCVD,
SIP_PRACK_REQ_SENT,
SIP_REFER_REQ_RCVD,
SIP_REFER_REQ_SENT,
SIP_REGISTER_REQ_RCVD,
SIP_REGISTER_REQ_SENT,
SIP_SUBSCRIBE_REQ_RCVD,
SIP_SUBSCRIBE_REQ_SENT,
SIP_UPDATE_REQ_RCVD,
SIP_UPDATE_REQ_SENT,
SIP_1XX_RESP_RCVD,
SIP_1XX_RESP_SENT,
SIP_2XX_RESP_RCVD,
SIP_2XX_RESP_SENT,
SIP_3XX_RESP_RCVD,
SIP_3XX_RESP_SENT,
SIP_4XX_RESP_RCVD,
SIP_4XX_RESP_SENT,
SIP_5XX_RESP_RCVD,
SIP_5XX_RESP_SENT,
SIP_6XX_RESP_RCVD,
SIP_6xx_RESP_SENT,
SIP_COUNTER_START_TIME,
SIP_COUNTER_STOP_TIME
} sip_traffic_counter_names_t;
The above definitions will be part of *sip.h* and will be introduced
as Committed. All of the above counters, except for
SIP_COUNTER_START_TIME and SIP_COUNTER_STOP_TIME, are defined to be
uint64_t. The two timer counters SIP_COUNTER_START_TIME and
SIP_COUNTER_STOP_TIME are defined to be time_t.
The following APIs will be provided to measure end-to-end SIP traffic:
(1) int sip_enable_counters(int counter_group)
Function: enables counting of the selected counter group.
Arguments:
counter_group: identifies the counter group to enable
counting for. The only allowed value as of now is
SIP_TRAFFIC_COUNTERS defined in <sip.h>.
Return Values:
0 : Success
EINVAL : If unknown counter_group is set.
(2) int sip_disable_counters(int counter_group)
Function: disables counting of the selected counter group. When
disabled, the counter values are NOT reset and are retained
until the measurement is enabled again.
Arguments:
counter_group: identifies the counter group to disable
counting for. The only allowed value as of now is
SIP_TRAFFIC_COUNTERS defined in <sip.h>.
Return Values:
0 : Success
EINVAL : If unknown counter_group is set.
(3) int sip_get_counter_value(int group, int counter, void *cntval,
size_t cntlen)
Function: retrieves the value for a given counter in a counter
group.
Arguments:
group: identfies the counter group. The only allowed value
as of now is SIP_TRAFFIC_COUNTERS.
counter: the counter whose value needs to be fetched. It can
be any one of aforementioned counters (see above
definitions).
*cntval: is the place holder for the counter value and
cannot be NULL
cntlen: size of the place holder.
Return Values:
0 : Success and *cntval will have the counter value
EINVAL : if group is unknown or if counter is unknown or
cntval is NULL or incorrect cntlen is specified.
SIP Transaction/Dialog logging:
-------------------------------
Another feature this project adds is SIP transaction and dialog
logging.
SIP is based on HTTP-like request/response transaction model. A
transaction is initiated by a request sent by a client transaction
to a server transaction, and terminated by a final response (for
that request) from the server transaction, there could be
intermediate responses from the server. Transaction logging, when
enabled, will capture all these request/responses exchanged within
a transaction.
A dialog is a peer-to-peer SIP relationship between tow user agents
that persists for some time. A dialog facilitates sequencing of
messages and proper routing of requests between the user agents.
Dialog logging, when enabled, will capture all the SIP messages
exchanged within a dialog.
Interfaces are provided to enable/disable transaction/dialog
logging. One can turn on either or both at the same time. All of
the messages exchanged within a transaction/dialog will be captured
and later on dumped to a log file, provided by application, when
the transaction/dialog is deleted/terminated. Each dialog when it
is terminated writes to the file the messages that were processed
in its context. Similarly, each transaction when it is terminated
writes to the file the messages that were processed in its context.
This feature provides the application to trace dialogs only or
transactions only or both.
The following API's will be provided to enable/disable
transaction/dialog logging:
(4) int sip_enable_trans_logging(FILE *logfile, int flags);
Function: enables transaction logging.
Arguments:
*logfile : points to a file to which SIP messages will be
logged.
flags : controls the level of logging. For now the only
acceptable value is SIP_DETAIL_LOGGING.
Return Values:
0 : Success
EINVAL : if logfile == NULL or flags value is unknown
(5) void sip_disable_trans_logging()
Function: disables transaction logging.
Arguments: (void)
Return Values: (void)
(6) int sip_enable_dialog_logging(FILE *logfile, int flags);
Function: enables dialog logging.
Arguments:
*logfile : points to a file to which SIP messages will be
logged.
flags : controls the level of logging. For now the only
acceptable value is SIP_DETAIL_LOGGING.
Return Values:
0 : Success
EINVAL : if logfile == NULL or flags value is unknown
(7) void sip_disable_dialog_logging()
Function: disables transaction logging.
Arguments: (void)
Return Values: (void)
(8) int sip_get_dialog_msgcnt(sip_dialog_t dialog, int *error);
Function: Returns the number of messages (requests and responses)
that were exchanged within the context of the given dialog.
Arguments:
dialog : points to the dialog from which the message count
needs to be retrieved. sip_dialog_t is an opaque
structure and hence we need this API.
*error : will be 0 if the call is success otherwise will have
EINVAL on failure (if dialogs not enabled or if
dialog == NULL)
Return Values:
Number of messages exchanged within the context of the given
dialog.
