High-level NetLogger API

From NetLogger

Contents 1 Overview 1.1 Defines 1.2 Enumerations 1.3 Functions 1.4 Variables 2 Define documentation 3 Enumeration type documentation 4 Function documentation 5 Variable documentation

Overview

Defines

#define 	NL_DEST_ENV   "NL_DEST"
#define 	NL_DEST2_ENV   "NETLOGGER_DEST"
#define 	NL_CFG_ENV   "NL_CFG"
#define 	NL_EXTRA_ENV   "NL_EXTRA"

Enumerations

enum  	NL_level_t
enum  	NL_result_t

Functions

NL_log_T     NL_open (const char *url)
int 	     NL_open_succeeded (NL_log_T self)
NL_result_t  NL_set_const (NL_log_T self, const char *fmt,...)
void 	     NL_set_level (NL_log_T self, NL_level_t level)
NL_result_t  NL_write (NL_log_T self, NL_level_t level, const char *event, const char *fmt,...)
NL_result_t  NL_write_ts (NL_log_T self, struct timeval *ts, NL_level_t level, const char  
             *event, const char *fmt,...)
void 	     NL_flush (NL_log_T self)
void 	     NL_close (NL_log_T self)

Variables

int 	     NL_flush_on
mode_t       NL_file_mode
int 	     NL_file_append

Define documentation

#define NL_CFG_ENV   "NL_CFG"

• Log level file. Full path to file containing log level. See parse_level() for details.

#define NL_DEST2_ENV   "NETLOGGER_DEST"

• Output URL (old env var.)

#define NL_DEST_ENV   "NL_DEST"

• Output URL (new). Example: "x-netlog://remote.host:55555"

#define NL_EXTRA_ENV   "NL_EXTRA"

• Extra text to append to each log entry. The formatting for this text is not checked, so improper values here will corrupt the logs. However, this is a useful way to add arbitrary metadata without changing the program in any way. The data doesn't need any delimiters at the start or end.

For example, if the 'gridbp' format is being used: prompt> export NL_EXTRA='experiment.name="test 1" p1=5 p2=14'

Enumeration type documentation

enum NL_level_t

• Log level enumeration

enum NL_result_t

• Return value enumeration

Function documentation

void NL_close (NL_log_T self)  	

Close and destroy log.

• Precondition: Parameter is NULL or valid log object.
• Postcondition:Argument passed as 'self' is closed.
• Parameters: self Log object

void NL_flush (NL_log_T self)  	

• Flush log.
• Parameters: self Log object

NL_log_T NL_open (const char *url)  	

• Create and open log.
• Parameters: url Output URL. Accepted URL patterns:
  • path
  • file://path
  • x-netlog://host[:port]
  • x-netlog-udp://host[:port]
  • x-syslog://[facility_name:]program_name Where 'facility_name' is one of the standard syslog macro names, case-insensitive and without the LOG_ prefix. For example "FTP", "Local0", and "syslog" are all valid. The default facility is USER (LOG_USER).

• Returns:(NL_log_T) Log handle, NULL on error.

int NL_open_succeeded (NL_log_T self)  	

• Check whether NL_open succeeded.
• Parameters: self Log object (may be NULL)
• Returns: 1=yes, 0=no

NL_result_t NL_set_const (NL_log_T self, const char *fmt, ...) 			

• Create 'constant' record. Replace existing constant record, if any.
• Postcondition: This call does nothing if the log object is closed.
• Parameters:
  • self Log object.
  • fmt Format used to create log.
• Returns: Success (NL_OK) or failure (NL_ERROR).

void NL_set_level (NL_log_T self, NL_level_t level) 			

• Set log level.
• Parameters:
  • self Log object
  • level New logging level
• Returns: None

NL_result_t NL_write (NL_log_T self,NL_level_t level, const char *event, const char *fmt, ...) 	*Write one log event.

• Parameters:
  • self Log object
  • level Logging level for this event
  • event Event name
  • fmt Format for event attributes: "name1=type_code1 name2=type_code2 ..etc..".

• Recognized type_codes (all single characters):
  • 'd' Double (64 bits)
  • 's' String
  • 'i' Integer (32 bits)
  • 'l' Long integer (64 bits)
  • 't' Time; input as double seconds since UTC,1970

• Parameters: ... Event attributes
  • Returns: Status of write operation

NL_result_t NL_write_ts (NL_log_T self, struct timeval *ts, NL_level_t	level, const char *event,		const char *  	fmt, ...) 			

• Write one event with user-supplied timestamp.
• Parameters:
  • self Log object
  • ts Timestamp
  • level Logging level for this event
  • event Event name
  • mt Format for event attributes: "name1=type_code1 name2=type_code2 ..etc..".

• Recognized type_codes (all single characters):
  • 'd' Double (64 bits)
  • 's' String
  • 'i' Integer (32 bits)
  • 'l' Long integer (64 bits)
  • 't' Time; input as double seconds since UTC,1970

• Parameters: ... Event attributes
• Returns:
  • Status of write operation

Variable documentation

int NL_file_append

File append flag. If non-zero, open file URLs with O_APPEND in the open flags.

mode_t NL_file_mode

File permission bits. User may set this to change the permissions on log files.

Default value is 0664.

int NL_flush_on

Flush flag. User may set this to '1' to turn on flushing of all (file) output. Note that this will GREATLY reduce performance, and should only be used if each message is critical (and infrequent, i.e. < 10 per second).