Logging

## Macros

#define | FUNC __FUNCTION__
#define | g_info(fmt, ...) g_log(G_LOG_DOMAIN, G_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)
#define | VMTOOLS_LOGGING_LEVEL_DEFAULT "message"
#define | vm_critical(fmt, ...) g_critical("%s: " fmt, FUNC, ## __VA_ARGS__)
#define | vm_debug(fmt, ...) g_debug("%s: " fmt, FUNC, ## __VA_ARGS__)
#define | vm_error(fmt, ...) g_error("%s: " fmt, FUNC, ## __VA_ARGS__)
#define | vm_info(fmt, ...) g_info("%s: " fmt, FUNC, ## __VA_ARGS__)
#define | vm_message(fmt, ...) g_message("%s: " fmt, FUNC, ## __VA_ARGS__)
#define | vm_warning(fmt, ...) g_warning("%s: " fmt, FUNC, ## __VA_ARGS__)

## Functions

G_BEGIN_DECLS void | VMTools_ConfigLogToStdio (const gchar *domain)
void | VMTools_ConfigLogging (const gchar *defaultDomain, GKeyFile *cfg, gboolean force, gboolean reset)

## Detailed Description

The Tools logging facility is built on top of glib's logging functions (http://developer.gnome.org/glib/stable/glib-Message-Logging.html). Some convenience macros built on top of glib's existing macros are also provided.

Logging is configurable on a per-domain basis. The configuration options for each domain are:

- level: minimum log level to log. Also used to declare specific log domain configurations.
  - Valid values: error, critical, warning, message, info, debug, none
  - This value is required when configuring a domain.
- handler: the handler to use when logging.
  - Valid values: std, outputdebugstring (Win32-only), file, file+ (same as "file", but appends to existing log file), vmx, syslog.
  - Default: "syslog".

For file handlers, the following extra configuration information can be provided:

- data: path to the log file, required.
- maxOldLogFiles: maximum number of rotated log files to keep around. By default, at most 10 backed up log files will be kept. Value should be >= 1.
- maxLogSize: maximum size of each log file, defaults to 10 (MB). A value of 0 disables log rotation.

When using syslog on Unix, the following options are available:

- facility: either of "daemon", "user" or "local[0-7]". Controls whether to connect to syslog as LOG_DAEMON, LOG_USER or LOG_LOCAL[0-7], respectively (see syslog(3)). Defaults to "user". Any unknown value is mapped to LOG_USER. This option should be defined for the application's default log domain (it's ignored for all other domains).

The "vmx" logger will log all messages to the host; it's not recommended for normal use, since writing to the host log is an expensive operation and can also affect other running applications that need to send messages to the host. Do not use this logger unless explicitly instructed to do so.

Log levels:

glib log levels are supported. The error levels from most to least severe:

'error' - fatal errors 'critical' - critical errors 'warning' - something unexpected happened (useful when an error will be reported back.) 'message' - messages about services starting, version data 'info' - informational and diagnostic messages. 'debug' - debug messages, typically only of interest ot a developer

Until vSphere 6.0, the default logging level for beta/rel is 'warning'. Since vsphere 6.0 it is 'message'.

When adding new logging messages, be sure to use the appropriate level to balance the amount of logging and usability. The goal is to be able to debug a customer problem with the default log level whenever possible, while not filling up logfiles with noise or customer-sensitive data.

Logging configuration should be under the "[logging]" group in the application's configuration file.

Each application can specify a default log domain (which defaults to "vmtools"). If no handler is specified for a particular domain when logging, the default handler will be used. The default logging level for the default domain is "warning" in non-debug builds, and "message" in debug builds.

Example of logging configuration in the config file:

    * [logging]
    * # Turns on logging globally. It can still be disabled for each domain.
    * log = true
    *
    * # Disables core dumps on fatal errors; they're enabled by default.
    * enableCoreDump = false
    *
    * # Defines the "vmsvc" domain, logging to stdout/stderr.
    * vmsvc.level = info
    * vmsvc.handler = std
    *
    * # Defines the "unity" domain, logging to a file.
    * unity.level = warning
    * unity.handler = file
    * unity.data = /tmp/unity.log
    *
    * # Defines the "vmtoolsd" domain, and disable logging for it.
    * vmtoolsd.level = none
    *

Log file names can contain references to pre-defined variables. The following variables are expanded when determining the path of the log file:

- ${USER}: expands to the current user's login name
- ${PID}: expands to the current process's ID.
- ${IDX}: expands to the log file index (for rolling logs).

So, for example, log.${USER}.${PID}.txt would expand to "log.jdoe.1234.txt" for user "jdoe" if the process ID were 1234.

## Macro Definition Documentation

## g_info

#define g_info | ( |  | fmt,
|  |  | ...
| ) |  | g_log(G_LOG_DOMAIN, G_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)

Log a message with G_LOG_LEVEL_INFO; this function is missing in glib < 2.39 for whatever reason.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## vm_critical

#define vm_critical | ( |  | fmt,
|  |  | ...
| ) |  | g_critical("%s: " fmt, FUNC, ## __VA_ARGS__)

Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## vm_debug

#define vm_debug | ( |  | fmt,
|  |  | ...
| ) |  | g_debug("%s: " fmt, FUNC, ## __VA_ARGS__)

Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## vm_error

#define vm_error | ( |  | fmt,
|  |  | ...
| ) |  | g_error("%s: " fmt, FUNC, ## __VA_ARGS__)

Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## vm_info

#define vm_info | ( |  | fmt,
|  |  | ...
| ) |  | g_info("%s: " fmt, FUNC, ## __VA_ARGS__)

Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## vm_message

#define vm_message | ( |  | fmt,
|  |  | ...
| ) |  | g_message("%s: " fmt, FUNC, ## __VA_ARGS__)

Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## vm_warning

#define vm_warning | ( |  | fmt,
|  |  | ...
| ) |  | g_warning("%s: " fmt, FUNC, ## __VA_ARGS__)

Wrapper around the corresponding glib function that automatically includes the calling function name in the log message. The "fmt" parameter must be a string constant.

Parameters

  [in] | fmt | Log message format.
  [in] | ... | Message arguments.

## VMTOOLS_LOGGING_LEVEL_DEFAULT

#define VMTOOLS_LOGGING_LEVEL_DEFAULT "message"

default logging level

## Function Documentation

## VMTools_ConfigLogging()

void VMTools_ConfigLogging | ( | const gchar * | defaultDomain,
|  | GKeyFile * | cfg,
|  | gboolean | force,
|  | gboolean | reset
| ) |  |

Configures the logging system according to the configuration in the given dictionary.

Optionally, it's possible to reset the logging subsystem; this will shut down all log handlers managed by the vmtools library before configuring the log system, which means that logging will behave as if the application was just started. A visible side-effect of this is that log files may be rotated (if they're not configure for appending).

Parameters

  [in] | defaultDomain | Name of the default log domain.
  [in] | cfg | The configuration data. May be NULL.
  [in] | force | Whether to force logging to be enabled.
  [in] | reset | Whether to reset the logging subsystem first.

## VMTools_ConfigLogToStdio()

G_BEGIN_DECLS void VMTools_ConfigLogToStdio | ( | const gchar * | domain | ) |

Configures the logging system to log to the STDIO.

Parameters

  [in] | defaultDomain | Name of the default log domain.