Diff for /wikisrc/tutorials/how_to_enable_and_run_dtrace.mdwn between versions 1.12 and 1.28

version 1.12, 2014/09/18 19:46:11 version 1.28, 2020/03/30 15:40:27
Line 1 Line 1
 DTrace is a Dynamic Tracing framework developed by Sun and ported to NetBSD. It enables extensive instrumentation of the kernel and user space. See the [DTrace Community Page](http://dtrace.org) for more information. Also see [DTrace Introduction](http://dtrace.org/guide/preface.html).   DTrace is a Dynamic Tracing framework developed by Sun and ported to NetBSD. It enables extensive instrumentation of the kernel and user space. See the [DTrace Community Page](http://dtrace.org) for more information.
   Also see [DTrace Introduction](http://dtrace.org/guide/preface.html), Brendan Gregg's [DTrace one liners](http://www.brendangregg.com/DTrace/dtrace_oneliners.txt) and his notes for [DTrace on FreeBSD](https://wiki.freebsd.org/DTrace/).
   
 # Current status  # Current status
   
Line 7  DTrace is a Dynamic Tracing framework de Line 8  DTrace is a Dynamic Tracing framework de
 DTrace is a work-in-progress effort and it is for x86 systems and some arm boards.  DTrace is a work-in-progress effort and it is for x86 systems and some arm boards.
   
 * i386 and amd64  * i386 and amd64
 * evbarm  * earm* (evbarm and armv4 based ports)
     * BEAGLEBONE and SHEEVAPLUG  
   
 ## Supported providers  ## Supported providers
   
 * SDT: Statically Defined Tracing  * DTrace: What to do when a script BEGINs, ENDs, ERRORs
 * FBT: Function Boundary Tracing  * FBT: Function Boundary Tracing
   * IO: Disk I/O
 You can currently run a hello world DScript.   * Lockstat: Kernel Lock Statistics
   * Proc: Process and thread related events
   * Profile: Time based interrupt event source for Profiling
   * SDT: Statically Defined Tracing
   * Syscall: System Calls
   * Syscall Linux (32bit & 64 bit): System calls via the Linux binary emulation layer
   * VFS: Filesystem operations (confined to namecache events at time of writing - 8.99.22)
   
 ## TODO for netbsd-7  ## TODO for netbsd-7
   
Line 23  You can currently run a hello world DScr Line 29  You can currently run a hello world DScr
 * Determine whether the profile module works and list it here.  * Determine whether the profile module works and list it here.
 * Integrate [[riz|users/riz]]'s syscall provider patch.  * Integrate [[riz|users/riz]]'s syscall provider patch.
   
 ## TODO for netbsd-6  
   
 Need to identify changes to pull up to netbsd-6 and pull them up.  
 Candidates:  
   
 * Profile provider.  
   
 # How to use  # How to use
   
 ##  Building DTrace   ##  Building DTrace 
   
 You need the following options in your kernel:   You need the following options in your kernel: 
           
     options         INSECURE  
     options         KDTRACE_HOOKS   # kernel DTrace hooks      options         KDTRACE_HOOKS   # kernel DTrace hooks
     options         MODULAR      options         MODULAR
       
   
 You also need to build distribution with the options MKDTRACE=yes.  Optionally:
   
 ##  Running hello world       options         INSECURE   # permit modules to loaded from user space once system has gone multiuser and securelevel has been raised.
   
 Load the solaris and dtrace modules, and the SDT (Statically Defined Tracing) and FBT (Function Boundary Tracing) modules:   A Distribution needs to be built with the options `MKDTRACE=yes` and `MKCTF=yes`, this is taken care of automatically and doesn't need to be specified manually. The list of platforms it is applied to automatically is set in `src/share/mk/bsd.own.mk`
       
     modload solaris  Set the system to load the solaris and dtrace related modules in `/etc/modules.conf`, for a list of available modules, see `/stand/$MACHINE/$VERSION/modules/`
     modload dtrace  
     modload dtrace_sdt  
     modload dtrace_fbt  
       
   
 Make the dtrace device node:   For example, add the following to `/etc/modules.conf` (the file may not exist already on a system):
           
     cd /dev  - `solaris`
     sh MAKEDEV dtrace  - `dtrace`
   - `dtrace_fbt`
   - `dtrace_lockstat`
   - `dtrace_profile`
   - `dtrace_sdt`
   - `dtrace_syscall`
   - `dtrace_syscall_linux`
       
   A `dtrace` device node is created automatically in `/dev/dtrace` when the modules are loaded into place.
           
   
 List the dtrace probes   List the dtrace probes 
           
     dtrace -l      dtrace -l
Line 81  List the dtrace probes  Line 81  List the dtrace probes 
         .          .
     29140       proc                                                     lwp_start      29140       proc                                                     lwp_start
     29141       proc                                                     lwp_exit      29141       proc                                                     lwp_exit
       
   
     
   
   ## Running hello world 
   
 Put the following into the file hello.d:  Put the following into the file hello.d:
           
Line 102  Run the hello world script:  Line 101  Run the hello world script: 
     dtrace: script './hello.d' matched 1 probe      dtrace: script './hello.d' matched 1 probe
     CPU     ID                    FUNCTION:NAME      CPU     ID                    FUNCTION:NAME
       0      1                           :BEGIN   Hello world        0      1                           :BEGIN   Hello world
       
   
 A more complex example that traces the execution of a sleep operation  The same script could be executed as a one liner on the shell, using
   
       dtrace -n 'BEGIN { trace("Hello world"); exit(0); }'
   
   ## A more complex example
   
   The following script traces the execution of a sleep operation
 in the kernel. Put it in sleep.d:  in the kernel. Put it in sleep.d:
           
     #pragma D option flowindent      #pragma D option flowindent
       
     fbt::syscall:entry      syscall::nanosleep:entry
     /execname == "sleep" && guard++ == 0/      /execname == "sleep" && guard++ == 0/
     {      {
             self->traceme = 1;              self->traceme = 1;
             printf("fd: %d", arg0);  
     }      }
       
     fbt::syscall:entry /self->traceme/ {}      fbt:::
           /self->traceme/
     fbt::syscall:return      {}
   
       syscall::nanosleep:return
     /self->traceme/      /self->traceme/
     {      {
             self->traceme = 0;              self->traceme = 0;
             exit(0);              exit(0);
     }      }
       
   
 Start the script running (dtrace -s sleep.d) and then execute a "sleep 2" in another shell.   Start the script running:
   
       dtrace -s sleep.d
   
   This will take a while as the script instruments every function in the
   kernel. When it's ready, it will print a message like "dtrace: script
   'sleep.d' matched 59268 probes".  Then execute a "sleep 2" in another
   shell.
   
   ## Tools included in base
   
   Starting with NetBSD-8, on builds where `MKDTRACE=yes` is set, scripts from
   [Brendan Gregg's DTrace toolkit](https://github.com/opendtrace/toolkit/) are installed in base as standard.
   
   At present, the following scripts are installed in `/usr/sbin`: 
   
   - `dtruss` - An implementation of the truss utility in DTrace which traces the system calls
   made by a process
   - `execsnoop` - snoop on execution of processes as they occur
   - `opensnoop` - snoop on openning of files as they occur
   - `procsystime` -  print process system call time details.
   
   ## Troubleshooting
   
   The Compact C Type Format (CTF) has a 2^15 limit on types which can overflow, this prevents DTrace from
   working correctly.
   
   Check the number of types using `ctfdump` e.g
       ctfdump -S /netbsd
   
   Note the line which states `total number of types`, the value should by less than 32768.
   
   If overflow is not an issue, `libdtrace(3)` can provide some insight into what is going on via an
   environment variable. Define `DTRACE_DEBUG` before tracing.
   
        env DTRACE_DEBUG= execsnoop
   

Removed from v.1.12  
changed lines
  Added in v.1.28


CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb