open-vm-tools 13.0.10: Logging

open-vm-tools 13.0.10

Logging

## Macros
#define | FUNC __FUNCTION__
#define | g_info(fmt, ...)
#define | VMTOOLS_LOGGING_LEVEL_DEFAULT "message"
#define | vm_critical(fmt, ...)
#define | vm_debug(fmt, ...)
#define | vm_error(fmt, ...)
#define | vm_info(fmt, ...)
#define | vm_message(fmt, ...)
#define | vm_warning(fmt, ...)
#define | VM_SAFE_STR(string)
#define | host_warning(fmt, ...)
#define | guest_warning(fmt, ...)
#define | host_message(fmt, ...)
#define | guest_message(fmt, ...)
#define | host_info(fmt, ...)
#define | guest_info(fmt, ...)
#define | host_debug(fmt, ...)
#define | guest_debug(fmt, ...)

## Enumerations
enum | LogWhere { TO_HOST , IN_GUEST }

## Functions
G_BEGIN_DECLS void | VMTools_ConfigLogToStdio (const gchar *domain)
void | VMTools_ConfigLogging (const gchar *defaultDomain, GKeyFile *cfg, gboolean force, gboolean reset)
void | VMTools_UseVmxGuestLog (const gchar *appName)
void | VMTools_SetupVmxGuestLog (gboolean refreshRpcChannel, GKeyFile *cfg, const gchar *level)
void | VMTools_TeardownVmxGuestLog (void)
void | VMTools_Log (LogWhere where, GLogLevelFlags level, const gchar *domain, const gchar *fmt,...)
void | VMTools_VmxLog (RpcChannel *chan, const gchar *fmt,...)
void | VMTools_VmxLogThrottled (uint32 *count, RpcChannel *chan, const gchar *fmt,...)

## 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,
|  |  | ... )

Value:
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.

## ◆ guest_debug

#define guest_debug | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(IN_GUEST, G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)
VMTools_Log
void VMTools_Log(LogWhere where, GLogLevelFlags level, const gchar *domain, const gchar *fmt,...)
Definition vmtoolsLog.c:2779

## ◆ guest_info

#define guest_info | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(IN_GUEST, G_LOG_LEVEL_INFO, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ guest_message

#define guest_message | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(IN_GUEST, G_LOG_LEVEL_MESSAGE, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ guest_warning

#define guest_warning | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(IN_GUEST, G_LOG_LEVEL_WARNING, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ host_debug

#define host_debug | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(TO_HOST, G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ host_info

#define host_info | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(TO_HOST, G_LOG_LEVEL_INFO, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ host_message

#define host_message | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(TO_HOST, G_LOG_LEVEL_MESSAGE, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ host_warning

#define host_warning | ( |  | fmt,
|  |  | ... )

Value:
VMTools_Log(TO_HOST, G_LOG_LEVEL_WARNING, G_LOG_DOMAIN, fmt, ## __VA_ARGS__)

## ◆ vm_critical

#define vm_critical | ( |  | fmt,
|  |  | ... )

Value:
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,
|  |  | ... )

Value:
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,
|  |  | ... )

Value:
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,
|  |  | ... )

Value:
g_info("%s: " fmt, FUNC, ## __VA_ARGS__)
g_info
#define g_info(fmt,...)
Definition log.h:163

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,
|  |  | ... )

Value:
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_SAFE_STR

#define VM_SAFE_STR | ( |  | string | ) |

Value:
(string != NULL ? string : "(NULL)")

## ◆ vm_warning

#define vm_warning | ( |  | fmt,
|  |  | ... )

Value:
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.

## ◆ VMTools_Log()

void VMTools_Log | ( | LogWhere | where,
|  | GLogLevelFlags | level,
|  | const gchar * | domain,
|  | const gchar * | fmt,
|  |  | ... )

VMTools_Log – Entry log function.

Use this function to log different log messages on host and in guest. Usually a macro is defined to invoke this function once for the host side logging and the second time for the guest side logging.

Parameters

  [in] | where | where the log should go.
  [in] | level | Log level.
  [in] | domain | Log domain.
  [in] | fmt | Log message output format.

## ◆ VMTools_SetupVmxGuestLog()

void VMTools_SetupVmxGuestLog | ( | gboolean | refreshRpcChannel,
|  | GKeyFile * | cfg,
|  | const gchar * | level )

Initialize the Vmx Guest Logging. If the guest.log.* RPC is supported, set the level from the RPC query. Otherwise, read tools.conf for the vmx handler setting. This function is called from the tools initialization, tools reset, and the tools options handler code path.

Parameters

  [in] | refreshRpcChannel | whether to create a new RPC channel.
  | [in/opt] | cfg tools config file object.
  | [in/opt] | level log level string from vmx

## ◆ VMTools_TeardownVmxGuestLog()

void VMTools_TeardownVmxGuestLog | ( | void |  | ) |

Destroy the dedicated RPCI channel set up for the Vmx Guest Logging. This function is called from the tools process exit code path.

## ◆ VMTools_UseVmxGuestLog()

void VMTools_UseVmxGuestLog | ( | const gchar * | appName | ) |

Set up a global flag that indicates we shall use the vmx guest logger. You might wonder why this function and the VMTools_SetVmxGuestLog() are NOT one. This is because we need to call VMTools_SetupVmxGuestLog() after VMTools_ConfigLogging() since if we failed to setup the vmx guest logger, we can leverage the file system logging facility to log those setup failures. However, VMTools_ConfigLogging() code path needs to know whether to disable the old vmx log handler or not. Not all tools app have migrated to the new vmx guest logger. To keep the compatibility we should not mess up with the VMTools_ConfigLogging() code path by restructuring it yet.

Parameters

  [in] | appName | the application name, also serves as a routing tag of the log message for the host side.