Copyright © 2009 Toby Inkster, some rights reserved.
This document specifies a technique for HTTP servers to offer debugging information (warnings, notices) to clients; and a method for HTTP clients to advertise the fact that they would like this information.
A possible use-case would be a development tool that showed a browser side-panel with debugging messages while using a web service.
This document is published by buzzword.org.uk, a web site that hosts various specifications, articles and tools of use to web publishers. This is not a W3C recommendation. It is not even a buzzword.org.uk recommendation yet.
The author welcomes feedback on this draft by e-mail to firstname.lastname@example.org.
This document is available under a licence which allows the creation of derivative works under certain conditions. For the purpose of licensing, implementations of the ideas considered in this specification shall not be considered derivative works.
Clients wishing to be sent debugging messages should send a list of tokens representing the classes of messages they are interested in.
An example client request:
GET / HTTP/1.1 Host: webapp.example.com X-Debug: auth, db, conneg
Each class of message is indicated by a case-insensitive token. Multiple X-Debug tokens may be specified. Valid tokens are specified in Debugging Tokens. Additional application-specific tokens may also be requested — these must begin with x-.
As a special case, a header of X-Debug: * indicates that the client is interested in all debugging messages.
Indicates that the client is interested in debugging messages concerned with authentication and authorisation.
Indicates that the client is interested in debugging messages concerned with connection negotiation. This includes automatically negotiated media types, languages, character sets and so forth.
Indicates that the client is interested in debugging messages concerned with database access. This may include database query explanations, access problems and so forth.
Indicates that the client is interested in application-specific logic debugging messages. For example, indications that the server has reached a supposedly impossible state.
Applications may provide three levels of debugging information:
Classification of a debugging message as one of these levels is left up to the server. Debugging messages are communicated to the client using different techniques depending on the level of message.
This specification defers to [RFC2616]. If a server reaches a condition that will generate an error-level message, the server must respond with an appropriate 4xx or 5xx status code and a description of the error in the HTTP message body.
Servers may inspect the X-Debug request header to tailor the message body to the interests of the client.
Servers should include a Warning header for each warning message that the client is known to be interested in, and may include Warning headers for other warning-level messages. The syntax of the Warning header is defined in [RFC2616].
Servers should indicate the class of warning (e.g. conneg or auth) in square brackets at the start of the warn-text section of the header. For example:
HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Warning: 199 "[conneg] The plain text representation of this resource is significantly less pretty than the HTML version."
Notices are represented by HTTP response headers of the pattern X-Debug-class where "class" is the class of notice. For example:
HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 X-Debug-CONNEG: Automatically generating HTML from XML input.
Servers should include these messages when the client has indicated it is interested via the X-Debug request header. Servers should not include these headers in responses to disinterested clients, as it is a waste of bandwidth. (Even with gzipped responses, the HTTP header is transmitted uncompressed.)
Developers should be aware that exposing the internals of an application's processing and structure may pose security risks. They may wish to expose debugging messages only to authenticated clients or a restricted set of IP addresses.