Issues with documentation

Issues with documentation

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 3540 bytes --]

Hi!

I've started going through the DTrace tutorial on docs.oracle.com [0]
and found a few errors which derailed me.

Hopefully this is the right place to report that so the docs can
be updated.

Testing was done with dtrace at commit c84954cdc6fb017034e2c3fe4445a7c8981d35e9
and linux-6.6.46.

# 2 Tracing Operating System Behavior 

* Tracing Process Creation
** Example: Monitoring the System as Programs Are Executed (execcalls.d)
	```
	$ dtrace -n 'proc::do_execveat_common:exec { trace(stringof(args[0])); }'
	dtrace: invalid probe specifier proc::do_execveat_common:exec { trace(stringof(args[0])); }: probe description proc::do_execveat_common:exec does not match any probes
	```

	Workaround I used: proc:::exec works.

* Tracing System Calls
** Example: Recording open() System Calls on a System (syscalls.d)
	```
	$ dtrace -n 'syscall::open:entry { printf("%-16s %-16s\n",execname,copyinstr(arg0)); }'
	dtrace: description 'syscall::open:entry ' matched 1 probe
	[no output]
	```

	I think the reason here is that it's pretty rare for anything to actually
	use `open` directly.

	Workaround I used: wildcard with: 'syscall::openat*:entry { printf("%s %s\n", execname, copyinstr(arg1)); }'

** Exercise: Using the printf() Function to Format Output
	Nit: there's inconsistent spaces between the function arguments.

** Exercise: Using tick Probes
	In 'Example: Modified Version of tick.d', the listed function names
	don't have 'ms' appended, but the example solution to the exercise does.

	The docs should explain the inconsistency and why it's OK (or fix it).

* Tracing Parent and Child Processes
** Example: Using proc Probes to Report Activity on a System (activity.d) 
	```
	$ dtrace -s activity.d
	dtrace: failed to compile script activity.d: line 5: probe description proc::_do_fork:create does not match any probes
	```

	See cad6967ac10843a70842cd39c7b53412901dd21f in linux.git, _do_fork
	was renamed.

** Example: Recording fork() and exec() Activity for a Specified Program (activity1.d)
	This example is broken in a few ways:
	1) because of the fork issue mentioned above;
	2) the command snippet afterwards says 'activity.d', not 'activity1.d'
	(tries to pass arg to activity.d which doesn't accept any, unlike
	the just-created activity1.d);
	3) same proc::do_execveat_common:exec issue as earlier too.

** Exercise: Tracing Processes That Are Run by a User
	```
	$ ./countprogs.d $(id -u sam)
	dtrace: failed to compile script ./countprogs.d: line 5: probe description proc::do_execveat_common:exec does not match any probes
	```

** Example: Counting the Number of Times a Program Reads From Different Files in 10 Seconds (fdscount.d) 
	I think the program (fdscount.d) is missing?

** Example: Displaying System Call Errors (errno.d) 
	This didn't seem to work for me (no output) after doing e.g. ls /idonotexist,
	cat blahblah.

# 3 Tracing User-Space Applications 

* Using USDT Probes
	This didn't seem to work for me (no probes found).

	I stopped testing here for now.

[0] https://docs.oracle.com/en/operating-systems/oracle-linux/dtrace-tutorial/dtrace-tutorial-Preface.html#pref

I've not repeated the same issues if e.g. a probe is gone/renamed/missing
so other instances will need to be checked if I already named it.

I'd like to add that the doc website is pretty nice to navigate and the content
is well-written. While I normally prefer PDFs, I didn't even end up using the
download option.

thanks,
sam

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 377 bytes --]