Tracing

Functions for tracing. More...

Files
file	influxdb.h
	Structures and functions supporting interaction with InfluxDB.
file	trace.h
	API for the tracing module that records runtime events for debugging and analysis.
file	trace_types.h
	Definitions that are needed by both implementors and callers of the trace API regardless of whether tracing is enabled at compile time.
file	trace_util.h
	Header file for common utilities used in converting Lingua Franca trace files into other formats.

Data Structures
struct	influx_client_t
	InfluxDB client. More...
struct	influx_v2_client_t
	InfluxDB v2 client. More...
struct	trace_record_nodeps_t
	Trace record without dependencies. More...

Macros
#define	_LF_TRACE_FAILURE(trace_file)
	Macro to use when access to trace file fails.
#define	BUFFER_SIZE   1024
	Buffer size for reading object descriptions.

Typedefs
typedef struct influx_client_t	influx_client_t
	InfluxDB client.
typedef struct influx_v2_client_t	influx_v2_client_t
	InfluxDB v2 client.
typedef struct object_description_t	object_description_t
	Struct for table of pointers to a description of the object.

Enumerations
enum	_lf_trace_object_t { trace_reactor , trace_trigger , trace_user }
	Identifier for what is in the object table. More...
enum	trace_event_t {   reaction_starts , reaction_ends , reaction_deadline_missed , schedule_called ,   user_event , user_value , worker_wait_starts , worker_wait_ends ,   scheduler_advancing_time_starts , scheduler_advancing_time_ends , federated , send_ACK ,   send_FAILED , send_TIMESTAMP , send_NET , send_LTC ,   send_STOP_REQ , send_STOP_REQ_REP , send_STOP_GRN , send_FED_ID ,   send_PTAG , send_TAG , send_REJECT , send_RESIGN ,   send_PORT_ABS , send_CLOSE_RQ , send_TAGGED_MSG , send_P2P_TAGGED_MSG ,   send_MSG , send_P2P_MSG , send_ADR_AD , send_ADR_QR ,   send_DNET , receive_ACK , receive_FAILED , receive_TIMESTAMP ,   receive_NET , receive_LTC , receive_STOP_REQ , receive_STOP_REQ_REP ,   receive_STOP_GRN , receive_FED_ID , receive_PTAG , receive_TAG ,   receive_REJECT , receive_RESIGN , receive_PORT_ABS , receive_CLOSE_RQ ,   receive_TAGGED_MSG , receive_P2P_TAGGED_MSG , receive_MSG , receive_P2P_MSG ,   receive_ADR_AD , receive_ADR_QR , receive_DNET , receive_UNIDENTIFIED ,   NUM_EVENT_TYPES }
	Trace event types. More...

Functions
int	format_line (char **buf, int *len, size_t used,...)
	Format a line for InfluxDB.
char *	get_object_description (void *reactor, int *index)
	Get the description of the object pointed to by the specified pointer.
char *	get_trigger_name (void *trigger, int *index)
	Get the trigger name for the specified pointer.
void	lf_tracing_global_init (char *process_name, char *process_names, int process_id, int max_num_local_threads)
	Initialize the tracing module.
void	lf_tracing_global_shutdown ()
	Shut down the tracing module.
void	lf_tracing_register_trace_event (object_description_t description)
	Register a kind of trace event.
void	lf_tracing_set_start_time (int64_t start_time)
	Give the tracing module access to the start time.
void	lf_tracing_tracepoint (int worker, trace_record_nodeps_t *tr)
	Submit a tracepoint from the given worker to the tracing module.
const version_t *	lf_version_tracing ()
	Return a description of the compile-time properties of the current plugin.
FILE *	open_file (const char *path, const char *mode)
	Open the specified file for reading or writing.
int	post_curl (influx_v2_client_t *c,...)
	Post a line to InfluxDB via HTTP.
int	post_http (influx_client_t *c,...)
	Post a line to InfluxDB via HTTP.
int	post_http_send_line (influx_client_t *c, char *buf, int len)
	Post a line to InfluxDB via HTTP.
void	print_table ()
	Print the object to description table.
size_t	read_header ()
	Read header information.
int	read_trace ()
	Read the trace from the trace_file and put it in the trace global variable.
char *	root_name (const char *path)
	Return the root file name from the given path.
int	send_udp (influx_client_t *c,...)
	Send a line to InfluxDB via UDP.
int	send_udp_line (influx_client_t *c, char *line, int len)
	Send a line to InfluxDB via UDP.
void	usage ()
	Print a usage message.

Variables
static const char *	trace_event_names []
	String description of event types.

Detailed Description

Functions for tracing.

This group contains functions for tracing. Tracing is described in the Lingua Franca handbook.

Macro Definition Documentation

_LF_TRACE_FAILURE

#define _LF_TRACE_FAILURE

(

trace_file

)

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Value:

  do {                                                                                                                 \
    fprintf(stderr, "ERROR: Access to trace file failed.\n");                                                          \
    fclose(trace_file);                                                                                                \
    trace_file = NULL;                                                                                                 \
    exit(1);                                                                                                           \
  } while (0)

Macro to use when access to trace file fails.

BUFFER_SIZE

#define BUFFER_SIZE   1024

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Buffer size for reading object descriptions.

Typedef Documentation

influx_client_t

typedef struct influx_client_t influx_client_t

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

InfluxDB client.

influx_v2_client_t

typedef struct influx_v2_client_t influx_v2_client_t

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

InfluxDB v2 client.

object_description_t

typedef struct object_description_t object_description_t

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Struct for table of pointers to a description of the object.

Enumeration Type Documentation

_lf_trace_object_t

enum _lf_trace_object_t

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Identifier for what is in the object table.

Enumerator
trace_reactor	A reactor instance, identified by its self struct pointer.
trace_trigger	A trigger (timer or action), identified by its trigger pointer.
trace_user	A user-defined trace object.

trace_event_t

enum trace_event_t

#include </Users/runner/work/reactor-c/reactor-c/trace/api/types/trace_types.h>

Trace event types.

If you update this, be sure to update the string representation below. Also, create a tracepoint function for each event type.

Enumerator
reaction_starts
reaction_ends
reaction_deadline_missed
schedule_called
user_event
user_value
worker_wait_starts
worker_wait_ends
scheduler_advancing_time_starts
scheduler_advancing_time_ends
federated
send_ACK
send_FAILED
send_TIMESTAMP
send_NET
send_LTC
send_STOP_REQ
send_STOP_REQ_REP
send_STOP_GRN
send_FED_ID
send_PTAG
send_TAG
send_REJECT
send_RESIGN
send_PORT_ABS
send_CLOSE_RQ
send_TAGGED_MSG
send_P2P_TAGGED_MSG
send_MSG
send_P2P_MSG
send_ADR_AD
send_ADR_QR
send_DNET
receive_ACK
receive_FAILED
receive_TIMESTAMP
receive_NET
receive_LTC
receive_STOP_REQ
receive_STOP_REQ_REP
receive_STOP_GRN
receive_FED_ID
receive_PTAG
receive_TAG
receive_REJECT
receive_RESIGN
receive_PORT_ABS
receive_CLOSE_RQ
receive_TAGGED_MSG
receive_P2P_TAGGED_MSG
receive_MSG
receive_P2P_MSG
receive_ADR_AD
receive_ADR_QR
receive_DNET
receive_UNIDENTIFIED
NUM_EVENT_TYPES

Function Documentation

format_line()

int format_line	(	char **	buf,
		int *	len,
		size_t	used,
			... )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

Format a line for InfluxDB.

Parameters

buf	Returned pointer to the formatted line.
len	Returned length of the formatted line.
used	Number of bytes used in the formatted line.
...	Formatting arguments.

Returns

int 0 on success, -1 on failure.

get_object_description()

char * get_object_description	(	void *	reactor,
		int *	index )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Get the description of the object pointed to by the specified pointer.

For example, this can be the name of a reactor (pointer points to the self struct) or a user-defined string. If there is no such pointer in the symbol table, return NULL. If the index argument is non-null, then put the index of the entry in the table into the int pointed to or -1 if none was found.

Parameters

reactor	The pointer to to an object, e.g. a self struct.
index	An optional pointer into which to write the index.

Returns

The description of the object or NULL if not found.

get_trigger_name()

char * get_trigger_name	(	void *	trigger,
		int *	index )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Get the trigger name for the specified pointer.

If there is no such trigger, return NULL. If the index argument is non-null, then put the index of the trigger in the table into the int pointed to or -1 if none was found.

Parameters

trigger	The pointer to a trigger struct.
index	An optional pointer into which to write the index.

Returns

The name of the trigger or NULL if not found.

lf_tracing_global_init()

void lf_tracing_global_init	(	char *	process_name,
		char *	process_names,
		int	process_id,
		int	max_num_local_threads )

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Initialize the tracing module.

Calling other API functions before calling this procedure is undefined behavior.

Parameters

process_name	The name of the current federate, or a placeholder if this is not a federate.
process_names	The names of all federates, separated by commas, or NULL if that information is not available.
process_id	The ID of the current federate, or -1 if this is the RTI. 0 if unfederated.
max_num_local_threads	An upper bound on the number of threads created by this process.

lf_tracing_global_shutdown()

void lf_tracing_global_shutdown

(

)

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Shut down the tracing module.

Calling other API functions after calling this procedure is undefined behavior.

lf_tracing_register_trace_event()

void lf_tracing_register_trace_event

(

object_description_t

description

)

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Register a kind of trace event.

This should be called before tracepoints are reached.

Parameters

description

A description of some trace events which may be received in the future. This may be invoked after many tracepoints have already been recorded but should be invoked early.

lf_tracing_set_start_time()

void lf_tracing_set_start_time

(

int64_t

start_time

)

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Give the tracing module access to the start time.

This may be invoked after many tracepoints have already been recorded but should be invoked early.

lf_tracing_tracepoint()

void lf_tracing_tracepoint	(	int	worker,
		trace_record_nodeps_t *	tr )

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Submit a tracepoint from the given worker to the tracing module.

lf_version_tracing()

const version_t * lf_version_tracing

(

)

#include </Users/runner/work/reactor-c/reactor-c/trace/api/trace.h>

Return a description of the compile-time properties of the current plugin.

open_file()

FILE * open_file	(	const char *	path,
		const char *	mode )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Open the specified file for reading or writing.

This function records the file for closing at termination.

Parameters

path	The path to the file.
mode	"r" for reading and "w" for writing.

Returns

A pointer to the open file or NULL for failure.

post_curl()

int post_curl	(	influx_v2_client_t *	c,
			... )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

Post a line to InfluxDB via HTTP.

Parameters

c	InfluxDB v2 client.
...	Formatting arguments.

Returns

int 0 on success, -1 on failure.

post_http()

int post_http	(	influx_client_t *	c,
			... )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

Post a line to InfluxDB via HTTP.

Parameters

c	InfluxDB client.
...	Formatting arguments.

Returns

int 0 on success, -1 on failure.

post_http_send_line()

int post_http_send_line	(	influx_client_t *	c,
		char *	buf,
		int	len )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

Post a line to InfluxDB via HTTP.

Parameters

c	InfluxDB client.
buf	Pointer to the line to post.
len	Length of the line to post.

Returns

int 0 on success, -1 on failure.

print_table()

void print_table

(

)

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Print the object to description table.

read_header()

size_t read_header

(

)

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Read header information.

Returns

The number of objects in the object table or -1 for failure.

read_trace()

int read_trace

(

)

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Read the trace from the trace_file and put it in the trace global variable.

Returns

The number of trace records read or 0 upon seeing an EOF.

root_name()

char * root_name

(

const char *

path

)

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Return the root file name from the given path.

Given a path to a file, this function returns a dynamically allocated string (which you must free) that points to the root filename without the preceding path and without the file extension.

Parameters

path	The path including the full filename.

Returns

The root name of the file or NULL for failure.

send_udp()

int send_udp	(	influx_client_t *	c,
			... )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

Send a line to InfluxDB via UDP.

Parameters

c	InfluxDB client.
...	Formatting arguments.

Returns

int 0 on success, -1 on failure.

send_udp_line()

int send_udp_line	(	influx_client_t *	c,
		char *	line,
		int	len )

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/influxdb.h>

Send a line to InfluxDB via UDP.

Parameters

c	InfluxDB client.
line	Pointer to the line to send.
len	Length of the line to send.

Returns

int 0 on success, -1 on failure.

usage()

void usage

(

)

#include </Users/runner/work/reactor-c/reactor-c/util/tracing/trace_util.h>

Print a usage message.

Variable Documentation

trace_event_names

const char* trace_event_names[]

static

#include </Users/runner/work/reactor-c/reactor-c/trace/api/types/trace_types.h>

Initial value:

= {
    "Reaction starts",
    "Reaction ends",
    "Reaction deadline missed",
    "Schedule called",
    "User-defined event",
    "User-defined valued event",
    "Worker wait starts",
    "Worker wait ends",
    "Scheduler advancing time starts",
    "Scheduler advancing time ends",
    "Federated marker",
    
    "Sending ACK",
    "Sending FAILED",
    "Sending TIMESTAMP",
    "Sending NET",
    "Sending LTC",
    "Sending STOP_REQ",
    "Sending STOP_REQ_REP",
    "Sending STOP_GRN",
    "Sending FED_ID",
    "Sending PTAG",
    "Sending TAG",
    "Sending REJECT",
    "Sending RESIGN",
    "Sending PORT_ABS",
    "Sending CLOSE_RQ",
    "Sending TAGGED_MSG",
    "Sending P2P_TAGGED_MSG",
    "Sending MSG",
    "Sending P2P_MSG",
    "Sending ADR_AD",
    "Sending ADR_QR",
    "Sending DNET",
    
    "Receiving ACK",
    "Receiving FAILED",
    "Receiving TIMESTAMP",
    "Receiving NET",
    "Receiving LTC",
    "Receiving STOP_REQ",
    "Receiving STOP_REQ_REP",
    "Receiving STOP_GRN",
    "Receiving FED_ID",
    "Receiving PTAG",
    "Receiving TAG",
    "Receiving REJECT",
    "Receiving RESIGN",
    "Receiving PORT_ABS",
    "Receiving CLOSE_RQ",
    "Receiving TAGGED_MSG",
    "Receiving P2P_TAGGED_MSG",
    "Receiving MSG",
    "Receiving P2P_MSG",
    "Receiving ADR_AD",
    "Receiving ADR_QR",
    "Receiving DNET",
    "Receiving UNIDENTIFIED",
}

String description of event types.