C language

From NetLogger

Jump to: navigation, search

Contents

NetLogger Modules

NetLogger has the five modules:

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.

This shows how Netlogger can be used to emulate sprintf functionality:

Environment variables

If you provide a NULL url to NL_logger_module(), then NetLogger will look for the enviroment variable 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.

Retrieved from "http://acs.lbl.gov/NetLoggerWiki/index.php/C_language"
Personal tools