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
Thektr 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() andether_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_ALLis 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
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.