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_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_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.