How it works
Aggregation functions
count, sum, avg, min, max, quantize and lquantize answer different questions. Histograms are especially valuable for latency tails.
Thread-local state
self-> variables correlate entry and return events on the same thread. Clear state on completion to avoid stale timestamps.
Predicates first
Narrow by PID, executable or probe arguments before printing or collecting stacks.
Safe measurement
Plan a short collection interval, baseline CPU impact, avoid unbounded output, and note DTrace dropped records if reported.
Worked examples
Each example explains the question it answers, a reproducible starting point, what to look for, and operational precautions.
1. Average and maximum write latency
Contrast normal and worst-case writes.
syscall::write:entry { self->t = timestamp; }
syscall::write:return /self->t/
{
this->dt = timestamp-self->t;
@avg[execname] = avg(this->dt);
@max[execname] = max(this->dt);
self->t = 0;
}Interpretation: A high maximum with a low average suggests occasional stalls.
Operational note: Run commands in a test environment first; confirm device names, privileges and release-specific options.
2. Latency histogram
Find tail behavior rather than relying on averages.
syscall::read:entry { self->t = timestamp; }
syscall::read:return /self->t/
{
@hist[execname] = quantize(timestamp-self->t);
self->t = 0;
}Interpretation: Buckets are powers of two in nanoseconds.
Operational note: Run commands in a test environment first; confirm device names, privileges and release-specific options.
3. Count a specific executable
Reduce system-wide trace noise.
syscall:::entry
/execname == "httpd"/
{
@[probefunc] = count();
}Interpretation: Replace `httpd` with the observed executable name.
Operational note: Run commands in a test environment first; confirm device names, privileges and release-specific options.
4. Sample every second with a timer
Build a simple periodic observation.
tick-1s
{
printf("%Y observing...\n", walltimestamp);
}Interpretation: The `tick` provider can be used to schedule periodic actions.
Operational note: Run commands in a test environment first; confirm device names, privileges and release-specific options.
Before you finish
- Prefer aggregation to printing every event.
- Benchmark tracing overhead under representative load.
Primary documentation
Read the relevant Oracle documentation for exact version-specific flags, supported platforms and limitations: Oracle primary reference ↗.
This field manual is independent, not affiliated with or endorsed by Oracle. Command examples should be adapted to your environment.