Basic functions that can be used with all or multiple tracer types. More...

Functions
void	onesdk_tracer_start (onesdk_tracer_handle_t tracer_handle)
	Starts a tracer. More...

void	onesdk_tracer_end (onesdk_tracer_handle_t tracer_handle)
	Ends and releases a tracer. More...

void	onesdk_tracer_error (onesdk_tracer_handle_t tracer_handle, onesdk_string_t error_class, onesdk_string_t error_message)
	Sets error information for a tracer. More...

onesdk_size_t	onesdk_tracer_get_outgoing_dynatrace_string_tag (onesdk_tracer_handle_t tracer_handle, char buffer, onesdk_size_t buffer_size, onesdk_size_t required_buffer_size)
	Retrieves the string representation of the tag from an "outgoing taggable" tracer. More...

onesdk_size_t	onesdk_tracer_get_outgoing_dynatrace_byte_tag (onesdk_tracer_handle_t tracer_handle, unsigned char buffer, onesdk_size_t buffer_size, onesdk_size_t required_buffer_size)
	Retrieves the binary representation of the tag from an "outgoing taggable" tracer. More...

void	onesdk_tracer_set_incoming_dynatrace_string_tag (onesdk_tracer_handle_t tracer_handle, onesdk_string_t string_tag)
	Sets the tag of an "incoming taggable" tracer using the string representation. More...

void	onesdk_tracer_set_incoming_dynatrace_byte_tag (onesdk_tracer_handle_t tracer_handle, unsigned char const *byte_tag, onesdk_size_t byte_tag_size)
	Sets the tag of an "incoming taggable" tracer using the binary representation. More...

Detailed Description

Basic functions that can be used with all or multiple tracer types.

Tracers are the objects used to capture information about "operations" (e.g. remote calls or database requests) that your application performs.

Tracers are created by different factory functions, depending on the type of the tracer, and destroyed/released by onesdk_tracer_end.

Tracers are automatically linked to other active tracers on the same thread. To link to an operation that's running in another thread, processes or on another system you have to use the tagging or in-process linking functions.

Attention: All tracers in this SDK have strict thread affinity - they are bound to the thread by which they were created. Calling any tracer function with a tracer handle that was created by a different thread is an error and will not produce any effect. Note that this includes onesdk_tracer_end. Thus trying to destroy/release a tracer from a different thread will result in a memory leak.

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

Function Documentation

◆ onesdk_tracer_end()

void onesdk_tracer_end ( onesdk_tracer_handle_t tracer_handle )

Ends and releases a tracer.

Parameters

tracer_handle A valid tracer handle.

This function releases the specified tracer. Allocated resources are freed and the handle is invalidated.

An application should call onesdk_tracer_start exactly once for each tracer that it has created.

If the tracer has been started, the time measurement will be stopped and its exit fields will be captured before releasing the tracer.

Note: Just like all other tracer functions, this function must only be called from the thread that was used to create the tracer. This is important because it means that a tracer cannot be released on a different thread. Attempting to do so is an error and will result in memory leaks.

◆ onesdk_tracer_error()

void onesdk_tracer_error	(	onesdk_tracer_handle_t	tracer_handle,
		onesdk_string_t	error_class,
		onesdk_string_t	error_message
	)

inline

Sets error information for a tracer.

Parameters

tracer_handle	A valid tracer handle.
error_class	[optional] Pointer to a string denoting the error class/type/category.
error_message	[optional] Pointer to a string with the error message.

An application should call this function to notify a tracer that the traced operations has failed.

Note: Calling onesdk_tracer_error does not end/release the tracer.; onesdk_tracer_error must only be called once. If a traced operation results in multiple errors and the application wants all of them to be captured, it must concatenate/combine them and then call onesdk_tracer_error once before calling onesdk_tracer_end.

◆ onesdk_tracer_get_outgoing_dynatrace_byte_tag()

onesdk_size_t onesdk_tracer_get_outgoing_dynatrace_byte_tag	(	onesdk_tracer_handle_t	tracer_handle,
		unsigned char *	buffer,
		onesdk_size_t	buffer_size,
		onesdk_size_t *	required_buffer_size
	)

Retrieves the binary representation of the tag from an "outgoing taggable" tracer.

Parameters

	tracer_handle	A valid tracer handle.
[out]	buffer	[optional] Pointer to a buffer into which the binary representation shall be copied.
	buffer_size	Size of the buffer pointed to by `buffer` in bytes. Must be zero if `buffer` is `NULL`.
[out]	required_buffer_size	[optional] Pointer to a onesdk_size_t variable where the required buffer size will be stored.

Returns: The number of bytes copied into buffer.

An application can call this function to retrieve the binary representation of the outgoing tag for a tracer. The tracer handle must refer to an "outgoing taggable" tracer that has already been started.

If required_buffer_size is not NULL, the number of bytes required to store the binary representation is stored in *required_buffer_size.

If buffer is not NULL and buffer_size is big enough, this function will copy the binary representation into the provided buffer.

Note: If called with invalid arguments, the retrieved binary tag will be empty (have zero length).; Calling this function multiple times for the same tracer is explicitly supported and will yield the same result.; Retrieving both the string representation and the binary representation from the same tracer is explicitly supported.

See also: onesdk_tracer_get_outgoing_dynatrace_string_tag

◆ onesdk_tracer_get_outgoing_dynatrace_string_tag()

onesdk_size_t onesdk_tracer_get_outgoing_dynatrace_string_tag	(	onesdk_tracer_handle_t	tracer_handle,
		char *	buffer,
		onesdk_size_t	buffer_size,
		onesdk_size_t *	required_buffer_size
	)

Retrieves the string representation of the tag from an "outgoing taggable" tracer.

Parameters

	tracer_handle	A valid tracer handle.
[out]	buffer	[optional] Pointer to a buffer into which the string representation shall be copied.
	buffer_size	Size of the buffer pointed to by `buffer` in bytes. Must be zero if `buffer` is `NULL`.
[out]	required_buffer_size	[optional] Pointer to a onesdk_size_t variable where the required buffer size will be stored.

Returns: The number of characters copied into buffer, not including the terminating null character.

An application can call this function to retrieve the string representation of the outgoing tag for a tracer. The tracer handle must refer to an "outgoing taggable" tracer that has already been started.

If required_buffer_size is not NULL, the number of bytes required to store the string representation is stored in *required_buffer_size.

If buffer is not NULL and buffer_size is big enough, this function will copy the string representation into the provided buffer.

This function will always make sure that, if the application provides a non-NULL buffer with a buffer_size >= 1, buffer will always be null-terminated. I.e. if the string representation cannot be stored because buffer_size is too small, a null character will be written into buffer[0].

The string copied into buffer uses ASCII encoding.

Note: If called with invalid arguments, the retrieved string will be an empty string.; Calling this function multiple times for the same tracer is explicitly supported and will yield the same result.; Retrieving both the string representation and the binary representation from the same tracer is explicitly supported.

See also: onesdk_tracer_get_outgoing_dynatrace_byte_tag

◆ onesdk_tracer_set_incoming_dynatrace_byte_tag()

void onesdk_tracer_set_incoming_dynatrace_byte_tag	(	onesdk_tracer_handle_t	tracer_handle,
		unsigned char const *	byte_tag,
		onesdk_size_t	byte_tag_size
	)

Sets the tag of an "incoming taggable" tracer using the binary representation.

Parameters

tracer_handle	A valid tracer handle.
byte_tag	Pointer to an array that holds the binary representation of the incoming tag.
byte_tag_size	Size of the binary representation of the incoming tag.

An application can call this function to set the incoming tag of an "incoming taggable" tracer using the binary representation. The tracer handle must refer to an "incoming taggable" tracer that has not been started yet.

If byte_tag_size is zero, the incoming tag will be reset (cleared).

Note: An "incoming taggable" tracer has one tag. Calling onesdk_tracer_set_incoming_dynatrace_byte_tag will overwrite any tag that was set by either onesdk_tracer_set_incoming_dynatrace_string_tag or onesdk_tracer_set_incoming_dynatrace_byte_tag.

See also: onesdk_tracer_set_incoming_dynatrace_string_tag

◆ onesdk_tracer_set_incoming_dynatrace_string_tag()

void onesdk_tracer_set_incoming_dynatrace_string_tag	(	onesdk_tracer_handle_t	tracer_handle,
		onesdk_string_t	string_tag
	)

inline

Sets the tag of an "incoming taggable" tracer using the string representation.

Parameters

tracer_handle	A valid tracer handle.
string_tag	The string representation of the incoming tag.

An application can call this function to set the incoming tag of an "incoming taggable" tracer using the string representation. The tracer handle must refer to an "incoming taggable" tracer that has not been started yet.

If string_tag is a "null string" or an empty string, the incoming tag will be reset (cleared).