YAC: YAC Performance Analysis Kit (YAC PAK)

Searching...

No Matches

Lightweight per-rank event tracing tool. More...

Macros
#define	YAC_PAK_VERSION_MAJOR 0

#define	YAC_PAK_VERSION_MINOR 1

#define	YAC_PAK_VERSION_PATCH 2

#define	YAC_PAK_VERSION_STRING "0.1.2"

Enumerations
enum	yac_pak_event_type_t { YAC_PAK_EVENT_TYPE_INIT = 0 , YAC_PAK_EVENT_TYPE_DEF_COMP , YAC_PAK_EVENT_TYPE_SYNC_DEF , YAC_PAK_EVENT_TYPE_ENDDEF , YAC_PAK_EVENT_TYPE_FINALIZE , YAC_PAK_EVENT_TYPE_GET , YAC_PAK_EVENT_TYPE_AGET , YAC_PAK_EVENT_TYPE_PUT , YAC_PAK_EVENT_TYPE_REGION , YAC_PAK_EVENT_TYPE_UPDATE , YAC_PAK_EVENT_TYPE_WAIT }
	Event type for YAC PAK trace entries. Defines the type of events that can be recorded in YAC PAK traces. More...

enum	yac_pak_trace_level_t { YAC_PAK_TRACE_LEVEL_OFF = 0 , YAC_PAK_TRACE_LEVEL_COUPLING = 1 , YAC_PAK_TRACE_LEVEL_REGIONS = 2 , YAC_PAK_TRACE_LEVEL_MAX = YAC_PAK_TRACE_LEVEL_REGIONS }
	YAC PAK coupling trace level. More...

Functions
struct yac_pak *	yac_pak_new (MPI_Comm comm, int capacity)
	Construct a new YAC PAK object.

void	yac_pak_delete (struct yac_pak *pak)
	Destroy a YAC PAK object.

int	yac_pak_register (struct yac_pak pak, char const name)
	Register a named timer.

int	yac_pak_start (struct yac_pak *pak, int idx)
	Start a registered timer.

int	yac_pak_stop (struct yac_pak *pak, int idx)
	Stop a registered timer.

int	yac_pak_report (struct yac_pak pak, FILE out)
	Generate collective timer report.

int	yac_pak_trace_is_enabled (struct yac_pak const *pak)
	Event tracing support.

int	yac_pak_setup_trace_is_enabled (struct yac_pak const *pak)
	Check whether setup-phase tracing is active.

int	yac_pak_trace_stop (struct yac_pak *pak, int handle)
	Stop a trace event.

int	yac_pak_flush_trace (struct yac_pak *pak)
	Flush trace data to disk.

int	yac_pak_trace_start_ex (struct yac_pak pak, char const field, char const component, char const grid, yac_pak_event_type_t type, int put_idx, char const *datetime, int action, yac_pak_trace_level_t level)
	Start a trace event with full metadata.

int	yac_pak_region_trace_is_enabled (struct yac_pak const *pak, yac_pak_trace_level_t level)
	Check whether region events at a given trace level will be recorded.

int	yac_pak_trace_start_setup (struct yac_pak pak, char const name, yac_pak_event_type_t type)
	Setup-phase event tracing.

int	yac_pak_trace_record (struct yac_pak pak, char const field, char const component, char const grid, yac_pak_event_type_t type, double tstart, double tend)
	Record a complete trace entry with explicit timestamps.

char const *	yac_pak_get_config_output_path (struct yac_pak const *pak)
	Return the coupling configuration output file path if enabled.

void	yac_pak_set_component (struct yac_pak pak, char const comp_name, int comp_rank, int comp_size)
	Set the component this process belongs to.

Detailed Description

Lightweight per-rank event tracing tool.

YAC PAK provides tools for event tracing, detecting load imbalances and performance analysis. It supports:

Per-rank event timeline recording
Coupling operation tracing with metadata
Setup-phase event tracking
Named timer registration and reporting (TODO: expand and test)

All interface routines take a struct yac_pak pointer as their first argument. Passing NULL is safe and results in a no-op.

For usage details, see YAC PAK Tracing Guide.

Macro Definition Documentation

◆ YAC_PAK_VERSION_MAJOR

#define YAC_PAK_VERSION_MAJOR 0

YAC PAK version; independent of the YAC library version.

Definition at line 36 of file yac_pak.h.

◆ YAC_PAK_VERSION_MINOR

#define YAC_PAK_VERSION_MINOR 1

Definition at line 37 of file yac_pak.h.

◆ YAC_PAK_VERSION_PATCH

#define YAC_PAK_VERSION_PATCH 2

Definition at line 38 of file yac_pak.h.

◆ YAC_PAK_VERSION_STRING

#define YAC_PAK_VERSION_STRING "0.1.2"

Definition at line 39 of file yac_pak.h.

Enumeration Type Documentation

◆ yac_pak_event_type_t

enum yac_pak_event_type_t

Event type for YAC PAK trace entries. Defines the type of events that can be recorded in YAC PAK traces.

Enumerator
YAC_PAK_EVENT_TYPE_INIT
YAC_PAK_EVENT_TYPE_DEF_COMP
YAC_PAK_EVENT_TYPE_SYNC_DEF
YAC_PAK_EVENT_TYPE_ENDDEF
YAC_PAK_EVENT_TYPE_FINALIZE
YAC_PAK_EVENT_TYPE_GET
YAC_PAK_EVENT_TYPE_AGET
YAC_PAK_EVENT_TYPE_PUT
YAC_PAK_EVENT_TYPE_REGION
YAC_PAK_EVENT_TYPE_UPDATE
YAC_PAK_EVENT_TYPE_WAIT

Definition at line 48 of file yac_pak.h.

◆ yac_pak_trace_level_t

enum yac_pak_trace_level_t

YAC PAK coupling trace level.

The value of YAC_PAK_TRACE_LEVEL and equivalently the category of a coupling event, are gated together (event level <= setting). It is a coarse level, not a nesting depth (nesting depth is separate and unbounded). Setup-phase events are gated separately by YAC_PAK_TRACE_SETUP, independent of this level (see yac_pak_trace_start_ex).

Enumerator
YAC_PAK_TRACE_LEVEL_OFF	no coupling events
YAC_PAK_TRACE_LEVEL_COUPLING	PUT/GET/AGET/UPDATE/WAIT events.
YAC_PAK_TRACE_LEVEL_REGIONS	nested instrumented-region events
YAC_PAK_TRACE_LEVEL_MAX	highest level

Definition at line 71 of file yac_pak.h.

Function Documentation

◆ yac_pak_delete()

void yac_pak_delete ( struct yac_pak * pak )

Destroy a YAC PAK object.

Frees all allocated memory and flushes pending traces (if autoflush is enabled). Safe to call with NULL.

Parameters

[in] pak YAC PAK object to destroy (may be NULL)

Note: Must be called before MPI_Finalize()

Definition at line 847 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_flush_trace()

int yac_pak_flush_trace ( struct yac_pak * pak )

Flush trace data to disk.

Writes accumulated trace events to per-rank CSV files in the configured output directory. Each rank that passes the stride gate writes independently (not collective). Rank 0 always writes and additionally generates trace_metadata.json.

After flushing, the local event buffer is cleared and can be reused.

Parameters

[in] pak YAC PAK object (no-op if NULL)

Returns: 0 on success, -1 if tracing was never initialized

Note: Independent operation, each rank writes its own file; Rank 0 writes additional metadata file

Definition at line 1092 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_get_config_output_path()

char const * yac_pak_get_config_output_path ( struct yac_pak const * pak )

Return the coupling configuration output file path if enabled.

Return coupling configuration file output path when YAC_PAK_TRACE=1 and YAC_PAK_TRACE_CONFIG=1 are both set. Otherwise NULL is returned. The returned string is owned by the YAC PAK object and must not be freed by the caller.

Parameters

[in] pak YAC PAK object (returns NULL if NULL)

Returns: Path string if config output is enabled, NULL otherwise

Definition at line 925 of file yac_pak.c.

Here is the caller graph for this function:

◆ yac_pak_new()

struct yac_pak * yac_pak_new	(	MPI_Comm	comm,
		int	capacity )

Construct a new YAC PAK object.

Allocates and initialises the performance analysis infrastructure.

Parameters

[in]	comm	MPI communicator to use (must not be MPI_COMM_NULL)
[in]	capacity	Event buffer capacity (if > 0, overrides YAC_PAK_TRACE_CAPACITY environment variable)

Returns: Pointer to the new object, or NULL if tracing is disabled

Note: This is collective on the provided communicator; Returns NULL unless YAC_PAK_TRACE=1

Definition at line 737 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_region_trace_is_enabled()

int yac_pak_region_trace_is_enabled	(	struct yac_pak const *	pak,
		yac_pak_trace_level_t	level )

Check whether region events at a given trace level will be recorded.

Lets callers skip setting up region instrumentation when the resulting events would be discarded anyway.

Parameters

[in]	pak	YAC PAK object (returns 0 if NULL)
[in]	level	Event category (see yac_pak_trace_level_t), e.g. YAC_PAK_TRACE_LEVEL_REGIONS

Returns: Non-zero if a yac_pak_trace_start_ex call with the same level would be recorded, 0 otherwise

Definition at line 913 of file yac_pak.c.

Here is the caller graph for this function:

◆ yac_pak_register()

int yac_pak_register	(	struct yac_pak *	pak,
		char const *	name )

Registers a new performance timer. Must be called collectively on all ranks in the same order to ensure consistent timer indices (TODO: expand and test).

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	name	Name of the timer (will be duplicated internally)

Returns: Timer index (>= 0) on success, -1 on error or if pak is NULL

Note: Collective operation, all ranks must call with the same name in the same order

Definition at line 1151 of file yac_pak.c.

Here is the call graph for this function:

◆ yac_pak_report()

int yac_pak_report	(	struct yac_pak *	pak,
		FILE *	out )

Generate collective timer report.

Computes and prints global statistics (sum, min, max, average, count) for all registered timers. Output is written by rank 0 only (TODO: expand and test).

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	out	Output stream (uses stdout if NULL)

Returns: 0 on success, -1 on error or if pak is NULL

Note: Collective operation on the communicator used at construction

Definition at line 1181 of file yac_pak.c.

◆ yac_pak_set_component()

void yac_pak_set_component	(	struct yac_pak *	pak,
		char const *	comp_name,
		int	comp_rank,
		int	comp_size )

Set the component this process belongs to.

Called once the components are known. Name, rank and size are set together, so that the trace file name and YAC_PAK_TRACE_STRIDE always refer to the same component. May be called only once and has to be called before any traced event that carries a component name.

Without this call the component name is taken from the first traced event that carries one (yac_pak_unknown if there is none) and the stride is applied within the communicator.

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	comp_name	Name of the component (non-empty)
[in]	comp_rank	Rank within the component
[in]	comp_size	Number of ranks of the component

Note: Local operation

Definition at line 929 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_setup_trace_is_enabled()

int yac_pak_setup_trace_is_enabled ( struct yac_pak const * pak )

Check whether setup-phase tracing is active.

Returns non-zero only when both the main trace flag (YAC_PAK_TRACE=1) and the setup flag (YAC_PAK_TRACE_SETUP=1) are set. Use this as the guard for level-0 (setup-phase) trace calls such as those in yac_cinit, yac_cdef_comp, yac_csync_def, yac_cenddef, and yac_cfinalize.

Parameters

[in] pak YAC PAK object (returns 0 if NULL)

Returns: Non-zero if setup-phase tracing is enabled, 0 otherwise

Definition at line 909 of file yac_pak.c.

Here is the caller graph for this function:

◆ yac_pak_start()

int yac_pak_start	(	struct yac_pak *	pak,
		int	idx )

Start a registered timer.

Starts timing for a previously registered timer. Local operation (TODO: expand and test).

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	idx	Timer index returned by yac_pak_register()

Returns: 0 on success, -1 on error or if pak is NULL

Definition at line 1162 of file yac_pak.c.

◆ yac_pak_stop()

int yac_pak_stop	(	struct yac_pak *	pak,
		int	idx )

Stop a registered timer.

Stops timing for a running timer and accumulates the elapsed time. Local operation (TODO: expand and test).

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	idx	Timer index returned by yac_pak_register()

Returns: 0 on success, -1 if timer was not running or index is invalid

Definition at line 1170 of file yac_pak.c.

◆ yac_pak_trace_is_enabled()

int yac_pak_trace_is_enabled ( struct yac_pak const * pak )

Event tracing support.

YAC PAK can record detailed per-rank event timelines for coupling operations. Traces include field name, component, grid, event type, timestamps, and coupling metadata.

Environment Variables (all optional)

YAC_PAK_TRACE=0|1: Enable tracing (default: 0)
YAC_PAK_TRACE_LEVEL=0|1|2: Coupling trace level (default: 1). Level 0 records no coupling events (setup-phase events are still recorded if YAC_PAK_TRACE_SETUP=1); level 1 records PUT/GET/AGET/UPDATE/WAIT; level 2 additionally records nested interpolation/compute regions (and any deeper nesting).
YAC_PAK_TRACE_SETUP=0|1: Additionally record lifecycle events (INIT, DEF_COMP, SYNC_DEF, ENDDEF, FINALIZE) together with the setup-phase regions (distributed grid pair generation, process sphere part generation) (default: 0)
YAC_PAK_TRACE_CAPACITY=<n>: In-memory event buffer size per rank (default: 4096). Buffer grows automatically; aborts on OOM.
YAC_PAK_TRACE_DIR=<path>: Output directory (default: auto-generated as traces_YYYYMMDD_HHMMSS_N<number_of_processes>_v<YAC_PAK_VERSION>/)
YAC_PAK_TRACE_STRIDE=<n>: Write only every n-th rank of each component, counted within the component (default: 1, the first rank of every component always writes)
YAC_PAK_TRACE_FLUSH_TIME=0|1: Include flush_duration_s in trace metadata (default: 1)
YAC_PAK_TRACE_AUTOFLUSH=0|1: Automatically flush traces at finalize (default: 1)
YAC_PAK_TRACE_CONFIG=0|1: Store coupling configuration in trace (default: 0) (requires YAC_PAK_TRACE=1)
YAC_PAK_TRACE_WRITE_MODE=at_finalize|instant: When event rows are written (default: at_finalize). instant writes each event as it ends and lists the events in progress in <component>_r<rank>.open.
YAC_PAK_TRACE_VERBOSE=0|1: Print progress messages (trace directory, files written) to stderr (default: 0)

Output Format

Each rank writes a CSV file: <dir>/<component>_r<rank>.csv

Rank 0 additionally writes trace_metadata.json with run-level information.

Query tracing status

Checks whether event tracing is currently enabled.

Parameters

[in] pak YAC PAK object (returns 0 if NULL)

Returns: Non-zero if tracing is enabled, 0 otherwise

Definition at line 905 of file yac_pak.c.

Here is the caller graph for this function:

◆ yac_pak_trace_record()

int yac_pak_trace_record	(	struct yac_pak *	pak,
		char const *	field,
		char const *	component,
		char const *	grid,
		yac_pak_event_type_t	type,
		double	tstart,
		double	tend )

Record a complete trace entry with explicit timestamps.

Records a trace event with pre-determined start and end times. Useful for tracing operations where timing needs to be captured before the YAC PAK object's trace buffers are fully set up (INIT event).

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	field	Name of the field or operation (may be NULL)
[in]	component	Component name (may be NULL)
[in]	grid	Grid name (may be NULL)
[in]	type	Event type (e.g. `YAC_PAK_EVENT_TYPE_INIT`)
[in]	tstart	Start timestamp (MPI_Wtime())
[in]	tend	End timestamp (MPI_Wtime())

Returns: 0 on success, -1 if tracing is not enabled or on error

Note: No-op if tracing (setup or coupling) is not enabled

Definition at line 979 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_trace_start_ex()

int yac_pak_trace_start_ex	(	struct yac_pak *	pak,
		char const *	field,
		char const *	component,
		char const *	grid,
		yac_pak_event_type_t	type,
		int	put_idx,
		char const *	datetime,
		int	action,
		yac_pak_trace_level_t	level )

Start a trace event with full metadata.

Records the start of a coupling or setup event with detailed metadata. Returns a handle for later use with yac_pak_trace_stop().

Parameters

[in]	pak	YAC PAK object (returns -1 if NULL)
[in]	field	Name of the field being communicated (may be NULL)
[in]	component	Component name (may be NULL)
[in]	grid	Grid name (may be NULL)
[in]	type	Event type ("PUT", "GET", "AGET", "UPDATE", "WAIT", "REGION", "INIT", "DEF_COMP", "SYNC_DEF", "ENDDEF", "FINALIZE")
[in]	put_idx	Per-put index for source operations (-1 for GET or aggregated PUT; TODO: implement when needed)
[in]	datetime	ISO 8601 datetime string of the coupling step (may be NULL). For WAIT this is the step of the exchange being completed, not the current one.
[in]	action	Coupling action as integer (0=NONE, 1=REDUCTION, 2=COUPLING, 3=RESTART, -1=unknown)
[in]	level	Coupling level of the event (see yac_pak_trace_level_t), recorded when `level` <= YAC_PAK_TRACE_LEVEL. Ignored for setup-phase event types (INIT, DEF_COMP, SYNC_DEF, ENDDEF, FINALIZE; gated by YAC_PAK_TRACE_SETUP).

Returns: Event handle (>= 0) on success, -1 if disabled or on error

Note: Setup traces require YAC_PAK_TRACE=1 and YAC_PAK_TRACE_SETUP=1; Coupling traces require YAC_PAK_TRACE=1 and level <= YAC_PAK_TRACE_LEVEL; setting YAC_PAK_TRACE_LEVEL=2 records level-2 (nested) events in addition to level-1 events.

Definition at line 1017 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_trace_start_setup()

int yac_pak_trace_start_setup	(	struct yac_pak *	pak,
		char const *	name,
		yac_pak_event_type_t	type )

Setup-phase event tracing.

Setup-phase tracing records YAC lifecycle events: INIT, DEF_COMP, SYNC_DEF, ENDDEF, FINALIZE. Controlled by the YAC_PAK_TRACE_SETUP environment variable.

Setup traces:

Require YAC_PAK_TRACE=1
Are activated when YAC_PAK_TRACE_SETUP=1
Use level=0 in yac_pak_trace_start_ex()

Start a setup-phase trace event

Convenience wrapper around yac_pak_trace_start_ex() for setup-phase events (level=0). Setup events carry no field, grid, component, put_idx, or datetime; this function fills those with the appropriate NULL/-1 defaults so callers need not repeat them.

Parameters

[in]	pak	YAC PAK object (returns -1 if NULL)
[in]	name	Operation name (e.g. `"yac_enddef"`)
[in]	type	Event type (e.g. `YAC_PAK_EVENT_TYPE_ENDDEF`)

Returns: Event handle (>=0) on success, -1 if disabled or on error

Note: No-op unless both YAC_PAK_TRACE=1 and YAC_PAK_TRACE_SETUP=1 are set.

Definition at line 972 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ yac_pak_trace_stop()

int yac_pak_trace_stop	(	struct yac_pak *	pak,
		int	handle )

Stop a trace event.

Stops a trace event previously started with yac_pak_trace_start_ex(). Records the end timestamp and stores the complete entry in the trace buffer.

Parameters

[in]	pak	YAC PAK object (no-op if NULL)
[in]	handle	Event handle returned by yac_pak_trace_start_ex()

Returns: 0 on success, -1 if handle is invalid or tracing is disabled

Definition at line 1055 of file yac_pak.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ YAC_PAK_VERSION_MAJOR

◆ YAC_PAK_VERSION_MINOR

◆ YAC_PAK_VERSION_PATCH

◆ YAC_PAK_VERSION_STRING

Enumeration Type Documentation

◆ yac_pak_event_type_t

◆ yac_pak_trace_level_t

Function Documentation

◆ yac_pak_delete()

◆ yac_pak_flush_trace()

◆ yac_pak_get_config_output_path()

◆ yac_pak_new()

◆ yac_pak_region_trace_is_enabled()

◆ yac_pak_register()

◆ yac_pak_report()

◆ yac_pak_set_component()

◆ yac_pak_setup_trace_is_enabled()

◆ yac_pak_start()

◆ yac_pak_stop()

◆ yac_pak_trace_is_enabled()

◆ yac_pak_trace_record()

◆ yac_pak_trace_start_ex()

◆ yac_pak_trace_start_setup()

◆ yac_pak_trace_stop()