cuSPARSE Logging API

cuSPARSE logging mechanism can be enabled by setting the following environment variables before launching the target application:

CUSPARSE_LOG_LEVEL=<level> - while level is one of the following levels:

  • 0 - Off - logging is disabled (default)

  • 1 - Error - only errors will be logged

  • 2 - Trace - API calls that launch CUDA kernels will log their parameters and important information

  • 3 - Hints - hints that can potentially improve the application’s performance

  • 4 - Info - provides general information about the library execution, may contain details about heuristic status

  • 5 - API Trace - API calls will log their parameter and important information

CUSPARSE_LOG_MASK=<mask> - while mask is a combination of the following masks:

  • 0 - Off

  • 1 - Error

  • 2 - Trace

  • 4 - Hints

  • 8 - Info

  • 16 - API Trace

CUSPARSE_LOG_FILE=<file_name> - while file name is a path to a logging file. File name may contain %i, that will be replaced with the process id. E.g <file_name>_%i.log.

If CUSPARSE_LOG_FILE is not defined, the log messages are printed to stdout.

Starting from CUDA 12.3, it is also possible to dump sparse matrices (CSR, CSC, COO, SELL, BSR) in binary files during the creation by setting the environment variable CUSPARSE_STORE_INPUT_MATRIX. Later on, the binary files can be send to Math-Libs-Feedback@nvidia.com for debugging and reproducibility purposes of a specific correctness/performance issue.

Another option is to use the experimental cuSPARSE logging API. See:

Note

The logging mechanism is not available for the legacy APIs.


cusparseLoggerSetCallback()

cusparseStatus_t
cusparseLoggerSetCallback(cusparseLoggerCallback_t callback)

Experimental: The function sets the logging callback function.

Param.

In/out

Meaning

callback

IN

Pointer to a callback function

where cusparseLoggerCallback_t has the following signature:

void (*cusparseLoggerCallback_t)(int         logLevel,
                                 const char* functionName,
                                 const char* message)

Param.

In/out

Meaning

logLevel

IN

Selected log level

functionName

IN

The name of the API that logged this message

message

IN

The log message

See cusparseStatus_t for the description of the return status


cusparseLoggerSetFile()

cusparseStatus_t
cusparseLoggerSetFile(FILE* file)

Experimental: The function sets the logging output file. Note: once registered using this function call, the provided file handle must not be closed unless the function is called again to switch to a different file handle.

Param.

In/out

Meaning

file

IN

Pointer to an open file. File should have write permission

See cusparseStatus_t for the description of the return status


cusparseLoggerOpenFile()

cusparseStatus_t
cusparseLoggerOpenFile(const char* logFile)

Experimental: The function opens a logging output file in the given path.

Param.

In/out

Meaning

logFile

IN

Path of the logging output file

See cusparseStatus_t for the description of the return status


cusparseLoggerSetLevel()

cusparseStatus_t
cusparseLoggerSetLevel(int level)

Experimental: The function sets the value of the logging level. path.

Param.

In/out

Meaning

level

IN

Value of the logging level

See cusparseStatus_t for the description of the return status


cusparseLoggerSetMask()

cusparseStatus_t
cusparseLoggerSetMask(int mask)

Experimental: The function sets the value of the logging mask.

Param.

In/out

Meaning

mask

IN

Value of the logging mask

See cusparseStatus_t for the description of the return status