Represents an X-Trace Event, with enough information to generate an X-Trace report. More...

#include <XtrEvent.h>

Public Member Functions
	Event ()
	Creates a new Event.
	Event (const Metadata &xtr)
	Creates a new Event from a given Metadata, with no incoming edges.
	Event (const Event &model)
	Creates a new Event with a default event as a model, i.e., with pre-filled fields.
xtr_result	setTaskId (const TaskId &taskId)
	Sets the taskId of the event.
xtr_result	setRandomOpId (size_t opIdLen=4)
	Sets the opId of the Event to a random one.
xtr_result	setSeverity (u_int8_t severity)
	Sets the severity of the Event.
u_int8_t	getSeverity ()
	Gets the severity of the event.
xtr_result	addEdge (const Metadata &xtr, EventEdge::EdgeDir dir=EventEdge::NEXT)
	Adds an edge to the event.
xtr_result	addInfo (const char key, const char value)
	Adds information to this event.
void	addTimestamp (const char *label)
size_t	fork ()
	Indicates that the task is forking at this event, i.e., two or more concurrent events will follow this task.
const Metadata &	getMetadata ()
	Returns an Metadata object to be propagated to the subsequent events in this task.
const Metadata &	getMetadata (size_t index)
	Returns an Metadata object to be propagated to the subsequent events in this task, indexed by the parameter index.
string	getReport ()
	Returns a string representation of the report for this event.
xtr_result	sendReport ()
	Directly call the Reporter report method.

Detailed Description

Represents an X-Trace Event, with enough information to generate an X-Trace report.

Constructor & Destructor Documentation

xtr::Event::Event ( )

Creates a new Event.

It has a new, random opId, but invalid taskId.

xtr::Event::Event ( const Metadata & xtr )

Creates a new Event from a given Metadata, with no incoming edges.

The event's taskId and opId will be taken from the metadata. Also, the chainId of the context will be set to the first chain id option present in the metadata, if present.

xtr::Event::Event ( const Event & model )

Creates a new Event with a default event as a model, i.e., with pre-filled fields.

The event is initialized as in the default constructor, except that the extra information (info) is copied. This constructor is useful to set things like Agent, Machine, or some other key/value pairs that would be repeated.

Member Function Documentation

xtr_result xtr::Event::addEdge	(	const Metadata &	xtr,
		EventEdge::EdgeDir	dir = `EventEdge::NEXT`
	)

Adds an edge to the event.

This has several effects on the event. The default type of edge added is 'NEXT'. The first edge added does: 1. sets the taskId of the event if not already set 2. logically adds an edge to the report 3. sets the size of the event opId A subsequent edge added with a different TaskId has no effect. It is an error. This is added to the report as an error report. TODO: this is not an error, and can help identify cross-task interactions A subsequent edge added with the same ChainId: 1. logically adds an edge to the report A subsequent edge added with a different ChainId: 1. logically adds an edge to the report 2. signifies that the event is a barrier. This will cause the termination of the incoming ChainId

Parameters:

xtr
dir

Returns:: XTR_SUCCESS if the edge is valid,
XTR_FAIL if the metadata is invalid, if the taskId of the edge is different from the first edge added.

See also:: setTimeNow()

xtr_result xtr::Event::addInfo	(	const char *	key,
		const char *	value
	)

Adds information to this event.

This is a key-value pair of strings. This information is added to the report for this event. Multiple additions to the same key are allowed, and are listed in the report in an arbitrary order.

Parameters:

key	key for the info
value	value for the info

Returns:: XTR_SUCCESS

void xtr::Event::addTimestamp ( const char * label )

Deprecated:: , does nothing.

The timestamp is added automatically when the event is reported.

size_t xtr::Event::fork ( )

Indicates that the task is forking at this event, i.e., two or more concurrent events will follow this task.

fork() creates a new chainId, and returns its index. The index starts with 0, and by default the chainId of index 0 is the same as the first edge added to the task.

fork() will set up state such that the next metadata retrieved from this EventCtx will be in a different chainId than the original one.

Returns:: the index of the current ChainId after fork is called.

See also:: getMetadata()

const Metadata& xtr::Event::getMetadata ( )

Returns an Metadata object to be propagated to the subsequent events in this task.

The metadata returned will have the current chainId, as set by calls to fork(). The default chainId is the chainId of the first edge added to the context, or the canonical chainId 0 otherwise.

Returns:: a reference to the metadata.

const Metadata& xtr::Event::getMetadata ( size_t index )

Returns an Metadata object to be propagated to the subsequent events in this task, indexed by the parameter index.

This is the integer returned by fork().

Returns:: a reference to the metadata, or a reference to an invalid metadata if index is invalid.

string xtr::Event::getReport ( )

Returns a string representation of the report for this event.

This is a fully formated report that can be sent to the reporting daemon, and conforms to the X-Trace report specification version 1.0.

u_int8_t xtr::Event::getSeverity ( )

Gets the severity of the event.

Returns:: severity or OptionSeverity::_ABSENT if no severity set.

xtr_result xtr::Event::sendReport ( )

Directly call the Reporter report method.

Returns:: XTR_SUCCESS if reporter accepts to report the event XTR_FAIL_SEVERITY if event's severity is not sufficient XTR_FAIL otherwise.

See also:: Return codes for Reporter::sendReport

xtr_result xtr::Event::setRandomOpId ( size_t opIdLen = 4 )

Sets the opId of the Event to a random one.

Returns:: XTR_SUCCESS

xtr_result xtr::Event::setSeverity ( u_int8_t severity )

Sets the severity of the Event.

The severity will be used when reporting.

Parameters:

severity severity of this event

Returns:: XTR_SUCCESS if s is valid

xtr_result xtr::Event::setTaskId ( const TaskId & taskId )

Sets the taskId of the event.

If the taskId is already set and is different from the one being set, an error is returned.

Parameters:

taskId taskId to set

Returns:: XTR_SUCCESS if taskId was unset (invalid) or if it was set and was the same as the parameter. XTR_FAIL otherwise.

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

XtrEvent.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation