Loading...
Searching...
No Matches
log.h File Reference

Logging interfaces. More...

Data Structures

struct  spdk_log_opts
 
struct  spdk_log_flag
 

Macros

#define SPDK_DEBUGLOG_FLAG_ENABLED(name)   false
 
#define SPDK_NOTICELOG(...)    spdk_log(SPDK_LOG_NOTICE, __FILE__, __LINE__, __func__, __VA_ARGS__)
 
#define SPDK_WARNLOG(...)    spdk_log(SPDK_LOG_WARN, __FILE__, __LINE__, __func__, __VA_ARGS__)
 
#define SPDK_ERRLOG(...)    spdk_log(SPDK_LOG_ERROR, __FILE__, __LINE__, __func__, __VA_ARGS__)
 
#define SPDK_PRINTF(...)    spdk_log(SPDK_LOG_NOTICE, NULL, -1, NULL, __VA_ARGS__)
 
#define SPDK_INFOLOG(flag, ...)
 
#define SPDK_ERRLOG_RATELIMIT(...)
 
#define SPDK_DEBUGLOG(...)   do { } while (0)
 
#define SPDK_LOGDUMP(...)   do { } while (0)
 
#define SPDK_LOG_REGISTER_COMPONENT(flag)
 
#define SPDK_LOG_DEPRECATION_REGISTER(tag, desc, release, rate)
 
#define SPDK_LOG_DEPRECATED(tag)    spdk_log_deprecated(_deprecated_##tag, __FILE__, __LINE__, __func__)
 

Typedefs

typedef void spdk_log_cb(int level, const char *file, const int line, const char *func, const char *format, va_list args)
 for passing user-provided log call
 
typedef void spdk_log_open_cb(void *ctx)
 for opening user-provided logger
 
typedef void spdk_log_close_cb(void *ctx)
 for closing user-provided logger
 
typedef int(* spdk_log_for_each_deprecation_fn) (void *ctx, struct spdk_deprecation *deprecation)
 Callback function for spdk_log_for_each_deprecation().
 

Enumerations

enum  spdk_log_level {
  SPDK_LOG_DISABLED = -1 , SPDK_LOG_ERROR , SPDK_LOG_WARN , SPDK_LOG_NOTICE ,
  SPDK_LOG_INFO , SPDK_LOG_DEBUG
}
 

Functions

 SPDK_STATIC_ASSERT (sizeof(struct spdk_log_opts)==40, "Incorrect size")
 
void spdk_log_open (spdk_log_cb *log)
 Initialize the logging module.
 
void spdk_log_open_ext (struct spdk_log_opts *opts)
 Extended API to initialize the logging module.
 
void spdk_log_close (void)
 Close the currently active log.
 
void spdk_log_enable_timestamps (bool value)
 Enable or disable timestamps.
 
void spdk_log_set_level (enum spdk_log_level level)
 Set the log level threshold to log messages.
 
enum spdk_log_level spdk_log_get_level (void)
 Get the current log level threshold.
 
int spdk_log_to_syslog_level (enum spdk_log_level level)
 Get syslog level based on SPDK current log level threshold.
 
void spdk_log_set_print_level (enum spdk_log_level level)
 Set the current log level threshold for printing to stderr.
 
enum spdk_log_level spdk_log_get_print_level (void)
 Get the current log level print threshold.
 
void spdk_log (enum spdk_log_level level, const char *file, const int line, const char *func, const char *format,...)
 Write messages to the log file.
 
void spdk_vlog (enum spdk_log_level level, const char *file, const int line, const char *func, const char *format, va_list ap)
 Same as spdk_log except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.
 
void spdk_flog (FILE *fp, const char *file, const int line, const char *func, const char *format,...)
 Write messages to the log file.
 
void spdk_vflog (FILE *fp, const char *file, const int line, const char *func, const char *format, va_list ap)
 Same as spdk_flog except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.
 
void spdk_log_dump (FILE *fp, const char *label, const void *buf, size_t len)
 Log the contents of a raw buffer to a file.
 
void spdk_log_register_flag (const char *name, struct spdk_log_flag *flag)
 Register a log flag.
 
struct spdk_log_flagspdk_log_get_first_flag (void)
 Get the first registered log flag.
 
struct spdk_log_flagspdk_log_get_next_flag (struct spdk_log_flag *flag)
 Get the next registered log flag.
 
bool spdk_log_get_flag (const char *flag)
 Check whether the log flag exists and is enabled.
 
int spdk_log_set_flag (const char *flag)
 Enable the log flag.
 
int spdk_log_clear_flag (const char *flag)
 Clear a log flag.
 
void spdk_log_usage (FILE *f, const char *log_arg)
 Show all the log flags and their usage.
 
int spdk_log_deprecation_register (const char *tag, const char *description, const char *remove_release, uint32_t rate_limit_seconds, struct spdk_deprecation **reg)
 Register a deprecation.
 
void spdk_log_deprecated (struct spdk_deprecation *deprecation, const char *file, uint32_t line, const char *func)
 Indicate that a deprecated feature was used.
 
int spdk_log_for_each_deprecation (void *ctx, spdk_log_for_each_deprecation_fn fn)
 Iterate over all deprecations, calling a callback on each of them.
 
const char * spdk_deprecation_get_tag (const struct spdk_deprecation *deprecation)
 Get a deprecation's tag.
 
const char * spdk_deprecation_get_description (const struct spdk_deprecation *deprecation)
 Get a deprecation's description.
 
const char * spdk_deprecation_get_remove_release (const struct spdk_deprecation *deprecation)
 Get a deprecation's planned removal release.
 
uint64_t spdk_deprecation_get_hits (const struct spdk_deprecation *deprecation)
 Get the number of times that a deprecation's code has been executed.
 

Detailed Description

Logging interfaces.

Macro Definition Documentation

◆ SPDK_ERRLOG_RATELIMIT

#define SPDK_ERRLOG_RATELIMIT ( ...)
Value:
do { \
static uint64_t last_tsc = 0; \
static uint64_t squashed = 0; \
uint64_t tsc = spdk_get_ticks(); \
if (tsc > last_tsc + spdk_get_ticks_hz()) { \
last_tsc = tsc; \
SPDK_ERRLOG(__VA_ARGS__); \
if (squashed > 0) { \
SPDK_ERRLOG("(same message squashed %" PRIu64 " times)\n", \
squashed); \
squashed = 0; \
} \
} else { \
squashed++; \
} \
} while (0)
uint64_t spdk_get_ticks_hz(void)
Get the tick rate of spdk_get_ticks() per second.
uint64_t spdk_get_ticks(void)
Get a monotonic timestamp counter.

◆ SPDK_INFOLOG

#define SPDK_INFOLOG ( flag,
... )
Value:
do { \
extern struct spdk_log_flag SPDK_LOG_##flag; \
if (SPDK_LOG_##flag.enabled) { \
spdk_log(SPDK_LOG_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__); \
} \
} while (0)
Definition log.h:266

◆ SPDK_LOG_DEPRECATION_REGISTER

#define SPDK_LOG_DEPRECATION_REGISTER ( tag,
desc,
release,
rate )
Value:
static struct spdk_deprecation *_deprecated_##tag; \
static void __attribute__((constructor)) _spdk_deprecation_register_##tag(void) \
{ \
int rc; \
rc = spdk_log_deprecation_register(#tag, desc, release, rate, &_deprecated_##tag); \
(void)rc; \
assert(rc == 0); \
}
int spdk_log_deprecation_register(const char *tag, const char *description, const char *remove_release, uint32_t rate_limit_seconds, struct spdk_deprecation **reg)
Register a deprecation.

◆ SPDK_LOG_REGISTER_COMPONENT

#define SPDK_LOG_REGISTER_COMPONENT ( flag)
Value:
struct spdk_log_flag SPDK_LOG_##flag = { \
.name = #flag, \
.enabled = false, \
}; \
__attribute__((constructor)) static void register_flag_##flag(void) \
{ \
spdk_log_register_flag(#flag, &SPDK_LOG_##flag); \
}

Typedef Documentation

◆ spdk_log_cb

typedef void spdk_log_cb(int level, const char *file, const int line, const char *func, const char *format, va_list args)

for passing user-provided log call

Parameters
levelLog level threshold.
fileName of the current source file.
lineCurrent source file line.
funcCurrent source function name.
formatFormat string to the message.
argsAdditional arguments for format string.

◆ spdk_log_close_cb

typedef void spdk_log_close_cb(void *ctx)

for closing user-provided logger

Parameters
ctxUser-defined context for log open/close

◆ spdk_log_for_each_deprecation_fn

typedef int(* spdk_log_for_each_deprecation_fn) (void *ctx, struct spdk_deprecation *deprecation)

Callback function for spdk_log_for_each_deprecation().

Parameters
ctxContext passed via spdk_log_for_each_deprecation().
deprecationPointer to a deprecation structure.
Returns
0 to continue iteration or non-zero to stop iteration.

◆ spdk_log_open_cb

typedef void spdk_log_open_cb(void *ctx)

for opening user-provided logger

Parameters
ctxUser-defined context for log open/close

Enumeration Type Documentation

◆ spdk_log_level

Enumerator
SPDK_LOG_DISABLED 

All messages will be suppressed.

Function Documentation

◆ spdk_deprecation_get_description()

const char * spdk_deprecation_get_description ( const struct spdk_deprecation * deprecation)

Get a deprecation's description.

Parameters
deprecationA pointer to an spdk_deprecation.
Returns
The deprecation's description.

◆ spdk_deprecation_get_hits()

uint64_t spdk_deprecation_get_hits ( const struct spdk_deprecation * deprecation)

Get the number of times that a deprecation's code has been executed.

Parameters
deprecationA pointer to an spdk_deprecation.
Returns
The deprecation's planned removal release.

◆ spdk_deprecation_get_remove_release()

const char * spdk_deprecation_get_remove_release ( const struct spdk_deprecation * deprecation)

Get a deprecation's planned removal release.

Parameters
deprecationA pointer to an spdk_deprecation.
Returns
The deprecation's planned removal release.

◆ spdk_deprecation_get_tag()

const char * spdk_deprecation_get_tag ( const struct spdk_deprecation * deprecation)

Get a deprecation's tag.

Parameters
deprecationA pointer to an spdk_deprecation.
Returns
The deprecation's tag.

◆ spdk_flog()

void spdk_flog ( FILE * fp,
const char * file,
const int line,
const char * func,
const char * format,
... )

Write messages to the log file.

If level is set to SPDK_LOG_DISABLED, this log message won't be written.

Parameters
fpFile to hold the log.
fileName of the current source file.
lineCurrent source line number.
funcCurrent source function name.
formatFormat string to the message.

◆ spdk_log()

void spdk_log ( enum spdk_log_level level,
const char * file,
const int line,
const char * func,
const char * format,
... )

Write messages to the log file.

If level is set to SPDK_LOG_DISABLED, this log message won't be written.

Parameters
levelLog level threshold.
fileName of the current source file.
lineCurrent source line number.
funcCurrent source function name.
formatFormat string to the message.

◆ spdk_log_clear_flag()

int spdk_log_clear_flag ( const char * flag)

Clear a log flag.

The name of the flag can be a glob pattern (as expanded by fnmatch(3)), in which case all matching flags will be cleared.

Parameters
flagLog flag to clear.
Returns
0 on success, negative errno on failure.

◆ spdk_log_close()

void spdk_log_close ( void )

Close the currently active log.

Messages after this call will be dropped.

◆ spdk_log_deprecated()

void spdk_log_deprecated ( struct spdk_deprecation * deprecation,
const char * file,
uint32_t line,
const char * func )

Indicate that a deprecated feature was used.

Most consumers will use SPDK_LOG_DEPRECATED() instead.

Parameters
deprecationThe deprecated feature that was used.
fileThe name of the source file where the deprecated feature was used.
lineThe line in file where where the deprecated feature was used.
funcThe name of the function where where the deprecated feature was used.

◆ spdk_log_deprecation_register()

int spdk_log_deprecation_register ( const char * tag,
const char * description,
const char * remove_release,
uint32_t rate_limit_seconds,
struct spdk_deprecation ** reg )

Register a deprecation.

Most consumers will use SPDK_LOG_DEPRECATION_REGISTER() instead.

Parameters
tagA unique string that will appear in each log message and should appear in documentation.
descriptionA descriptive string that will also be logged.
rate_limit_secondsIf non-zero, log messages related to this deprecation will appear no more frequently than this interval.
remove_releaseThe release when the deprecated support will be removed.
regPointer to storage for newly allocated deprecation handle.
Returns
0 on success or negative errno on failure.

◆ spdk_log_dump()

void spdk_log_dump ( FILE * fp,
const char * label,
const void * buf,
size_t len )

Log the contents of a raw buffer to a file.

Parameters
fpFile to hold the log.
labelLabel to print to the file.
bufBuffer that holds the log information.
lenLength of buffer to dump.

◆ spdk_log_for_each_deprecation()

int spdk_log_for_each_deprecation ( void * ctx,
spdk_log_for_each_deprecation_fn fn )

Iterate over all deprecations, calling a callback on each of them.

Iteration will stop early if the callback function returns non-zero.

Parameters
ctxContext to pass to the callback.
fnCallback function
Returns
The value from the last callback called or 0 if there are no deprecations.

◆ spdk_log_get_first_flag()

struct spdk_log_flag * spdk_log_get_first_flag ( void )

Get the first registered log flag.

Returns
The first registered log flag.

◆ spdk_log_get_flag()

bool spdk_log_get_flag ( const char * flag)

Check whether the log flag exists and is enabled.

Returns
true if enabled, or false otherwise.

◆ spdk_log_get_level()

enum spdk_log_level spdk_log_get_level ( void )

Get the current log level threshold.

Returns
the current log level threshold.

◆ spdk_log_get_next_flag()

struct spdk_log_flag * spdk_log_get_next_flag ( struct spdk_log_flag * flag)

Get the next registered log flag.

Parameters
flagThe current log flag.
Returns
The next registered log flag.

◆ spdk_log_get_print_level()

enum spdk_log_level spdk_log_get_print_level ( void )

Get the current log level print threshold.

Returns
the current log level print threshold.

◆ spdk_log_open()

void spdk_log_open ( spdk_log_cb * log)

Initialize the logging module.

Messages prior to this call will be dropped.

◆ spdk_log_open_ext()

void spdk_log_open_ext ( struct spdk_log_opts * opts)

Extended API to initialize the logging module.

Messages prior to this call will be dropped.

Parameters
optsOptions to provide log related functions with user-defined context for open/close

◆ spdk_log_register_flag()

void spdk_log_register_flag ( const char * name,
struct spdk_log_flag * flag )

Register a log flag.

Parameters
nameName of the log flag.
flagLog flag to be added.

◆ spdk_log_set_flag()

int spdk_log_set_flag ( const char * flag)

Enable the log flag.

The name of the flag can be a glob pattern (as expanded by fnmatch(3)), in which case all matching flags will be set.

Parameters
flagLog flag to be enabled.
Returns
0 on success, negative errno on failure.

◆ spdk_log_set_level()

void spdk_log_set_level ( enum spdk_log_level level)

Set the log level threshold to log messages.

Messages with a higher level than this are ignored.

Parameters
levelLog level threshold to set to log messages.

◆ spdk_log_set_print_level()

void spdk_log_set_print_level ( enum spdk_log_level level)

Set the current log level threshold for printing to stderr.

Messages with a level less than or equal to this level are also printed to stderr. You can use SPDK_LOG_DISABLED to completely suppress log printing.

Parameters
levelLog level threshold for printing to stderr.

◆ spdk_log_to_syslog_level()

int spdk_log_to_syslog_level ( enum spdk_log_level level)

Get syslog level based on SPDK current log level threshold.

Parameters
levelLog level threshold
Returns
-1 for disable log print, otherwise is syslog level.

◆ spdk_log_usage()

void spdk_log_usage ( FILE * f,
const char * log_arg )

Show all the log flags and their usage.

Parameters
fFile to hold all the flags' information.
log_argCommand line option to set/enable the log flag.

◆ spdk_vflog()

void spdk_vflog ( FILE * fp,
const char * file,
const int line,
const char * func,
const char * format,
va_list ap )

Same as spdk_flog except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.

Parameters
fpFile to hold the log.
fileName of the current source file.
lineCurrent source line number.
funcCurrent source function name.
formatFormat string to the message.
apprintf arguments

◆ spdk_vlog()

void spdk_vlog ( enum spdk_log_level level,
const char * file,
const int line,
const char * func,
const char * format,
va_list ap )

Same as spdk_log except that instead of being called with variable number of arguments it is called with an argument list as defined in stdarg.h.

Parameters
levelLog level threshold.
fileName of the current source file.
lineCurrent source line number.
funcCurrent source function name.
formatFormat string to the message.
apprintf arguments