Logging-related y-lib functions. More...

#include "y_core.c"
#include "y_loadrunner_utils.c"

Functions
char *	y_make_datetimestamp (time_t time, unsigned short millitm)
	Convert a unixtime style timestamp to a date and time represented as YYYY-MM-DD HH:MM:SS.mmm. More...

char *	y_get_datetimestamp ()
	Returns the current time converted represented as YYYY-MM-DD HH:MM:SS.mmm. More...

void	y_setup_logging ()
	Turn on 'extra logging', when available. More...

void	y_log_to_report (char *message)
	If extra logging was enabled force a line to be logged to the logfile - even if regular logging was turned off. Enable extra logging by calling y_setup_logging() More...

void	y_log_error (char *message)
	Log an error message, with a timestamp, if extra logging is enabled. More...

void	y_log_warning (char *message)
	Log a warning, with a timestamp, if extra logging is enabled. More...

void	y_log_save ()
	Save the loglevel for later restoration through y_log_restore(). More...

void	y_log_turn_off_without_saving ()
	Force all logging off unconditionally, without saving the old state. More...

void	y_log_turn_off ()
	Save the current loglevel and turn off logging. More...

void	y_log_turn_off_permanently ()
	Turn all logging off and make sure it stays that way. More...

void	y_log_set_brief ()
	Set the log level to "brief" messages only. More...

void	y_log_set_extended ()
	Set the log level to show all messages, including extended result data, parameters, and tracing information. More...

void	y_log_restore ()
	Restore the loglevel to previous state. To be exact, it will restore it to the state it was in before the last call to y_log_set_{off\|on\|brief\|extended}() or y_log_save(). More...

void	y_log_turn_on ()
	Turn logging on. More...

void	y_log_force_message (char *message)
	Log a message forcefully, bypassing the current log settings. More...

int	y_write_to_log (char filename, char content)
	Write a string prepended with date and time to the specified (log)file. More...

void	y_disk_space_guard (double max_free_percentage)
	Detect low disk space situations on the generator and turn all logging off if not enough space is left. More...

void	y_disk_space_usage_guard (double limit_mebibytes_used)
	Detect excessive disk usage by the test and turn all further logging off if more than a specific limit number of mebibytes has been used. More...

Detailed Description

Logging-related y-lib functions.

Note that some of these are a bit marginal - the disk space guards for instance are logging related in the sense that they will turn all logging off when too much disk space has been used, but they aren't exactly log manipulation functions in the low-level sense.

Definition in file y_logging.c.

Function Documentation

void y_disk_space_guard ( double max_free_percentage )

Detect low disk space situations on the generator and turn all logging off if not enough space is left.

When called, this function will check the amount of space left on the generator's "output" device / directory. If the percentage of free space is lower than the treshold percentage, it will generate an error transaction "---DISK SPACE LOW IN LOG FOLDER FOR {y_hostname_generator}---" and turn all further logging off until the end of the test, using y_log_turn_off_permanently().

Note: Scripts that call lr_debug_message() or the various y_lib() toggle functions to turn the loglevel back up may ignore this restriction.

Loadrunner does not protect the generators' disks from overflowing, even if the test is writing out a lot of information to the logs really quickly. If a disk fills up on the generator or the disk the controller uses for results collation overflows there is no graceful recovery. Collation will fail and test results may be hard or impossible to recover. This kind of situation can occur when temporary service disruptions happen (triggering a flood of 'log on error' messages), but also if runtime settings are incorrect and the test was configured to log everything.

In order to prevent this from happening scripts should regularly call to both y_disk_space_guard() and y_disk_space_usage_guard() with some reasonable limits.

Parameters

[in] max_free_percentage The amount of free diskspace as a percentage of total space that will cause the logging to turn off.

Author: Floris Kraak

Definition at line 401 of file y_logging.c.

void y_disk_space_usage_guard ( double limit_mebibytes_used )

Detect excessive disk usage by the test and turn all further logging off if more than a specific limit number of mebibytes has been used.

When called, this function will check the amount of space used on the generator's "output" device / directory since the first call to this function. If the amount of used space exceeds the treshold it will generate an error transaction "---DISK SPACE LOW IN LOG FOLDER FOR {y_hostname_generator}---" and turn all further logging off until the end of the test, using y_log_turn_off_permanently().

Note: Scripts that call lr_debug_message() or the various y_lib() toggle functions to turn the loglevel back up may ignore this restriction.

Loadrunner does not protect the generators' disks from overflowing, even if the test is writing out a lot of information to the logs really quickly. If a disk fills up on the generator or the disk the controller uses for results collation overflows there is no graceful recovery. Collation will fail and test results may be hard or impossible to recover. This kind of situation can occur when temporary service disruptions happen (triggering a flood of 'log on error' messages), but also if runtime settings are incorrect and the test was configured to log everything.

Note: Because of the way this measurement is done, it may also trigger if some other process on the same machine starts writing large amounts of data to the same device.

In order to prevent this from happening scripts should regularly call to both y_disk_space_guard() and y_disk_space_usage_guard() with some reasonable limits.

Note: The contents of the generator's output folder will be transferred to the controller during collation. If the sum of the output directories for the generators exceed the size of that filesystem collation will fail, even if there is enough space on the generators. Therefore, set this low enough to make sure that if all generators output folders get filled to the limit the controller will still have enough space for it's collation process.

Parameters

[in] limit_mebibytes_used The amount of mebibytes the test is allowed to used on the generator's target directory.

Author: Floris Kraak

Definition at line 456 of file y_logging.c.

char* y_get_datetimestamp ( )

Returns the current time converted represented as YYYY-MM-DD HH:MM:SS.mmm.

Returns: The string represation of the current time, formatted as YYYY-MM-DD HH:MM:SS.mmm.

Deprecated:: Use lr_save_datetime() or direct ftime() calls instead.

See also: y_make_datetimestamp(), y_get_current_time()

Definition at line 87 of file y_logging.c.

void y_log_error ( char * message )

Log an error message, with a timestamp, if extra logging is enabled.

Parameters

[in] message The error message to be logged.

Deprecated:: Forcing your error messages to get logged may not be the best idea there is. And I don't know of anyone using this, either.

See also: y_log_to_report()

Definition at line 153 of file y_logging.c.

void y_log_force_message ( char * message )

Log a message forcefully, bypassing the current log settings.

Typically used for generating datafiles within scripts with the loglevel set to OFF, or things of that sort.

Example:

 lr_set_debug_message(LR_MSG_CLASS_DISABLE_LOG, LR_SWITCH_ON);
 lr_set_debug_message(LR_MSG_CLASS_AUTO_LOG, LR_SWITCH_OFF);
 lr_log_message("Before");              // Nothing gets logged here.
 y_log_force_message("Forced message"); // "Forced message" appears in the logs.
 lr_log_message("After");               // No output again.

Author: Floris Kraak

Definition at line 328 of file y_logging.c.

void y_log_restore ( )

Restore the loglevel to previous state. To be exact, it will restore it to the state it was in before the last call to y_log_set_{off|on|brief|extended}() or y_log_save().

Note: Multiple calls to y_log_set_* functions in a row will overwrite the previous saved state, making the first state potentially unrecoverable.

Author: Floris Kraak

Definition at line 274 of file y_logging.c.

void y_log_save ( )

Save the loglevel for later restoration through y_log_restore().

This is called by the various y_log_* functions to make sure the loglevel can be put back the way it was.

Author: Floris Kraak

Definition at line 182 of file y_logging.c.

void y_log_set_brief ( )

Set the log level to "brief" messages only.

Note: Calling y_log_restore() will restore the loglevel to the state it was in before this call.

Useful when you want to, say, not see that big PDF you are downloading somewhere in your logs but do want to see the rest of the logging.

Author: Floris Kraak

Definition at line 241 of file y_logging.c.

void y_log_set_extended ( )

Set the log level to show all messages, including extended result data, parameters, and tracing information.

Note: Calling y_log_restore() will restore the loglevel to the state it was in before this call.

Useful when you want to debug a particular step in the script.

Author: Floris Kraak

Definition at line 256 of file y_logging.c.

void y_log_to_report ( char * message )

If extra logging was enabled force a line to be logged to the logfile - even if regular logging was turned off. Enable extra logging by calling y_setup_logging()

Parameters

[in] message The message to be logged.

Deprecated:: Logging with a timestamp sounds useful, but I don't think it should be called "y_log_to_report()", and it is rather customer specific, too. Also, forced logging really should be it's own thing.

See also: y_setup_logging(), y_log_force_message()

Definition at line 128 of file y_logging.c.

void y_log_turn_off ( )

Save the current loglevel and turn off logging.

Note: Calling y_log_restore() will restore the loglevel to the state it was in before this call.

Author: Floris Kraak

Definition at line 213 of file y_logging.c.

void y_log_turn_off_permanently ( )

Turn all logging off and make sure it stays that way.

This will overwrite the state saved by y_log_save() with "No logging at all, please.", so that y_log_restore() can't turn things back on.

Note: Direct calls to lr_set_debug_message() will still be able to turn things back on.

Warning: Mixing calls to y_log_* functions with calls to lr_debug_message() is not wise and may yield unpredictable results.

Author: Floris Kraak

Definition at line 228 of file y_logging.c.

void y_log_turn_off_without_saving ( )

Force all logging off unconditionally, without saving the old state.

This is used by various y_log_* functions to get the loglevel to a known state.

Author: Floris Kraak

Definition at line 195 of file y_logging.c.

void y_log_turn_on ( )

Turn logging on.

What this function does depends on the saved loglevel.

If the saved loglevel was "no logging", y_log_set_extended() is called, turning all logging on.
Otherwise, y_log_restore() is called to undo the previous loglevel change.

Note: If the previous loglevel was "brief" while the current level is "extended", this may result in less logging.

Todo:: Either fix that, or remove this function.

Author: Floris Kraak

Definition at line 302 of file y_logging.c.

void y_log_warning ( char * message )

Log a warning, with a timestamp, if extra logging is enabled.

Parameters

[in] message The error message to be logged.

Deprecated:: Unused, and forcibly logging things even if logging is turned off is rather impolite to begin with ;-)

See also: y_log_to_report()

Definition at line 167 of file y_logging.c.

char* y_make_datetimestamp	(	time_t	time,
		unsigned short	millitm
	)

Convert a unixtime style timestamp to a date and time represented as YYYY-MM-DD HH:MM:SS.mmm.

Parameters

[in]	time	- the unix time stamp, as reported by ftime()
	millitm	- the milliseconds belonging to the time stamp

Returns: The string represation of the timestamp, formatted as YYYY-MM-DD HH:MM:SS.mmm.

See also: y_get_datetimestamp(), y_get_current_time()

Deprecated:: lr_save_datetime() really should be used for this kind of thing.

Definition at line 60 of file y_logging.c.

void y_setup_logging ( )

Turn on 'extra logging', when available.

This is one of the remnants of a bit of old code that would log every transaction stop/start with a timestamp, so that post-test-analysis of responstimes could be done with custom tools. Unless you are running a very old y-lib based script there is no reason why you should use this, as y_set_start_transaction_impl() and y_set_end_transaction_impl() should give you the tools you need to do something like that without polluting y-lib with it ;-)

Deprecated:: This will probably be removed in favor of y_set_transaction_implementation(), which is really how this kind of extra transaction logging should be done. Note that y_transaction.c hasn't used the extra logging stuff in some time ..

See also: y_log_to_report()

Definition at line 110 of file y_logging.c.

int y_write_to_log	(	char *	filename,
		char *	content
	)

Write a string prepended with date and time to the specified (log)file.

The logged line will have the following format: YYYYMM,DDHHmmss,{y_virtual_user_group},{y_virtual_user_id},{y_scid},{content}

Parameters

[in]	filename	The file name of the target file.
[in]	content	The logmessage to be written.

Returns: Negative number in case of an error, zero otherwise.

Example:

1 y_write_to_log("c:\\logfile.txt", "Everything went great");

Example output: 20091126,215212,SomeGroup,3,4,Everything went great

Author: Raymond de Jongh

Definition at line 354 of file y_logging.c.

Functions

Detailed Description

Function Documentation