2.2.1.1 ms-diagnostics Header

  • Article

Rules for adding this header

§ The SIP server SHOULD<2> add one ms-diagnostics header to a SIP response sent to the SIP protocol client.

§ The SIP server MUST NOT add more than one ms-diagnostics header to the same SIP response.

§ The SIP protocol client MUST NOT add the ms-diagnostics header to SIP requests or responses sent to the SIP server.

§ The SIP server MAY<3> add one ms-diagnostics header to CANCEL and BYE requests to indicate the reason for termination.

Header Format

The format for the ms-diagnostics header in the Augmented Backus-Naur Form (ABNF), as defined in [RFC5234], is specified as follows.

The parameters HCOLON, SEMI, generic-param, and quoted-string are as defined in [RFC3261] Section 25.1.

 ms-diagnostics HCOLON ErrorId SEMI reason-param SEMI source-param *(SEMI generic-param)

ErrorId (unsigned-integer): Required. Value MUST be within unsigned integer range. ErrorId represents a specific error condition, and SHOULD be used by the SIP client to determine appropriate error handling behavior.

source-param: Required. Equals "source=" source-value.

source-value: A quoted-string; optional. Value SHOULD be the fully qualified domain name (FQDN) or the IP address of the SIP server generating the header.

reason-param: Required. Equals "reason=" reason-value.

reason-value. A quoted-string; optional. Reason indicates a specific reason for an explanation of the error. The SIP protocol client SHOULD NOT use this parameter value for defining error handling behavior. This parameter value MAY be used for SIP server troubleshooting purposes, although this use is implementation-specific.

*(SEMI generic-param): Optional. Generic-param can be used to define custom attribute-value pairs to convey additional information to the SIP client on how to troubleshoot or fix the problem.

Following are some predefined Generic-param parameters. These parameters have specific meaning and SHOULD be used only for defined purpose.

  • Setup_time: Optional. The value of Setup_time is an integer that represents the time in milliseconds that is the difference between the time at which call establishment starts, and completes. Client SHOULD include this parameter only for calls that are established. If client is including this parameter it SHOULD report setup time as time perceived locally.

The following example is an ms-diagnostics header. For a list of all server error IDs and their corresponding reasons, see section 8.

ms-diagnostics: 1007;reason="Temporarily cannot route";source="sip.contoso.com";ErrorType="Connect Attempt Failure"
;WinsockFailureDescription="The peer actively refused the connection attempt";WinsockFailureCode="274D(WSAECONNREFUSED)"
;Peer="sip.fabrikam.com"

The error in the preceding example indicates that the server "sip.contoso.com" was not able to route the message or call to the peer server "sip.fabrikam.com" because the peer refused the attempt to connect. This could happen if the peer server was not accepting incoming connections.

In the preceding example:

  • ErrorId = 1007.

  • Source = "sip.contoso.com" is the server that reported the error.

  • Reason = "Temporarily cannot route" implies that this server, sip.contoso.com, cannot route messages and calls temporarily to the destination server.

  • The additional attributes Peer, ErrorType, WinsockFailureDescription and WinsockFailureCode provide additional information that can be used for troubleshooting purposes.