This document is relevant for: Inf1, Inf2, Trn1, Trn2, Trn3

nrt_sys_trace.h#

Neuron Runtime System Trace API - Capture and fetch system trace events from Neuron devices.

Source: src/libnrt/include/nrt/nrt_sys_trace.h

Functions#

System Trace Capture#

nrt_sys_trace_config_allocate#

NRT_STATUS nrt_sys_trace_config_allocate(nrt_sys_trace_config_t **options);

Allocate memory for the options structure which is needed to start profiling using nrt_sys_trace_start.

Parameters:

  • options [in] - pointer to a pointer to options nrt_sys_trace_config struct

Returns: NRT_SUCCESS on success

Source: nrt_sys_trace.h:29

nrt_sys_trace_config_set_max_events_per_nc#

void nrt_sys_trace_config_set_max_events_per_nc(nrt_sys_trace_config_t *options, uint64_t max_events_per_nc);

Sets max number of events that can be stored across all ring buffers.

Parameters:

  • options [in,out] - Pointer to the options structure.

  • max_events_per_nc [in] - Max number of events that can be stored in each ring buffer.

Source: nrt_sys_trace.h:50

nrt_sys_trace_config_set_capture_enabled_for_nc#

void nrt_sys_trace_config_set_capture_enabled_for_nc(nrt_sys_trace_config_t *options, uint32_t nc_idx, bool enabled);

Sets system trace capture enabled for a specific NeuronCore. Ring buffers won’t be allocated for disabled NeuronCores.

Parameters:

  • options [in,out] - Pointer to the options structure.

  • nc_idx [in] - NeuronCore index.

  • enabled [in] - Capture enabled flag.

Source: nrt_sys_trace.h:60

nrt_sys_trace_get_event_types#

NRT_STATUS nrt_sys_trace_get_event_types(const char ***event_types, size_t *count);

Returns an allocated array of all valid event type strings.

Parameters:

  • event_types [out] - Pointer to array of const char* (allocated).

  • count [out] - Number of event types.

Returns: NRT_SUCCESS on success, error code otherwise.

Note: The user is responsible for freeing the array and each string, or can use nrt_sys_trace_free_event_types() for convenience.

Source: nrt_sys_trace.h:79

nrt_sys_trace_start#

NRT_STATUS nrt_sys_trace_start(nrt_sys_trace_config_t *options);

Initialization for system trace capture including allocating memory for event ring buffers.

Parameters:

  • options [in] - Configuration options for system trace capture

Returns: NRT_SUCCESS on success

Source: nrt_sys_trace.h:106

nrt_sys_trace_stop#

NRT_STATUS nrt_sys_trace_stop();

Teardown for system trace capture including freeing allocated memory for event ring buffers.

Returns: NRT_SUCCESS on success

Source: nrt_sys_trace.h:109

System Trace Fetch#

nrt_sys_trace_fetch_events#

NRT_STATUS nrt_sys_trace_fetch_events(char **buffer, size_t *written_size, const nrt_sys_trace_fetch_options_t *options);

Fetches system trace events from process memory and returns them as a JSON-formatted string. Once events are fetched, they cannot be fetched again.

Parameters:

  • buffer [out] - On successful return, will point to a dynamically allocated, null-terminated JSON string containing the trace events. The caller must free the allocated memory by calling nrt_sys_trace_buffer_free(buffer).

  • written_size [out] - A pointer to a size_t variable that will be set to the number of bytes written into the allocated buffer.

  • options [in] - Pointer to options such as max number of events to fetch.

Returns: NRT_SUCCESS on success.

Source: nrt_sys_trace.h:143

nrt_sys_trace_buffer_free#

void nrt_sys_trace_buffer_free(char *buffer);

Free the buffer allocated by nrt_sys_trace_fetch_events. Should be called after the events are no longer needed.

Parameters:

  • buffer [in] - Pointer to buffer to be freed.

Source: nrt_sys_trace.h:151

This document is relevant for: Inf1, Inf2, Trn1, Trn2, Trn3