NAME

omlc_init - initialize the liboml2 measurement API.

SYNOPSIS

#include <oml2/omlc.h>
int omlc_init(const char *appname, int *pargc, const char **argv, o_log_fn log_fn);

DESCRIPTION

omlc_init initializes the OML client library API. It must be called before any other function in the API can be called.

The appname argument is a string name for this application that the library uses when declaring schemata for measurement output to local file storage or to an oml2-server(1).

The pargc and argv parameters should refer to the program’s command line arguments, described in liboml2(1). pargc should be a pointer to the argc parameter of the program’s main() function, and argv should be identical to the main() function’s argv parameter. omlc_init scans the command line options for options starting with --oml-, and uses them to configure the API. The --oml- options and their arguments are then removed from the argv array, and *pargc is adjusted to account for their removal. This allows the application using liboml2 to do its own option parsing without getting confused by the --oml- options. The available --oml- options are listed in liboml2(1).

If the --oml-config option is specified then liboml2 reads its configuration from an external configuration file (the format is documented in liboml2.conf(5)). omlc_init also recognizes several environment variables, see liboml2(1). Generally, if an option can be configured on the command line or an environment variable, the command line option takes precedence. If an option can also be set using the config file, then the config file takes precedence.

USING A CUSTOM LOGGING FUNCTION

The log_fn parameter allows the user to supply a custom logging function. If log_fn is NULL then liboml2 uses its own logging function (the output file is specified by the user in the --oml-log-file command line argument, and defaults to stderr).

This allows to integrate OML log messages into the standard log system of the instrumented application. The expected prototype of the function is as follows. 

void (*o_log_fn)(int log_level, const char* format, ...)

In short, that function should take a log_level as its first argument, a printf(3)-like format string as the second, and expect a variable number of arguments to render, depending on the format string.

Filtering messages based on log_level according to the --oml-log-level option is already done by the library. However, the log_level of the message is provided to the custom logging function so the message can be directed to the appropriate logging facility if relevant.

Assuming the existence of an application-wide vlog() function taking variadic arguments (see stdarg(3)), the log_fn can be as simple as the following example.

#ifdef HAVE_LIBOML2             /* Only declare when OML is enabled at compile time */
static void log_fn(int log_level, const char *format, ...)
{
  va_list ap;                   /* For variadiac arguments parsing */
  int pri;                      /* Logging facility to use for the application */
  switch(log_level) {           /* Map OML log levels to the applications's */
  case O_LOG_ERROR:
  case O_LOG_WARN:
    pri = LOG_CRIT;
    break;
  case O_LOG_DEBUG:
  case O_LOG_DEBUG2:
  case O_LOG_DEBUG3:
  case O_LOG_DEBUG4:
    pri = LOG_DEBUG;
    break;
  case O_LOG_INFO:
  default:
    pri = LOG_INFO;
    break;
  }
  va_start(ap, format);         /* Get ready to extract arguments from the va_list */
  vlog(pri, format, ap);        /* Application's own variadic logging function */
  va_end(ap);                   /* Done */
}
#endif

RETURN VALUE

omlc_init() returns 0 on success. On error, -1 is returned and an error message will be written to the log file describing the error. If OML reporting is disabled by other means (e.g., the --oml-noop command line option), 1 is returned. If the function returns non-zero the API will be unusable. The application should either refrain from calling any other functions in the API, or it should terminate.

ERRORS

omlc_init() will return -1 if:

  • the appname contains whitespace or is NULL;

  • an OML command line option that expects an argument is missing its argument.

BUGS

If a problem you are experiencing is not addressed in the FAQ (http://oml.mytestbed.net/projects/oml/wiki/FAQ_and_Support) nor already present in the list of know bugs (http://oml.mytestbed.net/projects/oml/issues). You could discuss it on the mailing list (details and archives at http://oml.mytestbed.net/tab/show?id=oml).

It is however advisable to open a ticket on our issue tracker at http://oml.mytestbed.net/projects/oml/issues/new. Don’t forget to include details such as client and server logs (at [--oml-log-level|-d] 2). It also helps if you can share the source code of a (minimal, if possible) example reliably triggering the problem.

SEE ALSO

Manual Pages

oml2-server(1), liboml2(1), liboml2(3), liboml2.conf(5)

OML User Manual

http://oml.mytestbed.net/projects/oml/wiki/Documentation

OML Measurement Stream Protocol (OMSP)

http://oml.mytestbed.net/doc/oml/2.12/doxygen/omsp.html