DataSource for C SDK  7.1.28.98838-0467ac22
DataSource Logging

Macros

#define DS_LOG_CONFIG   0
 Used for log messages that indicate a problem or feedback with library configuration. More...
 
#define DS_LOG_CRIT   2
 Used for log messages that indicate a serious failure. More...
 
#define DS_LOG_DEBUG   7
 Used for tracing messages. More...
 
#define DS_LOG_ERROR   3
 Used for log messages that indicate a problem. More...
 
#define DS_LOG_FINER   8
 Used for fairly detailed tracing messages. More...
 
#define DS_LOG_FINEST   9
 Used for the most finely detailed tracing messages. More...
 
#define DS_LOG_INFO   6
 Used for informational messages. More...
 
#define DS_LOG_MONITOR   128
 A modifier that will send the log message to the monitoring system in addition to the event log, even if the log level is below the monitoring threshold value. More...
 
#define DS_LOG_NOTIFY   4
 Used for messages of greater importance than DS_LOG_WARN that may not indicate problems. More...
 
#define DS_LOG_SYSLOG   512
 A modifier which will write the log message to the system log in addition to the event log regardless of the level passed to ds_log() or the level set by log-syslog-level. Using this modifier with ds_log() is equivalent to calling ds_syslog() without the modifier. More...
 
#define DS_LOG_TERMINAL   256
 A modifier which will write the log message to the terminal in addition to the event log. More...
 
#define DS_LOG_WARN   5
 Used for messages that indicate a potential problem. More...
 

Typedefs

typedef struct _ds_log ds_log_t
 The log file object. More...
 
typedef void(* ds_logcycled_t) (ds_log_t *log)
 Callback used when the log has cycled. More...
 
typedef void(* ds_loglevelchange_t) (ds_log_t *log, int new_level)
 Callback used when the logging level of a log file is changed. More...
 

Functions

void ds_cycle_all_logs (const char *suffix, long maxsize)
 Cycle all log files in the application. More...
 
int ds_cycle_log (ds_log_t *log, const char *suffix, long maxsize)
 Cycle a specific log file. More...
 
int ds_debug_level (const char *text)
 This function will convert a string into an appropriate debug level. More...
 
void ds_free_log (ds_log_t *log)
 Destroy a log object. More...
 
void ds_log (ds_log_t *log, int level, const char *fmt,...)
 Write a formatted string prefixed with log level and timestamp to the log object. More...
 
void ds_log_category (ds_log_t *log, int level, const char *category_prefix, const char *fmt,...)
 Write a formatted string prefixed with category, log level and timestamp to the log object if the category configuration permits it. More...
 
void ds_log_change_level_callback (ds_log_t *log, ds_loglevelchange_t change_cb)
 Set the level change callback for a given logfile. More...
 
ds_logcycled_t ds_log_cycled_callback (ds_log_t *log, ds_logcycled_t cycle_cb)
 Set the cycle callback for a given logfile. More...
 
int ds_log_flush (ds_log_t *log)
 flush log buffers to disk More...
 
int ds_log_get_level (ds_log_t *log)
 Get the current loglevel for the given logfile. More...
 
char * ds_log_getfilename (ds_log_t *log)
 Get the filename of a log object. More...
 
char * ds_log_getname (ds_log_t *log)
 Get the name of a log object. More...
 
int ds_log_set_log_level (ds_log_t *log, const char *level)
 Set the log level for a particular logfile. More...
 
ds_log_tds_new_headed_log (const char *name, const char *logname, const char *header)
 Create a new log object with a header. More...
 
ds_log_tds_new_level_log (const char *name, const char *logname, ds_loglevelchange_t change_cb)
 Create a new log object. More...
 
ds_log_tds_new_log (const char *name, const char *logname)
 Create a new log object. More...
 
void ds_printf (ds_log_t *log, const char *fmt,...)
 Write a formatted string to a log object. More...
 
void ds_printf_time (ds_log_t *log, const char *fmt,...)
 Write a formatted string prefixed with a timestamp string to a log object. More...
 
void ds_printf_time_ap (ds_log_t *log, const char *extra, const char *fmt, va_list ap)
 Write a formatted string prefixed with a timestamp string to a log object. More...
 
void ds_syslog (ds_log_t *log, int level, const char *fmt,...)
 Write a formatted string to a log object and to the system log. More...
 
void ds_write (ds_log_t *log, void *data, size_t len)
 Write binary data to a log object. More...
 
void ds_writev (ds_log_t *log, struct iovec *vector, int count)
 Write binary data to a log object. More...
 

Detailed Description

DataSource's log files keep a record of all data and to what destinations the data was sent.

The DataSource SDK logging API permits you to create your own logging functions

Log file names can use the following abbreviations:

Macro Definition Documentation

#define DS_LOG_CONFIG   0

Used for log messages that indicate a problem or feedback with library configuration.

#define DS_LOG_CRIT   2

Used for log messages that indicate a serious failure.

#define DS_LOG_DEBUG   7

Used for tracing messages.

#define DS_LOG_ERROR   3

Used for log messages that indicate a problem.

#define DS_LOG_FINER   8

Used for fairly detailed tracing messages.

#define DS_LOG_FINEST   9

Used for the most finely detailed tracing messages.

#define DS_LOG_INFO   6

Used for informational messages.

#define DS_LOG_MONITOR   128

A modifier that will send the log message to the monitoring system in addition to the event log, even if the log level is below the monitoring threshold value.

#define DS_LOG_NOTIFY   4

Used for messages of greater importance than DS_LOG_WARN that may not indicate problems.

#define DS_LOG_SYSLOG   512

A modifier which will write the log message to the system log in addition to the event log regardless of the level passed to ds_log() or the level set by log-syslog-level. Using this modifier with ds_log() is equivalent to calling ds_syslog() without the modifier.

#define DS_LOG_TERMINAL   256

A modifier which will write the log message to the terminal in addition to the event log.

#define DS_LOG_WARN   5

Used for messages that indicate a potential problem.

Typedef Documentation

typedef struct _ds_log ds_log_t

The log file object.

typedef void(* ds_logcycled_t) (ds_log_t *log)

Callback used when the log has cycled.

Parameters
logThe logfile that has cycled
typedef void(* ds_loglevelchange_t) (ds_log_t *log, int new_level)

Callback used when the logging level of a log file is changed.

Parameters
logThe logfile the change has happend to
new_levelThe new debug level

Function Documentation

void ds_cycle_all_logs ( const char *  suffix,
long  maxsize 
)

Cycle all log files in the application.

Parameters
suffixSuffix to use for the filename of the old log
maxsizeSize (in bytes) at which logs are cycled
Note
Log cycling can be configured and this function is only of use if customised cycling is required

If maxsize is -1 the configured default is used. If maxsize is 0 then the log isn't cycled based on size.

int ds_cycle_log ( ds_log_t log,
const char *  suffix,
long  maxsize 
)

Cycle a specific log file.

Parameters
logThe Log object
suffixSuffix to use for the filename of the old log
maxsizeSize (in bytes) at which logs are cycled
Return values
0- Log file was cycled
-1- Log file was not cycled

If maxsize is -1 the configured default is used. If maxsize is 0 then the log isn't cycled based on size.

int ds_debug_level ( const char *  text)

This function will convert a string into an appropriate debug level.

Parameters
textThe string to convert
Returns
An appropriate debug level or -1 if not recognised

Example:

ds_debug_level("INFO);

Will return the value DS_LOG_INFO

void ds_free_log ( ds_log_t log)

Destroy a log object.

Parameters
logThe log object to destroy
void ds_log ( ds_log_t log,
int  level,
const char *  fmt,
  ... 
)

Write a formatted string prefixed with log level and timestamp to the log object.

Parameters
logThe log object
levelThe level that this message should be logged at (for example DS_LOG_INFO).
fmtThe format string
Note
The log object should be of the type that is returned by ds_new_level_log.

This function uses standard print style formatting options.

void ds_log_category ( ds_log_t log,
int  level,
const char *  category_prefix,
const char *  fmt,
  ... 
)

Write a formatted string prefixed with category, log level and timestamp to the log object if the category configuration permits it.

Parameters
logThe log object
levelThe level that this message should be logged at (for example DS_LOG_INFO).
category_prefixA string that identifies the log category
fmtThe format string
Note
The log object should be of the type that is returned by ds_new_level_log.

This function uses standard print style formatting options.

void ds_log_change_level_callback ( ds_log_t log,
ds_loglevelchange_t  change_cb 
)

Set the level change callback for a given logfile.

Parameters
logThe log file
change_cbThe callback to call when the debug level changes
ds_logcycled_t ds_log_cycled_callback ( ds_log_t log,
ds_logcycled_t  cycle_cb 
)

Set the cycle callback for a given logfile.

Parameters
logThe log file
cycle_cbThe callback to call when the log cycles
Return values
Anyexisting callback
int ds_log_flush ( ds_log_t log)

flush log buffers to disk

Parameters
log- The log to be flushed
Return values
0- Log was flushed successfully
-1- An error occurred flushing the logs
int ds_log_get_level ( ds_log_t log)

Get the current loglevel for the given logfile.

Parameters
logThe logfile
Return values
Thelog level
char* ds_log_getfilename ( ds_log_t log)

Get the filename of a log object.

Parameters
logThe Log object
Returns
The filename of this log object
char* ds_log_getname ( ds_log_t log)

Get the name of a log object.

Parameters
log- The log object
Returns
The name of the logfile (eg event_log)
int ds_log_set_log_level ( ds_log_t log,
const char *  level 
)

Set the log level for a particular logfile.

Parameters
logThe log to set the level for
levelA textual string representing the log level
Return values
0- Log level was set
-1- Log level wasn't set (invalid level supplied or inappropriate log file)
ds_log_t* ds_new_headed_log ( const char *  name,
const char *  logname,
const char *  header 
)

Create a new log object with a header.

Parameters
nameName of the log object
lognameFile name
headerThe header text
Returns
A new log object

The header will be added to the beginning of the log file every time it cycles. The header text can be a maximum of 80 characters

The filename given should be either absolute or relative to the configured log directory (log-dir)

Any log can be configured to cycle individually (add-log-cycle)

ds_log_t* ds_new_level_log ( const char *  name,
const char *  logname,
ds_loglevelchange_t  change_cb 
)

Create a new log object.

Parameters
nameName of the log object
lognameFile name
change_cbCallback for change log levels
Returns
A new log object

The filename given should be either absolute or relative to the configured log directory (log-dir)

Any log can be configured to cycle individually (add-log-cycle)

ds_log_t* ds_new_log ( const char *  name,
const char *  logname 
)

Create a new log object.

Parameters
nameName of the log object
lognameFile name
Returns
A new log object

The filename given should be either absolute or relative to the configured log directory (log-dir)

Any log can be configured to cycle individually (add-log-cycle)

void ds_printf ( ds_log_t log,
const char *  fmt,
  ... 
)

Write a formatted string to a log object.

Parameters
logThe log object
fmtThe format string

This function uses standard printf style formatting options.

void ds_printf_time ( ds_log_t log,
const char *  fmt,
  ... 
)

Write a formatted string prefixed with a timestamp string to a log object.

Parameters
logThe log object
fmtThe format string

This function uses standard printf style formatting options.

The time stamp produced by this function is of the form:

Nov 18 10:37:47.321 +0000: 
void ds_printf_time_ap ( ds_log_t log,
const char *  extra,
const char *  fmt,
va_list  ap 
)

Write a formatted string prefixed with a timestamp string to a log object.

Parameters
logThe log object
extraAn additional string
fmtThe format string
apAn argument list

The parameter extra is inserted after the timestamp and before the formatted string in the output stream

This function uses standard printf style formatting options.

void ds_syslog ( ds_log_t log,
int  level,
const char *  fmt,
  ... 
)

Write a formatted string to a log object and to the system log.

Parameters
logThe log object
levelThe level that this message should be logged at (for example DS_LOG_INFO).
fmtThe format string
Note
The format string should not end with a newline character
The log is written to syslog regardless of the level set by log-syslog-level or the level passed in the call to ds_syslog().
See also
DS_LOG_SYSLOG
void ds_write ( ds_log_t log,
void *  data,
size_t  len 
)

Write binary data to a log object.

Parameters
logThe log object
dataPointer to the start of data to write
lenSize of data to write (in bytes)
void ds_writev ( ds_log_t log,
struct iovec *  vector,
int  count 
)

Write binary data to a log object.

Parameters
logThe log object
vectorwritev vector
countwritev count

Generated on Fri Jan 20 2023 17:49:17 for DataSource for C SDK