aboutsummaryrefslogtreecommitdiffstats
path: root/include/sys/zfs_debug.h
diff options
context:
space:
mode:
authorSerapheim Dimitropoulos <[email protected]>2019-01-18 10:16:56 -0800
committerBrian Behlendorf <[email protected]>2019-01-18 10:16:56 -0800
commit1a759200e5aa080dd76208555ce83092f6110481 (patch)
tree333b37941ec0488b0181fadbead8f13ecc68f699 /include/sys/zfs_debug.h
parente45c1734a665e571599781811a0cd3128a550226 (diff)
Document guidelines for usage of zfs_dbgmsg
Reviewed-by: Richard Elling <[email protected]> Reviewed-by: Brian Behlendorf <[email protected]> Reviewed-by: Matt Ahrens <[email protected]> Reviewed-by: Igor Kozhukhov <[email protected]> Reviewed-by: George Melikov <[email protected]> Signed-off-by: Serapheim Dimitropoulos <[email protected]> Closes #8299
Diffstat (limited to 'include/sys/zfs_debug.h')
-rw-r--r--include/sys/zfs_debug.h18
1 files changed, 17 insertions, 1 deletions
diff --git a/include/sys/zfs_debug.h b/include/sys/zfs_debug.h
index f60932b5a..7564ae0e4 100644
--- a/include/sys/zfs_debug.h
+++ b/include/sys/zfs_debug.h
@@ -20,7 +20,7 @@
*/
/*
* Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
- * Copyright (c) 2012, 2017 by Delphix. All rights reserved.
+ * Copyright (c) 2012, 2018 by Delphix. All rights reserved.
*/
#ifndef _SYS_ZFS_DEBUG_H
@@ -58,6 +58,22 @@ extern int zfs_dbgmsg_enable;
extern void __zfs_dbgmsg(char *buf);
extern void __dprintf(boolean_t dprint, const char *file, const char *func,
int line, const char *fmt, ...);
+
+/*
+ * Some general principles for using zfs_dbgmsg():
+ * 1. We don't want to pollute the log with typically-irrelevant messages,
+ * so don't print too many messages in the "normal" code path - O(1)
+ * per txg.
+ * 2. We want to know for sure what happened, so make the message specific
+ * (e.g. *which* thing am I operating on).
+ * 3. Do print a message when something unusual or unexpected happens
+ * (e.g. error cases).
+ * 4. Print a message when making user-initiated on-disk changes.
+ *
+ * Note that besides principle 1, another reason that we don't want to
+ * use zfs_dbgmsg in high-frequency routines is the potential impact
+ * that it can have on performance.
+ */
#define zfs_dbgmsg(...) \
if (zfs_dbgmsg_enable) \
__dprintf(B_FALSE, __FILE__, __func__, __LINE__, __VA_ARGS__)