fill Policy

For some problems, you might wish to use a single in-kernel buffer. While this approach can be implemented with the switch policy and appropriate D constructs by incrementing a variable in D and predicating an exit() action appropriately, such an implementation does not eliminate the possibility of drops. To request a single, large in-kernel buffer, and continue tracing until one or more of the per-CPU buffers has filled, use the fill buffer policy. Under this policy, tracing continues until an enabled probe attempts to trace more data than can fit in the remaining principal buffer space. When insufficient space remains, the buffer is marked as filled and the consumer is notified that at least one of its per-CPU buffers has filled. Once dtrace(1M) detects a single filled buffer, tracing is stopped, all buffers are processed and dtrace exits. No further data will be traced to a filled buffer even if the data would fit in the buffer.

To use the fill policy, set the bufpolicy option to fill. For example, the following command traces every system call entry into a per-CPU 2K buffer with the buffer policy set to fill:

# dtrace -n syscall:::entry -b 2k -x bufpolicy=fill

fill Policy and END Probes

END probes normally do not fire until tracing has been explicitly stopped by the DTrace consumer. END probes are guaranteed to only fire on one CPU, but the CPU on which the probe fires is undefined. With fill buffers, tracing is explicitly stopped when at least one of the per-CPU principal buffers has been marked as filled. If the fill policy is selected, the END probe may fire on a CPU that has a filled buffer. To accommodate END tracing in fill buffers, DTrace calculates the amount of space potentially consumed by END probes and subtracts this space from the size of the principal buffer. If the net size is negative, DTrace will refuse to start, and dtrace(1M) will output a corresponding error message:

dtrace: END enablings exceed size of principal buffer

The reservation mechanism ensures that a full buffer always has sufficient space for any END probes.