Writing trace messages. More...

Macros
#define	TRACE_LEVEL_DEBUG 1
	Identifier for debug trace level: also logs internal variables/states, only useful for developers.

#define	TRACE_LEVEL_DATA 2
	Identifier for data trace level: logs process data (e.g. More...

#define	TRACE_LEVEL_INFO 4
	Identifier for info trace level: informational (e.g. More...

#define	TRACE_LEVEL_FUNC_ENTER 8
	Identifier for function enter trace level.

#define	TRACE_LEVEL_FUNC_LEAVE 16
	Identifier for function leave trace level.

#define	TRACE_LEVEL_FUNC 24
	Identifier for function trace level.

#define	TRACE_LEVEL_NOTICE 32
	Identifier for notice trace level: normal but significant condition, e.g. More...

#define	TRACE_LEVEL_WARNING 64
	Identifier for warning trace level. More...

#define	TRACE_LEVEL_ERROR 128
	Identifier for error trace level: error conditions, e.g. More...

#define	TRACE_LEVEL_INSANE 256
	Identifier for insane trace level, produces a lot of output! This is used for cyclic events. More...

#define	TRACE_LEVEL_ALL 511
	Combination of all trace levels.

#define	TRACE_LEVEL_DEFAULT (TRACE_LEVEL_ERROR \| TRACE_LEVEL_WARNING \| TRACE_LEVEL_NOTICE)
	Default trace levels the should be used at runtime. More...

#define	TRACE_FAC_PLATFORM 1
	Identifier for platform facility.

#define	TRACE_FAC_NETWORK 2
	Identifier for network facility.

#define	TRACE_FAC_CRYPTO 4
	Identifier for crypto facility.

#define	TRACE_FAC_IPC 8
	Identifier for IPC facility.

#define	TRACE_FAC_BASE 16
	Identifier for base facility.

#define	TRACE_FAC_MEMORY 32
	Identifier for memory facility.

#define	TRACE_FAC_UATCP 64
	Identifier for UATCP facility.

#define	TRACE_FAC_ENCODER 128
	Identifier for encoder facility.

#define	TRACE_FAC_SESSION 256
	Identifier for session facility.

#define	TRACE_FAC_PROVIDER 512
	Identifier for provider facility.

#define	TRACE_FAC_APPLICATION 1024
	Identifier for application facility.

#define	TRACE_FAC_ADDRSPACE 2048
	Identifier for address space facility.

#define	TRACE_FAC_TIMER 4096
	Identifier for timer facility.

#define	TRACE_FAC_PKI 8192
	Identifier for timer facility.

#define	TRACE_FAC_SUBSCRIPTION 16384
	Identifier for subscription facility.

#define	TRACE_FAC_CLIENT 32768
	Identifier for client facility.

#define	TRACE_FAC_USERAPPLICATION 65536
	Reserved for the user application. More...

#define	TRACE_FAC_FILEFORMAT (1 << 17)
	Identifier for file format facility.

#define	TRACE_FAC_FILETRANSFER (1 << 18)
	Identifier for filetransfer facility.

#define	TRACE_FAC_PUBSUB (1 << 19)
	Identifier for pubsub facility.

#define	TRACE_FAC_SERVICECALL (1 << 20)
	Identifier for service call facility. More...

#define	TRACE_FAC_PUBSUB_KEYSTORE (1 << 21)
	Identifier for pubsub keystore facility.

#define	TRACE_FAC_GDS (1 << 22)
	Identifier for GDS facility.

#define	TRACE_FAC_ALL ((1 << 23) - 1)
	Combination of all facilities.

#define	TRACE_SECMASK_SHOW_USERNAME 1
	Enables tracing of usernames. More...

#define	TRACE_SECMASK_SHOW_PASSWORD 2
	Enables tracing of passwords. More...

#define	TRACE_SECMASK_SHOW_IPADDRESS 4
	Enables tracing of IP addresses. More...

#define	TRACE_SECMASK_SHOW_ALL 7
	Enables all sensitive information. More...

#define	TRACE_DEBUG(facility, format, ...) trace_log(TRACE_LEVEL_DEBUG, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with debug level.

#define	TRACE_DATA(facility, format, ...) trace_log(TRACE_LEVEL_DATA, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with data level.

#define	TRACE_INFO(facility, format, ...) trace_log(TRACE_LEVEL_INFO, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with info level.

#define	TRACE_NOTICE(facility, format, ...) trace_log(TRACE_LEVEL_NOTICE, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with notic level.

#define	TRACE_WARNING(facility, format, ...) trace_log(TRACE_LEVEL_WARNING, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with warning level.

#define	TRACE_ERROR(facility, format, ...) trace_log(TRACE_LEVEL_ERROR, facility, format, ##__VA_ARGS__)
	Convenience define for tracing with error level.

#define	TRACE_INSANE(facility, format, ...)
	Convenience define for tracing with insane level.

#define	TRACE_ENTER(facility, funcname) trace_log(TRACE_LEVEL_FUNC_ENTER, facility, "> %s\n", funcname); trace_indent()
	Trace with function enter level, adds an indent.

#define	TRACE_RETURN(facility, funcname) trace_unindent(); trace_log(TRACE_LEVEL_FUNC_LEAVE, facility, "< %s\n", funcname)
	Trace with function leave level, removes an indent.

#define	TRACE_RETURNERR(facility, funcname, result) trace_unindent(); trace_log(TRACE_LEVEL_FUNC_LEAVE, facility, "< %s - return 0x%08X\n", funcname, result)
	Trace with function leave level, removes an indent and prints errorcode.

#define	TRACE_ENTERD(facility, funcname) trace_log(TRACE_LEVEL_INSANE, facility, "> %s\n", funcname); trace_indent()
	Trace function enter with insane level, adds an indent.

#define	TRACE_RETURND(facility, funcname) trace_unindent(); trace_log(TRACE_LEVEL_INSANE, facility, "< %s\n", funcname)
	Trace function leave with insane level, removes an indent.

#define	TRACE_RETURNERRD(facility, funcname, result) trace_unindent(); trace_log(TRACE_LEVEL_INSANE, facility, "< %s - return 0x%08X\n", funcname, result)
	Trace function leave with insane level, removes an indent and prints errorcode.

#define	TRACE_HEXDUMP(facility, data, len) trace_hexdump(TRACE_LEVEL_DATA, facility, data, len)
	Trace function for printing binary data as a hex dump.

#define	TRACE_USERNAME(x) trace_username(x)

#define	TRACE_PASSWORD(x) trace_password(x)

#define	TRACE_IPv4(x) trace_ipv4(x)

#define	TRACE_IPv6(x) trace_ipv6(x)

Functions
TRACE_EXPORT int	trace_openlog (int level_mask, int facility_mask)
	Initialize the trace backend. More...

TRACE_EXPORT void	trace_log (int level, int facility, const char *format,...) TRACE_FORMAT_ARGUMENT(3
	Write to trace. More...

TRACE_EXPORT void TRACE_EXPORT void	trace_hexdump (int level, int facility, const unsigned char *data, size_t count)
	Writes the hexdump of the given data to trace output. More...

TRACE_EXPORT void	trace_closelog (void)
	Close the trace backend.

TRACE_EXPORT int	trace_change_trace_level (int level_mask, int facility_mask)
	Change the trace level and facility. More...

TRACE_EXPORT int	trace_change_security_level (int security_mask)
	Changes the security level of the trace output. More...

TRACE_EXPORT int	trace_get_security_level (void)
	Returns the current security level mask. More...

TRACE_EXPORT int	trace_enabled (int level)
	Test if a certain trace level is enabled. More...

TRACE_EXPORT void	trace_indent (void)
	Add an indent to all further traces messages.

TRACE_EXPORT void	trace_unindent (void)
	Remove an indent from all further trace messages.

TRACE_EXPORT const char *	trace_username (const char *username)
	Returns the `username` as-is if TRACE_SECMASK_SHOW_USERNAME is set, otherwise the string "<hidden>". More...

TRACE_EXPORT const char *	trace_password (const char *password)
	Returns the `password` as-is if TRACE_SECMASK_SHOW_PASSWORD is set, otherwise the string "XXX". More...

TRACE_EXPORT const char *	trace_ipv4 (const unsigned char ipv4[4])
	Returns the string representation of the given IPv4 address if TRACE_SECMASK_SHOW_IPADDRESS is set, otherwise an anonymised version of it. More...

TRACE_EXPORT const char *	trace_ipv6 (const unsigned char ipv6[16])
	Returns the string representation of the given IPv6 address if TRACE_SECMASK_SHOW_IPADDRESS is set, otherwise an anonymised version of it. More...

TRACE_EXPORT void	trace_print_flags (const char *appname)
	Prints the available trace flags. More...

TRACE_EXPORT int	trace_parse_trace_level (char *args)
	Parse a numeric or textual representation of trace levels. More...

TRACE_EXPORT int	trace_parse_trace_facility (char *args)
	Parse a numeric or textual representation of trace facilities. More...

TRACE_NO_EXPORT const char *	trace_format_timestamp (void)

TRACE_NO_EXPORT void	trace_sdk_info (void)

Detailed Description

Writing trace messages.

The SDK has multiple trace backends implemented, which can be selected using the cmake switch TRACE_BACKEND. Each of them writes the trace to a different location. To disable the trace completely the cmake switch TRACE_ENABLED must be disabled.

Each trace message is written with a level to indicate the severity of the message and a facility to assign the message to a component. Depending of the trace backend the trace messages may be prefixed with timestamps, the output can be colored, etc. See Trace Module for more general information about the different trace backends.

Macro Definition Documentation

◆ TRACE_FAC_SERVICECALL

#define TRACE_FAC_SERVICECALL (1 << 20)

Identifier for service call facility.

All service calls that are processed on session level are reported. An exception are channel services which don't reached the session code, but are processed in secure channel layer.

◆ TRACE_FAC_USERAPPLICATION

#define TRACE_FAC_USERAPPLICATION 65536

Reserved for the user application.

Not used in the SDK.

◆ TRACE_IPv4

#define TRACE_IPv4 ( x ) trace_ipv4(x)

See also: trace_ipv4

◆ TRACE_IPv6

#define TRACE_IPv6 ( x ) trace_ipv6(x)

See also: trace_ipv6

◆ TRACE_LEVEL_DATA

#define TRACE_LEVEL_DATA 2

Identifier for data trace level: logs process data (e.g.

read/written values)

◆ TRACE_LEVEL_DEFAULT

#define TRACE_LEVEL_DEFAULT (TRACE_LEVEL_ERROR | TRACE_LEVEL_WARNING | TRACE_LEVEL_NOTICE)

Default trace levels the should be used at runtime.

More levels are only needed for debugging.

◆ TRACE_LEVEL_ERROR

#define TRACE_LEVEL_ERROR 128

Identifier for error trace level: error conditions, e.g.

file access denied, out of memory, etc.

◆ TRACE_LEVEL_INFO

#define TRACE_LEVEL_INFO 4

Identifier for info trace level: informational (e.g.

app started, shutdown, connect, disconnect, subscription created, ...)

◆ TRACE_LEVEL_INSANE

#define TRACE_LEVEL_INSANE 256

Identifier for insane trace level, produces a lot of output! This is used for cyclic events.

◆ TRACE_LEVEL_NOTICE

#define TRACE_LEVEL_NOTICE 32

Identifier for notice trace level: normal but significant condition, e.g.

authentication denied

◆ TRACE_LEVEL_WARNING

#define TRACE_LEVEL_WARNING 64

Identifier for warning trace level.

e.g. the certificate may expire soon, only 1MB of memory left, etc.

◆ TRACE_PASSWORD

#define TRACE_PASSWORD ( x ) trace_password(x)

See also: trace_password

◆ TRACE_SECMASK_SHOW_ALL

#define TRACE_SECMASK_SHOW_ALL 7

Enables all sensitive information.

◆ TRACE_SECMASK_SHOW_IPADDRESS

#define TRACE_SECMASK_SHOW_IPADDRESS 4

Enables tracing of IP addresses.

If disabled the IP addresses will be traced anonymised. IPv4 anonymisation: Only the last host byte is written to be able to distinguish different hosts: "x.x.x.123" IPv6 anonymisation: Only the first and last word is visible to allow to see the type of address and to allow to distinguish hosts, without leaking the globally unique IPv6 address: e.g. "fe80:x:x:x:x:x:x:123" The default is off.

◆ TRACE_SECMASK_SHOW_PASSWORD

#define TRACE_SECMASK_SHOW_PASSWORD 2

Enables tracing of passwords.

If disabled the string "XXX" will be traced instead. The default is off.

◆ TRACE_SECMASK_SHOW_USERNAME

#define TRACE_SECMASK_SHOW_USERNAME 1

Enables tracing of usernames.

If disabled the string "<hidden>" will be traced instead. The default is off.

◆ TRACE_USERNAME

#define TRACE_USERNAME ( x ) trace_username(x)

See also: trace_username

Function Documentation

◆ trace_change_security_level()

TRACE_EXPORT int trace_change_security_level ( int security_mask )

Changes the security level of the trace output.

By default no sensitive information like username, passwords or IP addresses are written to the trace. The prevents accidental leakage of sensitive information if trace are sent to other people, e.g. to get support.

However you can enable tracing of sensitive information by calling this function and set the security_mask. Note that this only has the desired effect if all trace lines use the special trace macros which honor this security mask.

See also: TRACE_USERNAME; TRACE_PASSWORD; TRACE_IPv4; TRACE_IPv6

Parameters

security_mask Bitwise ORed TRACE_SECMASK_* values.

Returns: Zero on success, UA_EBADINVALIDARGUMENT if the mask is invalid.

◆ trace_change_trace_level()

TRACE_EXPORT int trace_change_trace_level	(	int	level_mask,
		int	facility_mask
	)

Change the trace level and facility.

Parameters

level_mask	New trace level mask.
facility_mask	New trace facility mask.

Returns: Zero on success or errorcode on failure

◆ trace_enabled()

TRACE_EXPORT int trace_enabled ( int level )

Test if a certain trace level is enabled.

Parameters

level Trace level to test.

Returns: Zero if the specified trace level is disabled

Test if a certain trace level is enabled.

If the trace level is disabled this function returns zero.

◆ trace_get_security_level()

TRACE_EXPORT int trace_get_security_level ( void )

Returns the current security level mask.

◆ trace_hexdump()

TRACE_EXPORT void TRACE_EXPORT void trace_hexdump	(	int	level,
		int	facility,
		const unsigned char *	data,
		size_t	count
	)

Writes the hexdump of the given data to trace output.

Parameters

level	Level to trace to.
facility	Facility to trace to.
data	Pointer to data which should be dumped.
count	Length of data in bytes.

◆ trace_ipv4()

TRACE_EXPORT const char* trace_ipv4 ( const unsigned char ipv4[4] )

Returns the string representation of the given IPv4 address if TRACE_SECMASK_SHOW_IPADDRESS is set, otherwise an anonymised version of it.

You should used the macro TRACE_IPv6 instead of calling this function directly.

Example usage:

char ipv4[4];

TRACE_DEBUG(TRACE_FAC_APPLICATION, "New connection from IP %s.\n", TRACE_IPv4(ipv4));

◆ trace_ipv6()

TRACE_EXPORT const char* trace_ipv6 ( const unsigned char ipv6[16] )

Returns the string representation of the given IPv6 address if TRACE_SECMASK_SHOW_IPADDRESS is set, otherwise an anonymised version of it.

You should used the macro TRACE_IPv6 instead of calling this function directly.

Example usage:

char ipv6[16];

TRACE_DEBUG(TRACE_FAC_APPLICATION, "New connection from IP %s.\n", TRACE_IPv6(ipv6));

◆ trace_log()

TRACE_EXPORT void trace_log	(	int	level,
		int	facility,
		const char *	format,
			...
	)

Write to trace.

Parameters

level	Level to trace to.
facility	Facility to trace to.
format	Format specifier like for printf().

◆ trace_openlog()

TRACE_EXPORT int trace_openlog	(	int	level_mask,
		int	facility_mask
	)

Initialize the trace backend.

Parameters

level_mask	Bitwise OR of trace levels to trace.
facility_mask	Bitwise OR of trace facilities to trace.

Returns: Zero on success or errorcode on failure

◆ trace_parse_trace_facility()

TRACE_EXPORT int trace_parse_trace_facility ( char * args )

Parse a numeric or textual representation of trace facilities.

This function is indented for main applications which need to parse command line arguments using getopt().

The function is able to parse three different variants:

The argument can be a number like e.g. "160" = 32 (MEMORY) + 128 (ENCODER). This is backwards compatible to previous implementations.
The argument can be a hex number like e.g. "0xa0".
The argument can be a comma separated string of trace faciliies like e.g. "memory,encoder". The string comparison is performed case insensitive.

◆ trace_parse_trace_level()

TRACE_EXPORT int trace_parse_trace_level ( char * args )

Parse a numeric or textual representation of trace levels.

This function is indented for main applications which need to parse command line arguments using getopt().

The function is able to parse three different variants:

The argument can be a number like e.g. "6" = 4 (DATA) + 2 (INFO). This is backwards compatible to previous implementations.
The argument can be a hex number like e.g. "0x6".
The argument can be a comma separated string of trace levels like e.g. "data,info". The string comparison is performed case insensitive.

◆ trace_password()

TRACE_EXPORT const char* trace_password ( const char * password )

Returns the password as-is if TRACE_SECMASK_SHOW_PASSWORD is set, otherwise the string "XXX".

You should used the macro TRACE_PASSWORD instead of calling this function directly.

Example usage:

void user_logon(const char *username, const char *password)
{
    TRACE_DEBUG(TRACE_FAC_APPLICATION, "The user '%s' identified itself with password '%s'.\n", TRACE_USERNAME(username), TRACE_PASSWORD(password));
}

◆ trace_print_flags()

TRACE_EXPORT void trace_print_flags ( const char * appname )

Prints the available trace flags.

This function is used by many example applications to avoid replicating the same code in many different locations and to keep it consistent with trace.h.

◆ trace_username()

TRACE_EXPORT const char* trace_username ( const char * username )

Returns the username as-is if TRACE_SECMASK_SHOW_USERNAME is set, otherwise the string "<hidden>".

You should used the macro TRACE_USERNAME instead of calling this function directly.

Example usage:

void user_logon(const char *username, const char *password)
{
    TRACE_DEBUG(TRACE_FAC_APPLICATION, "The user '%s' identified itself with password '%s'.\n", TRACE_USERNAME(username), TRACE_PASSWORD(password));
}

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ TRACE_FAC_SERVICECALL

◆ TRACE_FAC_USERAPPLICATION

◆ TRACE_IPv4

◆ TRACE_IPv6

◆ TRACE_LEVEL_DATA

◆ TRACE_LEVEL_DEFAULT

◆ TRACE_LEVEL_ERROR

◆ TRACE_LEVEL_INFO

◆ TRACE_LEVEL_INSANE

◆ TRACE_LEVEL_NOTICE

◆ TRACE_LEVEL_WARNING

◆ TRACE_PASSWORD

◆ TRACE_SECMASK_SHOW_ALL

◆ TRACE_SECMASK_SHOW_IPADDRESS

◆ TRACE_SECMASK_SHOW_PASSWORD

◆ TRACE_SECMASK_SHOW_USERNAME

◆ TRACE_USERNAME

Function Documentation

◆ trace_change_security_level()

◆ trace_change_trace_level()

◆ trace_enabled()

◆ trace_get_security_level()

◆ trace_hexdump()

◆ trace_ipv4()

◆ trace_ipv6()

◆ trace_log()

◆ trace_openlog()

◆ trace_parse_trace_facility()

◆ trace_parse_trace_level()

◆ trace_password()

◆ trace_print_flags()

◆ trace_username()