KTR(4) BSD Kernel Interfaces Manual KTR(4)NAMEktr — kernel tracing facility
SYNOPSIS
options KTR
options KTR_ENTRIES=8192
options KTR_VERBOSE=1
options KTR_ALL
options KTR_ETHERNET
options KTR_IF_BGE
options KTR_IF_EM
options KTR_IF_START
options KTR_IFQ
options KTR_IPIQ
options KTR_KERNENTRY
options KTR_MEMORY
options KTR_POLLING
options KTR_SERIALIZER
options KTR_SPIN_CONTENTION
options KTR_TESTLOG
options KTR_TOKENS
options KTR_USB_MEMORY
options KTR_CTXSW
DESCRIPTION
The ktr facility allows kernel events to be logged while the kernel exe‐
cutes so that they can be examined later when debugging. The only manda‐
tory option to enable ktr is options KTR.
The KTR_ENTRIES option sets the size of the buffer of events. It should
be a power of two. The size of the buffer in the currently running ker‐
nel 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_ETHERNET cost of ether_input_chain() and
ether_input_dispatch()
KTR_IF_BGE bge(4) interrupts and sent/received packets
KTR_IF_EM em(4) interrupts, polling and sent/received packets
KTR_IFQ classic ifq dequeue/enqueue operation
KTR_IF_START running/avoiding/scheduling ifnet.if_start
KTR_IPIQ IPI related data (IPI requests, CPU synchronization
etc.)
KTR_KERNENTRY entry of the kernel from userland (faults, syscalls)
KTR_MEMORY kmalloc(9) and kfree(9) events
KTR_POLLING polling(4) begins and ends
KTR_SERIALIZER serializer(9) related events
KTR_SPIN_CONTENTION spinlock(9) contention
KTR_TESTLOG IPI performance testing
KTR_TOKENS LWKT token related events
KTR_USB_MEMORY USB memory allocation
KTR_CTXSW context switches
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 dis‐
plays 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 addi‐
tion to the normal output. Note that the events are displayed in reverse
chronological order. That is, the most recent events are displayed
first.
SEE ALSOgdb(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.
BSD October 1, 2008 BSD
