DragonFly On-Line Manual Pages
KTR(4) DragonFly Kernel Interfaces Manual KTR(4)
NAME
ktr -- kernel tracing facility
SYNOPSIS
options KTR
options KTR_ENTRIES=8192
options KTR_VERBOSE=1
options KTR_ALL
options KTR_ACPI_EC
options KTR_CTXSW
options KTR_DMCRYPT
options KTR_ETHERNET
options KTR_IF_BGE
options KTR_IF_EM
options KTR_IF_EMX
options KTR_IF_POLL
options KTR_IF_START
options KTR_IFQ
options KTR_IPIQ
options KTR_KERNENTRY
options KTR_LAPIC
options KTR_MEMORY
options KTR_SERIALIZER
options KTR_SPIN_CONTENTION
options KTR_TESTLOG
options KTR_TOKENS
options KTR_TSLEEP
options KTR_USCHED_BSD4
options KTR_USCHED_DFLY
DESCRIPTION
The ktr facility allows kernel events to be logged while the kernel
executes so that they can be examined later when debugging. The only
mandatory option to enable ktr is options KTR.
The KTR_ENTRIES option sets the size of the buffer of events. It must be
a power of two. The size of the buffer in the currently running kernel
can be found via the read-only sysctl debug.ktr.entries. By default the
buffer contains 2048 entries.
For debugging purposes, the following ktr related kernel options exist:
KTR_ALL turns on all options
KTR_ACPI_EC ACPI Embedded Controller related data
KTR_CTXSW context switches
KTR_DMCRYPT read and write strategy paths of dm(4)'s crypt
target
KTR_ETHERNET cost of ether_input() and ether_dispatch()
KTR_IF_BGE bge(4) interrupts and sent/received packets
KTR_IF_EM em(4) interrupts and sent/received packets
KTR_IF_EMX emx(4) interrupts and sent/received packets
KTR_IFQ classic ifq dequeue/enqueue operation
KTR_IF_POLL polling(4) operation
KTR_IF_START running/avoiding/scheduling ifnet.if_start
KTR_IPIQ IPI related data (IPI requests, CPU synchronization
etc.)
KTR_LAPIC Track LAPIC operation, for example EOI writes.
KTR_KERNENTRY entry of the kernel from userland (faults, syscalls)
KTR_MEMORY kmalloc(9) and kfree(9) events
KTR_SERIALIZER serializer(9) related events
KTR_SPIN_CONTENTION spinlock(9) contention
KTR_TESTLOG IPI performance testing
KTR_TOKENS LWKT token related events
KTR_TSLEEP tsleep(9) and wakeup(9)
KTR_USCHED_BSD4 usched_bsd4 scheduling decisions
KTR_USCHED_DFLY usched_dfly scheduling decisions
Verbose Mode
By default, events are only logged to the internal buffer for examination
later, but if the verbose flag is set then they are dumped to the kernel
console as well. This flag can also be set from the loader via the
debug.ktr.verbose environment variable, or it can be examined and set
after booting via the debug.ktr.verbose sysctl. If the flag is set to
zero, which is the default, then verbose output is disabled. If the flag
is set to one, then the contents of the log message and the CPU number
are printed to the kernel console. If the flag is greater than one, then
the filename and line number of the event are output to the console in
addition to the log message and the CPU number. The KTR_VERBOSE option
enables verbose mode and sets the flag to one.
Examining the Events
The KTR buffer can be examined with ktrdump(8), gdb(1) or from within
ddb(4) via the show ktr [/v] command. This command displays the contents
of the trace buffer one page at a time. At the ``--more--'' prompt, the
Enter key displays one more entry and prompts again. The spacebar
displays another page of entries. Any other key quits. By default the
timestamp, filename, and line number are not displayed with each log
entry. If the /v 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.
SYSCTL VARIABLES
debug.ktr.*_enable A 32 bit mask used to control event logging.
Each bit corresponds to one or more events
depending on the values of the maskbit
parameters that were passed to the KTR_INFO(9)
calls which declared the events.
Unless KTR_ALL is specified in the kernel
configuration, the default is to turn on logging
for all corresponding events (i.e. setting the
sysctl to -1).
debug.ktr.*_mask Read only sysctls (one per event) that show the
debug.ktr.*_enable values corresponding to the
events.
debug.ktr.resynchronize Resynchronize the TSC across all CPUs 10 times
per second in an attempt to reduce drift errors.
Note that this is very expensive and therefore
the default is 0.
SEE ALSO
gdb(1), ddb(4), ktrdump(8), ktr(9)
HISTORY
The KTR kernel tracing facility first appeared in BSD/OS 3.0 and was
imported into FreeBSD 5.0 and DragonFly 1.1. It was completely rewritten
by Matthew Dillon in DragonFly 1.3.
DragonFly 5.5 February 18, 2019 DragonFly 5.5