W3C Trace Context

Retrieve the current W3C Trace Context (trace + span ID). More...

Functions
onesdk_result_t	onesdk_tracecontext_get_current (char *trace_id_buffer, onesdk_size_t trace_id_buffer_size, char *span_id_buffer, onesdk_size_t span_id_buffer_size)
	Retrieves the current W3C trace context's span and trace ID. More...
#define	ONESDK_TRACE_ID_BUFFER_SIZE   33
	Required size for trace ID buffer (including null termiator).
#define	ONESDK_SPAN_ID_BUFFER_SIZE   17
	Required size for span ID buffer (including null termiator).

Detailed Description

Retrieve the current W3C Trace Context (trace + span ID).

Function Documentation

onesdk_tracecontext_get_current()

onesdk_result_t onesdk_tracecontext_get_current	(	char *	trace_id_buffer,
		onesdk_size_t	trace_id_buffer_size,
		char *	span_id_buffer,
		onesdk_size_t	span_id_buffer_size
	)

Retrieves the current W3C trace context's span and trace ID.

Parameters

[out]	trace_id_buffer	[optional] Pointer to a buffer into which the W3C trace ID string shall be copied.
	trace_id_buffer_size	Size of the buffer pointed to by buffer in bytes. Must be zero if buffer is NULL. Otherwise, exactly ONESDK_TRACE_ID_BUFFER_SIZE bytes are required.
[out]	span_id_buffer	[optional] Pointer to a buffer into which the W3C trace ID string shall be copied.
	span_id_buffer_size	Size of the buffer pointed to by buffer in bytes. Must be zero if buffer is NULL. Otherwise, exactly ONESDK_SPAN_ID_BUFFER_SIZE bytes are required.

Returns

ONESDK_SUCCESS or ONESDK_ERROR_NO_DATA if successful, another SDK stub error code otherwise.

Warning

This function is only meant for use cases like log enrichment (https://www.dynatrace.com/support/help/shortlink/log-monitoring-log-enrichment) This function cannot be used to create traceparent headers for linking or similar purposes. For these purposes, use onesdk_tracer_get_outgoing_dynatrace_string_tag or onesdk_tracer_get_outgoing_dynatrace_byte_tag.

If a buffer pointer is not NULL and the respective buffer size big enough, this function will copy the string representation into the provided buffer. Providing a larger buffer than required is allowed but useless. Use the null-terminator to determine the length of the received string then.

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 strings copied into the buffers use ASCII encoding and will conform to the W3C trace ID specification (i.e., consist only of lowercase hex characters), see https://www.w3.org/TR/trace-context-1/#traceparent-header-field-values.

If there is no data available (return value ONESDK_ERROR_NO_DATA) or an error occurs (any other return value other than ONESDK_SUCCESS) all provided buffers will contain the "invalid" trace and span IDs, i.e. an ID with the usual length consisting only with ASCII digit zero (followed, as always, by a null-terminator). The only exception is, naturally, if the provided buffers are too small. In these cases, only a null-terminator (i.e., empty string) will be written (provided the buffer size allows that).

This means that you usually don't need to check the return value of the function, since the usual logging callback mechanism can still be used if diagnostics information is needed. However, if you want to know if you got a valid trace context, checking whether the function returns ONESDK_SUCCESS is faster than manually checking the IDs for zeroes.