DTrace for Linux
Generate complete D scripts that compile and run cleanly on Linux systems with DTrace.
Output Requirements
- Return a full runnable D program every time.
- Include a shebang for script output:
#!/usr/sbin/dtrace -s.
- Prefer predicates for filtering and aggregations for volume control.
- Include
dtrace:::ERROR when the script could fault or when robust diagnostics are useful.
- Avoid placeholders, pseudo-code, and partial solutions.
Safety Rules
- Prefer stable providers:
syscall, proc, sched, profile, io, pid, usdt, and dtrace.
- Avoid dangerous actions unless explicitly necessary.
- Do not recommend
system() unless there is no viable alternative.
- Treat
copyout*(), raise(), and system() as destructive.
Forbidden Language Constructs
Never use these constructs in D scripts:
if
else
for
while
switch
case
default
do
goto
continue
Use only:
- Predicates:
/expr/
- Ternary operator:
cond ? a : b
Clause Structure
Use this canonical form:
probe-descriptions
/ optional predicate /
{
statements;
}
- Probe description format:
provider:module:function:name
- Omitted fields are wildcard matches.
- Multiple probes may be comma-separated in one clause.
- Avoid numeric probe IDs.
Script Skeleton
#!/usr/sbin/dtrace -s
dtrace:::BEGIN
{
printf("Tracing started...\n");
}
/* tracing clauses */
dtrace:::END
{
/* printa() for aggregations when needed */
}
dtrace:::ERROR
{
printf("DTrace error at %s:%s:%s:%s\n", probeprov, probemod, probefunc, probename);
}
Preferred Idioms
- Filter early with predicates:
/execname == "date"/
/pid == $target/
- Use per-thread state for timing:
self->ts = timestamp;
/self->ts/ { @lat = quantize(timestamp - self->ts); self->ts = 0; }
- Use aggregations instead of unbounded prints:
@counts[key] = count();
@sum[key] = sum(value);
@dist = quantize(value);
Variables
- Global:
x, arr[key] (shared, not MP-safe by default)
- Thread-local:
self->x (preferred for correlation)
- Clause-local:
this->x (temporary per-probe firing)
- Built-in probe/process vars:
pid, ppid, tid, execname
probeprov, probemod, probefunc, probename
timestamp, vtimestamp, errno
arg0 ... arg9, args[]
- Macro vars:
$target, $pid, $uid, $1, $2, ...
Common Functions
- Recording:
trace(), printf(), printa(), exit()
- Aggregation:
count(), sum(), avg(), min(), max(), stddev(), quantize(), lquantize(), llquantize()
- Memory/string:
copyin(), copyinstr(), strlen(), substr(), strstr()
- Stacks:
stack(), ustack()
- Speculation:
speculation(), speculate(), commit(), discard()
Provider Quick Reference
dtrace: lifecycle (BEGIN, END, ERROR)
syscall: syscall entry/return
proc: process lifecycle (exec, exit, ...)
sched: scheduler activity (on-cpu, off-cpu, ...)
profile: timed sampling (profile-N, tick-N)
io: I/O start/complete
pid: user-function boundaries in a target process
usdt: user static tracepoints
Patterns
Count syscalls by executable:
#!/usr/sbin/dtrace -s
syscall:::entry
/execname != ""/
{
@syscalls[execname] = count();
}
dtrace:::END
{
printa(@syscalls);
}
Time syscall latency:
#!/usr/sbin/dtrace -s
syscall::write:entry
{
self->ts = timestamp;
}
syscall::write:return
/self->ts/
{
@lat[execname] = quantize(timestamp - self->ts);
self->ts = 0;
}
Target one process:
#!/usr/sbin/dtrace -s
syscall:::entry
/pid == $target/
{
@calls[probefunc] = count();
}
Response Style
- Be precise and production-minded.
- Prefer compact scripts with clear predicates.
- Add brief comments only where they prevent ambiguity.
- After presenting a script, include one short run command when useful:
Verification Workflow
Always verify generated scripts before presenting them as final.
- Write the script to a file, for example
script.d.
- Run compile-only verification:
sudo dtrace -e -s script.d
- If compile-only is unavailable on the target distro, use a short bounded run:
sudo timeout 3 dtrace -s script.d
- Treat verification failures as blocking:
- Fix the script and re-run verification until it passes.
- Report verification status with the output:
Verified: yes plus the command used.
1---2name: dtrace-linux3description: Generate and validate runnable DTrace scripts for Linux debugging and performance investigations in an agentic coding framework capable of using SKILLs. Use for incident response, root-cause analysis, latency triage, syscall/process/scheduler/I-O tracing, and stack/profile sampling. Always return complete scripts with safe defaults, stable providers, strict D language constraints, and a verification step before final output.4metadata:5 source: https://skillmd.com/skills/oracle/dtrace-linux6---78# DTrace for Linux910Generate complete D scripts that compile and run cleanly on Linux systems with DTrace.1112## Output Requirements1314- Return a full runnable D program every time.15- Include a shebang for script output: `#!/usr/sbin/dtrace -s`.16- Prefer predicates for filtering and aggregations for volume control.17- Include `dtrace:::ERROR` when the script could fault or when robust diagnostics are useful.18- Avoid placeholders, pseudo-code, and partial solutions.1920## Safety Rules2122- Prefer stable providers: `syscall`, `proc`, `sched`, `profile`, `io`, `pid`, `usdt`, and `dtrace`.23- Avoid dangerous actions unless explicitly necessary.24- Do not recommend `system()` unless there is no viable alternative.25- Treat `copyout*()`, `raise()`, and `system()` as destructive.2627## Forbidden Language Constructs2829Never use these constructs in D scripts:3031- `if`32- `else`33- `for`34- `while`35- `switch`36- `case`37- `default`38- `do`39- `goto`40- `continue`4142Use only:4344- Predicates: `/expr/`45- Ternary operator: `cond ? a : b`4647## Clause Structure4849Use this canonical form:5051```d52probe-descriptions53/ optional predicate /54{55 statements;56}57```5859- Probe description format: `provider:module:function:name`60- Omitted fields are wildcard matches.61- Multiple probes may be comma-separated in one clause.62- Avoid numeric probe IDs.6364## Script Skeleton6566```d67#!/usr/sbin/dtrace -s6869dtrace:::BEGIN70{71 printf("Tracing started...\n");72}7374/* tracing clauses */7576dtrace:::END77{78 /* printa() for aggregations when needed */79}8081dtrace:::ERROR82{83 printf("DTrace error at %s:%s:%s:%s\n", probeprov, probemod, probefunc, probename);84}85```8687## Preferred Idioms8889- Filter early with predicates:90 - `/execname == "date"/`91 - `/pid == $target/`92- Use per-thread state for timing:93 - `self->ts = timestamp;`94 - `/self->ts/ { @lat = quantize(timestamp - self->ts); self->ts = 0; }`95- Use aggregations instead of unbounded prints:96 - `@counts[key] = count();`97 - `@sum[key] = sum(value);`98 - `@dist = quantize(value);`99100## Variables101102- Global: `x`, `arr[key]` (shared, not MP-safe by default)103- Thread-local: `self->x` (preferred for correlation)104- Clause-local: `this->x` (temporary per-probe firing)105- Built-in probe/process vars:106 - `pid`, `ppid`, `tid`, `execname`107 - `probeprov`, `probemod`, `probefunc`, `probename`108 - `timestamp`, `vtimestamp`, `errno`109 - `arg0` ... `arg9`, `args[]`110- Macro vars:111 - `$target`, `$pid`, `$uid`, `$1`, `$2`, ...112113## Common Functions114115- Recording: `trace()`, `printf()`, `printa()`, `exit()`116- Aggregation: `count()`, `sum()`, `avg()`, `min()`, `max()`, `stddev()`, `quantize()`, `lquantize()`, `llquantize()`117- Memory/string: `copyin()`, `copyinstr()`, `strlen()`, `substr()`, `strstr()`118- Stacks: `stack()`, `ustack()`119- Speculation: `speculation()`, `speculate()`, `commit()`, `discard()`120121## Provider Quick Reference122123- `dtrace`: lifecycle (`BEGIN`, `END`, `ERROR`)124- `syscall`: syscall entry/return125- `proc`: process lifecycle (`exec`, `exit`, ...)126- `sched`: scheduler activity (`on-cpu`, `off-cpu`, ...)127- `profile`: timed sampling (`profile-N`, `tick-N`)128- `io`: I/O start/complete129- `pid`: user-function boundaries in a target process130- `usdt`: user static tracepoints131132## Patterns133134Count syscalls by executable:135136```d137#!/usr/sbin/dtrace -s138139syscall:::entry140/execname != ""/141{142 @syscalls[execname] = count();143}144145dtrace:::END146{147 printa(@syscalls);148}149```150151Time syscall latency:152153```d154#!/usr/sbin/dtrace -s155156syscall::write:entry157{158 self->ts = timestamp;159}160161syscall::write:return162/self->ts/163{164 @lat[execname] = quantize(timestamp - self->ts);165 self->ts = 0;166}167```168169Target one process:170171```d172#!/usr/sbin/dtrace -s173174syscall:::entry175/pid == $target/176{177 @calls[probefunc] = count();178}179```180181## Response Style182183- Be precise and production-minded.184- Prefer compact scripts with clear predicates.185- Add brief comments only where they prevent ambiguity.186- After presenting a script, include one short run command when useful:187 - `sudo dtrace -s script.d`188189## Verification Workflow190191Always verify generated scripts before presenting them as final.1921931. Write the script to a file, for example `script.d`.1942. Run compile-only verification:195 - `sudo dtrace -e -s script.d`1963. If compile-only is unavailable on the target distro, use a short bounded run:197 - `sudo timeout 3 dtrace -s script.d`1984. Treat verification failures as blocking:199 - Fix the script and re-run verification until it passes.2005. Report verification status with the output:201 - `Verified: yes` plus the command used.