Trace messages sent or received via a messaging system. More...

Functions
onesdk_messagingsysteminfo_handle_t	onesdk_messagingsysteminfo_create (onesdk_string_t vendor_name, onesdk_string_t destination_name, onesdk_int32_t destination_type, onesdk_int32_t channel_type, onesdk_string_t channel_endpoint)
	Creates a messaging system info object. More...

void	onesdk_messagingsysteminfo_delete (onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle)
	Releases a messaging system info object. More...

onesdk_tracer_handle_t	onesdk_outgoingmessagetracer_create (onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle)
	Creates a tracer for tracing an outgoing message. More...

void	onesdk_outgoingmessagetracer_set_vendor_message_id (onesdk_tracer_handle_t tracer_handle, onesdk_string_t vendor_message_id)
	Sets the vendor message ID of an outgoing message. More...

void	onesdk_outgoingmessagetracer_set_correlation_id (onesdk_tracer_handle_t tracer_handle, onesdk_string_t correlation_id)
	Sets the corrrelation ID of an outgoing message. More...

onesdk_tracer_handle_t	onesdk_incomingmessagereceivetracer_create (onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle)
	Creates a tracer for tracing the receipt of an incoming message. More...

onesdk_tracer_handle_t	onesdk_incomingmessageprocesstracer_create (onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle)
	Creates a tracer for tracing the processing of an incoming message. More...

void	onesdk_incomingmessageprocesstracer_set_vendor_message_id (onesdk_tracer_handle_t tracer_handle, onesdk_string_t vendor_message_id)
	Sets the vendor message ID of an incoming message. More...

void	onesdk_incomingmessageprocesstracer_set_correlation_id (onesdk_tracer_handle_t tracer_handle, onesdk_string_t correlation_id)
	Sets the corrrelation ID of an incoming message. More...

#define	ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME "dtdTraceTagInfo"
	Message property name for the Dynatrace byte tag. More...

#define	ONESDK_DYNATRACE_MESSAGE_PROPERTYNAME ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME
	DEPRECATED alias for ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME. More...

Detailed Description

Trace messages sent or received via a messaging system.

When tracing messages, we distinguish between:

Sending a message: See onesdk_outgoingmessagetracer_create.
Receiving a message: See onesdk_incomingmessagereceivetracer_create
Processing a received message: See onesdk_incomingmessageprocesstracer_create

To create an outgoing message tracer, an application can simply call onesdk_outgoingmessagetracer_create. To enable continuing the trace on the consumer side, the application must then retrieve the byte tag from the tracer and send it along with the message in a property named "dtdTraceTagInfo" (if the other side is also traced by the SDK, any other method of transferring the tag is also possible as long as the receiving application's tracing cooperates, but the aforementioned method is highly recommended and also works with non-SDK OneAgents if the receiving message system is supported).

See also: onesdk_tracer_get_outgoing_dynatrace_byte_tag; ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME

For further information, see the high level SDK documentation at https://github.com/Dynatrace/OneAgent-SDK/#messaging

Since: Messaging tracers were added in version 1.4.0.

Macro Definition Documentation

◆ ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME

#define ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME "dtdTraceTagInfo"

Message property name for the Dynatrace byte tag.

Sending an "dtdTraceTagInfo" message property with a Dynatrace byte tag along with an message enables any Dynatrace OneAgent on the server side to continue tracing (connect the server side trace to the traced operation from which the tag was obtained). This works only if the receiving application is monitored by a Dynatrace agent and the messaging system used for receiving is supported.

◆ ONESDK_DYNATRACE_MESSAGE_PROPERTYNAME

#define ONESDK_DYNATRACE_MESSAGE_PROPERTYNAME ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME

DEPRECATED alias for ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME.

Deprecated:: Use ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME instead.

Function Documentation

◆ onesdk_incomingmessageprocesstracer_create()

onesdk_tracer_handle_t onesdk_incomingmessageprocesstracer_create ( onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle )

Creates a tracer for tracing the processing of an incoming message.

Parameters

messagingsysteminfo_handle A valid messaging system info handle.

Returns: A handle for the newly created incoming message process tracer or ONESDK_INVALID_HANDLE.

Use this tracer to trace the actual, logical processing of the message as opposed to the time it takes to receive it.

If you use an incoming message receive tracer to trace the receipt of the processed message, start and end the corresponding incoming message process tracer while the receive tracer is still active.

See also: onesdk_incomingmessagereceivetracer_create

Since: This function was added in version 1.4.0.

◆ onesdk_incomingmessageprocesstracer_set_correlation_id()

void onesdk_incomingmessageprocesstracer_set_correlation_id	(	onesdk_tracer_handle_t	tracer_handle,
		onesdk_string_t	correlation_id
	)

inline

Sets the corrrelation ID of an incoming message.

Parameters

tracer_handle	A valid incoming message process tracer handle.
correlation_id	The correlation ID for the message, usually application-defined.

Since: This function was added in version 1.4.0.

◆ onesdk_incomingmessageprocesstracer_set_vendor_message_id()

void onesdk_incomingmessageprocesstracer_set_vendor_message_id	(	onesdk_tracer_handle_t	tracer_handle,
		onesdk_string_t	vendor_message_id
	)

inline

Sets the vendor message ID of an incoming message.

Parameters

tracer_handle	A valid incoming message process tracer handle.
vendor_message_id	The message ID provided by the messaging system.

Since: This function was added in version 1.4.0.

◆ onesdk_incomingmessagereceivetracer_create()

onesdk_tracer_handle_t onesdk_incomingmessagereceivetracer_create ( onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle )

Creates a tracer for tracing the receipt of an incoming message.

Parameters

messagingsysteminfo_handle A valid messaging system info handle.

Returns: A handle for the newly created incoming message receive tracer or ONESDK_INVALID_HANDLE.

Tracing the receipt of the message is optional but may make sense if receiving may take a significant amount of time, e.g. when doing a blocking receive. It might make less sense when tracing a polling receive. If you do use a receive tracer, start and end the corresponding incoming message process tracer while the receive tracer is still active.

See also: onesdk_incomingmessageprocesstracer_create

Since: This function was added in version 1.4.0.

◆ onesdk_messagingsysteminfo_create()

onesdk_messagingsysteminfo_handle_t onesdk_messagingsysteminfo_create	(	onesdk_string_t	vendor_name,
		onesdk_string_t	destination_name,
		onesdk_int32_t	destination_type,
		onesdk_int32_t	channel_type,
		onesdk_string_t	channel_endpoint
	)

inline

Creates a messaging system info object.

Parameters

vendor_name	One of messaging_vendor_strings for well known vendors, or a custom string otherwise.
destination_name	The "destination" name, i.e. queue name or topic name.
destination_type	One of the messaging_destination_type.
channel_type	The type of the channel used to communicate with the messaging system.
channel_endpoint	[optional] The endpoint of the channel used to communicate with the messaging system.

Returns: A handle for the newly created messaging system info object or ONESDK_INVALID_HANDLE.

This function creates a messaging system info object which is required for tracing sending, receiving and processing messages. (see Messaging).

For information about channel_type and channel_endpoint see Channel Types and Endpoints.

Since: This function was added in version 1.4.0.

◆ onesdk_messagingsysteminfo_delete()

void onesdk_messagingsysteminfo_delete ( onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle )

Releases a messaging system info object.

Parameters

messagingsysteminfo_handle A valid messaging system info handle.

This function releases the specified messaging system info object. Allocated resources are freed and the handle is invalidated.

An application should call onesdk_messagingsysteminfo_delete exactly once for each messaging system info object that it has created.

Note: Calling onesdk_messagingsysteminfo_delete with a handle to a messaging system info object which is still referenced by existing tracers is supported. In that case the lifetime of the messaging system info object is extended as necessary. The handle will always become invalid immediately though.

Since: This function was added in version 1.4.0.

◆ onesdk_outgoingmessagetracer_create()

onesdk_tracer_handle_t onesdk_outgoingmessagetracer_create ( onesdk_messagingsysteminfo_handle_t messagingsysteminfo_handle )

Creates a tracer for tracing an outgoing message.

Parameters

messagingsysteminfo_handle A valid messaging system info handle.

Returns: A handle for the newly created outgoing message tracer or ONESDK_INVALID_HANDLE.

Since: This function was added in version 1.4.0.

◆ onesdk_outgoingmessagetracer_set_correlation_id()

void onesdk_outgoingmessagetracer_set_correlation_id	(	onesdk_tracer_handle_t	tracer_handle,
		onesdk_string_t	correlation_id
	)

inline

Sets the corrrelation ID of an outgoing message.

Parameters

tracer_handle	A valid incoming message process tracer handle.
correlation_id	The correlation ID for the message, usually application-defined.

Note: This information is often only available after the message was sent. Thus, calling this function is also supported after starting the tracer.

Since: This function was added in version 1.4.0.

◆ onesdk_outgoingmessagetracer_set_vendor_message_id()

void onesdk_outgoingmessagetracer_set_vendor_message_id	(	onesdk_tracer_handle_t	tracer_handle,
		onesdk_string_t	vendor_message_id
	)

inline

Sets the vendor message ID of an outgoing message.

Parameters

tracer_handle	A valid incoming message process tracer handle.
vendor_message_id	The message ID provided by the messaging system.

Note: This information is often only available after the message was sent. Thus, calling this function is also supported after starting the tracer.

Since: This function was added in version 1.4.0.

Functions

Detailed Description

Macro Definition Documentation

◆ ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME

◆ ONESDK_DYNATRACE_MESSAGE_PROPERTYNAME

Function Documentation

◆ onesdk_incomingmessageprocesstracer_create()

◆ onesdk_incomingmessageprocesstracer_set_correlation_id()

◆ onesdk_incomingmessageprocesstracer_set_vendor_message_id()

◆ onesdk_incomingmessagereceivetracer_create()

◆ onesdk_messagingsysteminfo_create()

◆ onesdk_messagingsysteminfo_delete()

◆ onesdk_outgoingmessagetracer_create()

◆ onesdk_outgoingmessagetracer_set_correlation_id()

◆ onesdk_outgoingmessagetracer_set_vendor_message_id()