Lustre 1.6 Operations Manual

23.2.8 Adding Debugging to the Lustre Source Code
In the Lustre source code, the debug infrastructure provides a number of macros
which aid in debugging or reporting serious errors. All of these macros depend on
having the DEBUG_SUBSYSTEM variable set at the top of the file:
#define DEBUG_SUBSYSTEM S_PORTALS
■ LBUG: A panic-style assertion in the kernel which causes Lustre to dump its
circular log to the /tmp/lustre-log file. This file can be retrieved after a reboot.
LBUG freezes the thread to allow capture of the panic stack. A system reboot is
needed to clear the thread.
■ LASSERT: Validates a given expression as true, otherwise calls LBUG. The failed
expression is printed on the console, although the values that make up the
expression are not printed.
■ LASSERTF: Similar to LASSERT but allows a free-format message to be printed,
like printf/printk.
■ CDEBUG: The basic, most commonly used debug macro that takes just one more
argument than standard printf - the debug type. This message adds to the debug
log with the debug mask set accordingly. Later, when a user retrieves the log for
troubleshooting, they can filter based on this type.
CDEBUG(D_INFO, "This is my debug message: the number is %d\n", number).
■
■
■
■
■
■
CERROR: Behaves similarly to CDEBUG, but unconditionally prints the message
in the debug log and to the console. This is appropriate for serious errors or fatal
conditions:
CERROR("Something very bad has happened, and the return code is %d.\n", rc);
ENTRY and EXIT: Add messages to aid in call tracing (takes no arguments).
When using these macros, cover all exit conditions to avoid confusion when the
debug log reports that a function was entered, but never exited.
LDLM_DEBUG and LDLM_DEBUG_NOLOCK: Used when tracing MDS and VFS
operations for locking. These macros build a thin trace that shows the protocol
exchanges between nodes.
DEBUG_REQ: Prints information about the given ptlrpc_request structure.
OBD_FAIL_CHECK: Allows insertion of failure points into the Lustre code. This
is useful to generate regression tests that can hit a very specific sequence of
events. This works in conjunction with "sysctl -w lustre.fail_loc={fail_loc}" to set a
specific failure point for which a given OBD_FAIL_CHECK will test.
OBD_FAIL_TIMEOUT: Similar to OBD_FAIL_CHECK. Useful to simulate hung,
blocked or busy processes or network devices. If the given fail_loc is hit,
OBD_FAIL_TIMEOUT waits for the specified number of seconds.
23-10 Lustre 1.6 Operations Manual • September 2008