- Add a section on logging ktr entries to disk via ALQ.

1 files changed, 42 insertions, 0 deletions

diff --git a/share/man/man4/ktr.4 b/share/man/man4/ktr.4
index a00f407..84a61bd 100644
--- a/share/man/man4/ktr.4
+++ b/share/man/man4/ktr.4
@@ -32,6 +32,7 @@
 .Nd kernel tracing facility
 .Sh SYNOPSIS
 .Cd options KTR
+.Cd options KTR_ALQ
 .Cd options KTR_COMPILE=(KTR_LOCK|KTR_INTR|KTR_PROC)
 .Cd options KTR_CPUMASK=0x3
 .Cd options KTR_ENTRIES=8192
@@ -136,6 +137,47 @@ modifier is specified, then they are displayed in addition to the normal
 output.
 Note that the events are displayed in reverse chronological order.
 That is, the most recent events are displayed first.
+.Ss Logging ktr to disk
+The
+.Dv KTR_ALQ
+option can be used to log ktr entries to disk for post analysis using the
+.Xr ktrdump 8
+utility.
+Due to the potentially high volume of trace messages the trace mask should be
+selected carefully.
+This feature is configured through a group of sysctls.
+.Pp
+.Va debug.ktr.alq_file
+displays or sets the file that ktr will log to.  By default its value is
+"/tmp/ktr.out".
+If the file name is changed while ktr is enabled it will not take effect until
+the next invocation.
+.Pp
+.Va debug.ktr.alq_enable
+enables logging of ktr entries to disk if it is set to one.
+Setting this to 0 will terminate logging.
+.Pp
+.Va debug.ktr.alq_max
+is the maximum number of entries that will be recorded to disk, or 0 for
+infinite.
+This is helpful for limiting the number of particularly high frequency entries
+that are recorded.
+.Pp
+.Va debug.ktr.alq_depth
+determines the number of entries in the write buffer.
+This is the buffer that holds entries before they are written to disk and
+defaults to the value of the
+.Dv KTR_ENTRIES
+option.
+.Pp
+.Va debug.ktr.alq_failed
+records the number of times we failed to write an entry due to overflowing the
+write buffer.
+This may happen if the frequency of the logged ktr messages outpaces the depth
+of the queue.
+.Pp
+.Va debug.ktr.alq_cnt
+records the number of entries that have currently been written to disk.
 .Sh SEE ALSO
 .Xr ktr 9 ,
 .Xr ktrdump 8