xtr::Context Class Reference

Represents an X-Trace context, which carries information about the current task and the most recent preceding event in a thread. More...

#include <XtrContext.h>

Static Public Member Functions
static const Metadata &	getContext ()
	Get the current context metadata.
static void	setContext (Metadata const &xtr)
	Set the current context metadata.
static void	unsetContext ()
	Clear the current context.
static xtr_result	logEvent (const char *agent, const char *label, u_int8_t severity=OptionSeverity::_DEFAULT)
	Logs an event to the X-Trace framework.
static xtr_result	logEvent (Event *e, u_int8_t severity=OptionSeverity::_DEFAULT)
	Logs an event to the X-Trace framework.
static auto_ptr< Event >	createEvent (const char *agent, const char *label, u_int8_t severity=OptionSeverity::_DEFAULT)
	The same as logEvent, but does not send the report, and returns the created Event object.
static auto_ptr< Event >	prepareEvent (const char *agent, const char *label, u_int8_t severity=OptionSeverity::_DEFAULT)
	Prepares an event object for reporting, returning a(n auto) pointer to the created event object.
static void	setHost (const char *name)
	Sets the host name that is automatically added to the reports generated by logEvent() and createEvent().
static void	forkContext ()
	Explicitly indicate the start of a new chain of events.
Static Public Attributes
static pthread_key_t	context_key

---

Detailed Description

Represents an X-Trace context, which carries information about the current task and the most recent preceding event in a thread.

This class also provides methods to create and log X-Trace events.

---

Member Function Documentation

static auto_ptr<Event> xtr::Context::createEvent	(	const char *	agent,
		const char *	label,
		u_int8_t	severity = OptionSeverity::_DEFAULT
	)		[static]

The same as logEvent, but does not send the report, and returns the created Event object.

Use this to add more information to the report.

Deprecated:

use Context::prepareEvent() and Context::logEvent(Event * e, u_int8_t severity) instead. The problem with this call is that it advances the X-Trace context independent of reporting. If the reporting doesn't happen (for example, if the buffer is full or if severity won't allow), then the graph gets disconnected. The right way to do this is to advance the context only if reporting happens, which the other calls do correctly.

Parameters:

agent	value of the Agent: key for the created report
label	value of the Label: key for the created report
severity	desired severity level for this report. This event will be logged only if the event severity <= reporting context's severityThreshold.

Returns:

an auto_ptr to an allocated Event object. Remember to call sendReport() on this object to report it! You don't need to worry about deleting it unless you will be passing it around to other functions.

See also:

logEvent(), Event

static void xtr::Context::forkContext

(

)

[static]

Explicitly indicate the start of a new chain of events.

This is used for explicitly capturing concurrency, and is experimental.

static const Metadata& xtr::Context::getContext

(

)

[static]

Get the current context metadata.

static xtr_result xtr::Context::logEvent	(	const char *	agent,
		const char *	label,
		u_int8_t	severity = OptionSeverity::_DEFAULT
	)		[static]

Logs an event to the X-Trace framework.

This call prepares and logs an event atomically, with a reduced set of standard information in the report. If you want to add more information to events, use the pair of calls prepareEvent() / logEvent(Event *).

This does several things:

• creates a new Event object with a new OpId
• adds an edge from the current context to the new Event
• adds agent and label to the event as information
• sends a report from the new Event, if the severity level and threshold are compatible.
• sets the current context to the Event.getMetadata(), if the report was successful.

If the current context is not valid, it will create a new context with a random task id and set it.

Parameters:

agent	value of the Agent: key for the created report
label	value of the Label: key for the created report
severity	desired severity level for this event. The default value is OptionSeverity::_DEFAULT. This event will be logged only if the event severity <= reporting context's severityThreshold.

Returns:

• XTR_SUCCESS if the event was successfully sent to the logging layer. Semantics: the current X-Trace metadata will be changed to this event's eventId *IFF* this call returns XTR_SUCCESS.
• XTR_FAIL_SEVERITY if the severity level of the event was not sufficient to clear the effective severity threshold of the reporter. The effective severity threhsold of the reporter is a combination of the severity threshold of the reporter and the severity threshold of the current X-Trace metadata.
• XTR_FAIL if the report is not sent for some other reason.

See also:

Event

static xtr_result xtr::Context::logEvent	(	Event *	e,
		u_int8_t	severity = OptionSeverity::_DEFAULT
	)		[static]

Logs an event to the X-Trace framework.

The second version of the logEvent call, taking an event object pointer rather than message strings. This event will be, most likely, the result of a previous call to prepareEvent(). This call will, atomically:

• send the event to the reporting infrastructure and
• advance the current X-Trace context to the just-logged event. If the report is not accepted by the X-Trace reporter, the call returns XTR_FAIL and the context *is not* advanced.

Parameters:

e	A pointer to an event object to be logged. The calling function maintains ownership of the pointer.
severity	(default OptionSeverity::_DEFAULT) The severity of the logged event.

Returns:

• XTR_SUCCESS if the report is accepted by the reporter. This also means that the Xtr::Context is made to point the just-logged event.
• XTR_FAIL_SEVERITY if the report is not sent because of insufficient severity.
• XTR_FAIL if the report is not sent for some other reason.

See also:

logEvent(const char*, const char*, u_int8_t)

static auto_ptr<Event> xtr::Context::prepareEvent	(	const char *	agent,
		const char *	label,
		u_int8_t	severity = OptionSeverity::_DEFAULT
	)		[static]

Prepares an event object for reporting, returning a(n auto) pointer to the created event object.

Use this if you want to add more information to the event before logging than the simple Context::logEvent() call gives. The most common usage pattern should be:

     auto_ptr<Event> e = prepareEvent(...)
     e->addInfo(...)
     e->addEdge(...)
     ...
     logEvent(e.get())

This does the following:

• creates a new Event object with a new OpId
• adds an edge from the current context to the new Event
• adds agent and label to the event as information It DOES NOT advance the context, and does not do reporting.

  Parameters:

  agent	value of the Agent: key for the created report
  label	value of the Label: key for the created report
  severity	Desired severity level for this report. This event will be logged only if the event severity <= reporting context's severityThreshold.

  Returns:

  auto_ptr<Event> an auto pointer to the created event. This has not been logged yet, but this pointer is suitable to be logged by logEvent. Since this is an auto_ptr, you don't need to worry about freeing it at the end of a stack frame. To pass the pointer to a function, use the auto_ptr get() or release() methods, depending on whether you do not or do want to pass the responsibility of freeing the pointer to the called function.

static void xtr::Context::setContext

(

Metadata const &

xtr

)

[static]

Set the current context metadata.

Parameters:

xtr	the metadata to set the context to.

static void xtr::Context::setHost

(

const char *

name

)

[static]

Sets the host name that is automatically added to the reports generated by logEvent() and createEvent().

The setting overrides the default, which the class tries to obtain from the underlying OS.

Parameters:

name	a regular C string with the host name. At most MAXHOSTNAME (256) characters are copied from this string into the class.

static void xtr::Context::unsetContext

(

)

[static]

Clear the current context.

After this, a call to Context.getContext().isValid() will return false. This is important to avoid the context leaking to other unrelated operations

---

Field Documentation

pthread_key_t xtr::Context::context_key [static]

---

The documentation for this class was generated from the following file:

• XtrContext.h