View source

== NetLogger Modules ==

'''NetLogger''' has the five modules: 
* [[High-level NetLogger API]] 
* [[Utility functions]]
* [[NetLogger summarization API]]
* [[NetLogger summarizer internal functions]]
* [[nltransfer API examples | File Transfer Summarization]]
* [[Experimental subsampling API]]

To use the C API, follow this basic pattern:

* Create logging 'module'(s): NL_logger_module()
* Write messages to module(s): NL_write(), NL_debug(), NL_info(), NL_warn(), NL_error(), ..etc.
* Cleanup: NL_logger_del() 

In the NetLogger C API, a module is a user-assigned name for all the parameters associated with a logging output – log "type", destination URL, and logging level. Every time you write a message, you specify which module to write it to. So, for example, you may specify one module for messages to the user on stdout, and another one for detailed debugging to a file in /tmp:

     NL_logger_module( "user", "-" /* stdout */, NL_LVL_INFO, NL_TGT_X );
     NL_logger_module( "debug", "/tmp/log", NL_LVL_DEBUG, NL_TGT_DBG, "" );

== Example code ==

This is a sample high-level C API usage. This is the API that most people
would be expected to use.
* http://dsd.lbl.gov/NetLogger/download/sample-code/logger_example.c.txt  (source) 	

This shows how Netlogger can be used to emulate sprintf functionality:
* http://dsd.lbl.gov/NetLogger/download/sample-code/nlsprintf_example.c.txt (source)

== Environment variables ==

If you provide a NULL url to NL_logger_module(), then NetLogger will look for the enviroment variable [[Environment_variables| NETLOGGER_DEST]] for the URL. If NETLOGGER_DEST is not set, events will do to stderr.

For example, if you have this code:

     #include "nl_log.h"
     main() {
        NL_logger_module("dbg", NULL, NL_LVL_INFO, NL_TYPE_DBG, "");
        NL_info("dbg","Hello","to_whom=s","World");
     }

Then NetLogger events will be sent to the URL specified in NETLOGGER_DEST.

Note: only the C API looks at this environment variable. The Python, Java, and Perl APIs do not.

== The L_logger_module() function ==

     NL_result_t
     NL_logger_module( const char *module,
                       const char *url,
                       NL_level_t level,
                       NL_tgttype_t ttype,
                       ... );

'''Parameters'''

The module name is a free-form string, but please remember that this is a key in a (hidden, global) hash-table, so long descriptive names will hurt performance.

The url is a standard netlogger URL. With no scheme or "file://" it is a filename, with "x-netlog://<host>[:<port>]" it is a TCP destination, and with "x-syslog://" it uses syslog. Two special filenames are defined, "-" for stdout and "&" for stderr. If the URL is NULL, the value of the environment NL_DEST is used, otherwise stderr.

The level is an integer. Higher numbers indicate more detailed logging, or looked at another way lower numbers are more 'critical' messages. The header file defines these symbolic names:

* NL_LVL_NOLOG = 0: Log nothing
* NL_LVL_FATAL = 1: Fatal error (program termination expected)
* NL_LVL_ERROR = 2: Error
* NL_LVL_WARN = 3: Warning
* NL_LVL_INFO = 4: Informational (default level)
* NL_LVL_DEBUG = 5: Debugging message
* NL_LVL_DEBUG1 = 6: More detailed debugging
* NL_LVL_DEBUG2 = 7: Even more detailed debugging
* NL_LVL_DEBUG3 = 8: Even more detailed debugging yet
* NL_LVL_USER = 9: This level and all others after it are not reserved 

The ttype, or target type, is an integer constant. Different target types will write different information, by default, in each message. The header file defines symbolic names:

* NL_TYPE_APP: "app". Application instrumentation
* NL_TYPE_DBG: "dbg". Application debugging
* NL_TYPE_PATH: "path". Network path monitoring
* NL_TYPE_NODE: "node". Host, etc. monitoring
* NL_TYPE_X: "any". None of the above.. 

The ... (variable arguments) depend on the target type. For APP, DBG, and NODE, the user should add the host IP address or "" to make NetLogger determine it automatically (via DNS). For the other target types, no argument is expected.

'''Return value'''

If the module was created, then NL_OK is returned. Otherwise NL_ERROR is returned, and an error message should have been written to the screen (stderr).

== The NL_write() function ==

The various logging functions are named for the logging level they use. The generic function is NL_write(), which unlike the others takes the level as its first argument.

    * NL_write(level, module, event, fmt, args...) Write any level message
    * NL_debug3(module, event, fmt, args...) Debug level 3 message.
    * NL_debug2(module, event, fmt, args...) Debug level 2 message.
    * NL_debug1(module, event, fmt, args...) Debug level 1 message.
    * NL_debug(module, event, fmt, args...) Debug (level 0) message.
    * NL_info(module, event, fmt, args...) Informational message.
    * NL_warn(module, event, fmt, args...) Warning message.
    * NL_error(module, event, fmt, args...) Error message.
    * NL_fatal(module, event, fmt, args...) Fatal error message. 

'''Parameters'''

The module is the name given to the module when it was created with NL_logger_module(().

The event is the name of the event.

The format string (fmt) describes the format of the variable arguments to follow, with the exception of the "special" arguments required for certain "target types", as explained below.

The syntax for fmt is <field>=<type-code> space <field>=<type-code> ..etc.., where <field> is the name of "key" of the key/value pair, and "type-code" is a one-letter code indicating the datatype. The type codes are enumerated in Output format. To improve performance, you can use a ":" instead of a "=" for values that will never change (a.k.a. constants) from their initial value.

For the path target type, the first two arguments are always interpreted as "SRC=s DST=s", i.e. the source and destination endpoints. Therefore, when using this target type, if fmt was "VAL=i" then you would have three (3) values: NL_info("test","my.event","VAL=i","12.13.14.15","15.14.13.12","76");

== The NL_flush function ==

There is no internal buffering of NetLogger writes. However, the operating system will buffer writes to socket or disk for improved efficiency. To force synchronization of data to the physical medium after every write, set the global variable NL_flush to '1'. For example:

     void my_function( char *msg ) {
         NL_flush = 1;
         NL_debug("main","hello","MSG=s",msg);
     }

== The "activation" function ==

The C API also includes the ability to turn on/off instrumentation in a running program. This is done using an activation trigger file.

XXX: explain activation file format here.