HttpTrace Struct Reference

Detailed Description

Buffered diagnostic output and optional HTTP protocol tracing.

Install a flush callback at startup to enable output. If the library is built without HTTP_TRACE, output functions have no effect. This header enables HTTP_TRACE by default unless NO_HTTP_TRACE is defined.

Priority zero is highest. A message is emitted when its priority is less than or equal to the configured filter (initially 5). Optional HTTP trace categories are initially disabled and use priority 5 when enabled.

Output is flushed when the buffer fills, after a write that leaves a newline in the buffer, or by an explicit flush(). Partial lines may remain buffered. The default payload buffer is approximately 80 bytes.

Configure the callback and buffer size at startup, before concurrent use. Do not change or close the trace while a writer is locked. Output functions serialize access with the trace mutex; the callback executes under that mutex and must not call back into trace output.

See also

HttpTrace::setFLushCallback

#include <HttpTrace.h>

Static Public Member Functions
static void	setFLushCallback (HttpTrace_Flush fcb)
	The HTTP_TRACE compile time macro adds the trace library to the Barracuda library, but the trace functions will have no effect if you do not provide a callback function. More...
static void	vprintf (int prio, const char *fmt, va_list argList)
	Write data to the trace buffer. More...
static void	printf (int prio, const char *fmt,...)
	Write data to the trace buffer. More...
static void	write (int prio, const char *buf, int len=-1)
	Write data to the trace buffer. More...
static int	setPrio (int prio)
	Set the trace message priority filter. More...
static BufPrint *	getWriter ()
	Get and lock the trace BufPrint object. More...
static void	releaseWriter (void)
	Release a writer lock obtained by a successful getWriter call. More...
static void	setRequest (bool cmd)
	Enable or disable request-line tracing. More...
static void	setRequestHeaders (bool cmd)
	If enabled, the web-server dumps the content of the request header to the trace buffer. More...
static void	setResponseHeaders (bool cmd)
	If enabled, the web-server dumps the content of the response header to the trace buffer. More...
static void	setResponseBody (bool cmd)
	If enabled, the web-server dumps the content of the response body to the trace buffer. More...
static void	setHttp11State (bool cmd)
	If enabled, prints the status for each active client connection of the internal "HTTP 1.1 persistent connection" state machine to the trace buffer. More...
static void	setReqBufOverflow (bool cmd)
	Report when an HTTP request exceeds the configured request buffer. More...
static int	setBufSize (int size)
	Set trace buffer size. More...
static void	flush ()
	Force a flush on data in trace buffer; i.e., call the flush callback. More...
static bool	isRequestSet ()
	Returns true if request-line tracing is enabled. More...
static bool	isRequestHeadersSet ()
	Returns true if request-header tracing is enabled. More...
static bool	isResponseHeadersSet ()
	Returns true if response-header tracing is enabled. More...
static bool	isResponseBodySet ()
	Returns true if response-body tracing is enabled. More...
static bool	isHttp11StateSet ()
	Returns true if HTTP/1.1 connection-state tracing is enabled. More...

Member Function Documentation

flush()

void HttpTrace::flush ( )

static

Force a flush on data in trace buffer; i.e., call the flush callback.

getWriter()

BufPrint * HttpTrace::getWriter ( )

static

Get and lock the trace BufPrint object.

Returns

Borrowed locked writer, or NULL when tracing is disabled. Call releaseWriter exactly once only after a non-NULL result. Writing through this object bypasses the priority filter. Do not free it.

See also

releaseWriter

HttpTraceWriteLock

isHttp11StateSet()

bool HttpTrace::isHttp11StateSet ( )

static

Returns true if HTTP/1.1 connection-state tracing is enabled.

isRequestHeadersSet()

bool HttpTrace::isRequestHeadersSet ( )

static

Returns true if request-header tracing is enabled.

isRequestSet()

bool HttpTrace::isRequestSet ( )

static

Returns true if request-line tracing is enabled.

isResponseBodySet()

bool HttpTrace::isResponseBodySet ( )

static

Returns true if response-body tracing is enabled.

isResponseHeadersSet()

bool HttpTrace::isResponseHeadersSet ( )

static

Returns true if response-header tracing is enabled.

printf()

void HttpTrace::printf ( int  prio, const char *  fmt,   ...  )

static

Write data to the trace buffer.

Works just like the regular printf function.

Parameters

prio	See HttpTrace::setPrio.
fmt	See BufPrint::printf

releaseWriter()

void HttpTrace::releaseWriter ( void  )

static

Release a writer lock obtained by a successful getWriter call.

Flushes pending output containing a newline before unlocking.

See also

HttpTraceWriteLock

setBufSize()

int HttpTrace::setBufSize ( int  size )

static

Set trace buffer size.

The default buffer is 80 characters long. This function is not re-entrant, and you should therefore call this function at system startup.

Parameters

size	Positive buffer allocation size in bytes; use at least 81. The payload capacity can be one byte smaller. Existing buffered data is discarded when replacing the buffer. Call only during startup.

Returns

0 on success, -1 on allocation failure (which disables tracing). Without HTTP_TRACE, the stub returns 0 without allocating storage.

setFLushCallback()

void HttpTrace::setFLushCallback ( HttpTrace_Flush  fcb )

static

The HTTP_TRACE compile time macro adds the trace library to the Barracuda library, but the trace functions will have no effect if you do not provide a callback function.

This function is not re-entrant; therefore, you should call this function at system startup.

The following example dumps data to the console:

void flush2Console(char* buf, int bufLen)
{
   // The trace buffer is always > bufLen
   buf[bufLen] = 0; // convert to string
   printf("%s",buf);
}
.
.
HttpTrace_setFLushCallback(flush2Console);

Newline-terminated output is flushed automatically. To deliver partial lines promptly, flush explicitly, for example after a dispatcher poll.

for(;;)
{
   myDispatcher->run(1000);
   HttpTrace::flush();
}

Parameters

[in]

fcb

Callback retained until replaced, or NULL to disable output. Allocation failure during initialization leaves tracing disabled; HttpTrace_getFLushCallback returns NULL in that case.

setHttp11State()

void HttpTrace::setHttp11State ( bool  cmd )

static

If enabled, prints the status for each active client connection of the internal "HTTP 1.1 persistent connection" state machine to the trace buffer.

The state machine can be in one of 5 states. As an example, a non-persistent connection will go through the following states for each request:

Connection 56c1f0 3944 trans: Free -> Connected
Connection 56c1f0 3944 trans: Connected -> Running
Connection 56c1f0 3944 trans: Running -> Terminated
Connection 56c1f0 -001 trans: Terminated -> Free

A persistent HTTP connection is in one of the Connected or Running states.

Connection 56c290 3944 trans: Connected -> Running
Connection 56c290 3944 trans: Running -> Connected
Connection 56c290 3944 trans: Connected -> Running
Connection 56c290 3944 trans: Running -> Connected
Connection 56c290 3944 trans: Connected -> Running
Connection 56c290 3944 trans: Running -> Connected

Parameters

[in]

cmd

TRUE enables this trace category; FALSE disables it.

setPrio()

int HttpTrace::setPrio ( int  prio )

static

Set the trace message priority filter.

Priority 0 is the highest priority. Setting the priority to say 10 means that only trace messages with a priority less than or equal to 10 will be printed to the trace buffer.

Parameters

prio	Maximum message priority to emit; use 0-255 [default=5]

Returns

previous priority.

setReqBufOverflow()

void HttpTrace::setReqBufOverflow ( bool  cmd )

static

Report when an HTTP request exceeds the configured request buffer.

Parameters

[in]

cmd

TRUE enables reporting; FALSE disables it.

See also

HttpServerConfig::setRequest

setRequest()

void HttpTrace::setRequest ( bool  cmd )

static

Enable or disable request-line tracing.

If enabled, the web-server prints the first line in the request header to the trace buffer.

Example:

68.5.99.169 GET "intro.html" Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.7) Gecko/20040623 Camino/0.8

Parameters

cmd	TRUE to enable request-line tracing.

setRequestHeaders()

void HttpTrace::setRequestHeaders ( bool  cmd )

static

If enabled, the web-server dumps the content of the request header to the trace buffer.

Parameters

cmd	TRUE to enable request-header tracing.

setResponseBody()

void HttpTrace::setResponseBody ( bool  cmd )

static

If enabled, the web-server dumps the content of the response body to the trace buffer.

Warning: this generates an enormous amount of trace data.

Parameters

cmd	TRUE to enable response-body tracing.

setResponseHeaders()

void HttpTrace::setResponseHeaders ( bool  cmd )

static

If enabled, the web-server dumps the content of the response header to the trace buffer.

Parameters

cmd	TRUE to enable response-header tracing.

vprintf()

void HttpTrace::vprintf ( int  prio, const char *  fmt, va_list  argList  )

static

Write data to the trace buffer.

Works just like the regular vprintf function.

Parameters

prio	See HttpTrace::setPrio.
fmt	See BufPrint::vprintf
argList	See BufPrint::vprintf more information.

write()

void HttpTrace::write ( int  prio, const char *  buf, int  len = -1  )

static

Write data to the trace buffer.

Parameters

prio	See HttpTrace::setPrio.
buf	Required input buffer, borrowed for the duration of the call.
len	Byte count; any negative value uses strlen(buf), requiring a NUL-terminated string. Zero writes no bytes.