File:  [NetBSD Developer Wiki] / wikisrc / tutorials / how_to_enable_and_run_dtrace.mdwn
Revision 1.14: download - view: text, annotated - select for diffs
Wed Mar 22 15:33:08 2017 UTC (3 years, 8 months ago) by sevan
Branches: MAIN
CVS tags: HEAD
List earm* rather than specific boards in evbarm port.
Add more providers to the list.
Note the INSECURE option is not mandatory and explain why it might be desired.
MKDTRACE & MKCTF build options are handled automatically now, direct reader to where that's controlled if the list needs to be extended.
Direct reader to use modules.conf and how they can find which modules are available on their system.
Replace instructions for creating a device node manually with a note that it is created automatically
Remove whitespace.

    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). 
    2: 
    3: # Current status
    4: 
    5: ## Supported platforms
    6: 
    7: DTrace is a work-in-progress effort and it is for x86 systems and some arm boards.
    8: 
    9: * i386 and amd64
   10: * earm* (evbarm and armv4 based ports (armv4 side requires further testing but system is built with CTF)
   11: 
   12: ## Supported providers
   13: 
   14: * SDT: Statically Defined Tracing
   15: * FBT: Function Boundary Tracing
   16: * Lockstat: Kernel Lock Statistics
   17: * Profile: Time based interrupt event source for Profiling
   18: * Syscall: System Calls
   19: * Syscall Linux (32bit & 64 bit): System calls via the Linux binary emulation layer
   20: 
   21: ## TODO for netbsd-7
   22: 
   23: * Measure effect of `options KDTRACE_HOOKS` on system performance.
   24: * Determine whether the profile module works and list it here.
   25: * Integrate [[riz|users/riz]]'s syscall provider patch.
   26: 
   27: ## TODO for netbsd-6
   28: 
   29: Need to identify changes to pull up to netbsd-6 and pull them up.
   30: Candidates:
   31: 
   32: * Profile provider.
   33: 
   34: # How to use
   35: 
   36: ##  Building DTrace 
   37: 
   38: You need the following options in your kernel: 
   39:     
   40:     options         KDTRACE_HOOKS   # kernel DTrace hooks
   41:     options         MODULAR
   42: 
   43: Optionally:
   44:     options         INSECURE   # permit modules to loaded from user space once system has gone multiuser and securelevel has been raised.
   45: 
   46: 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`
   47: 
   48: 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/`
   49:     
   50:     solaris
   51:     dtrace
   52:     dtrace_sdt
   53:     dtrace_fbt
   54:     dtrace_lockstat
   55:     dtrace_profile
   56:     dtrace_syscall
   57:     
   58: A `dtrace` device node is created automatically in `/dev/dtrace` when the modules are loaded into place.
   59:     
   60: List the dtrace probes 
   61:     
   62:     dtrace -l
   63:     
   64:        ID   PROVIDER            MODULE                          FUNCTION NAME
   65:         1     dtrace                                                     BEGIN
   66:         2     dtrace                                                     END
   67:         3     dtrace                                                     ERROR
   68:         4        fbt            netbsd             AcpiAcquireGlobalLock entry
   69:         5        fbt            netbsd             AcpiAcquireGlobalLock return
   70:         6        fbt            netbsd             AcpiAllocateRootTable entry
   71:         7        fbt            netbsd                    AcpiAttachData entry
   72:         . 
   73:         .
   74:     29129        fbt           solaris                   zfs_vop_getattr entry 
   75:     29130        fbt           solaris                   zfs_vop_getattr return
   76:     29131       proc                                                     create
   77:     29132       proc                                                     exec 
   78:         .
   79:         .
   80:     29140       proc                                                     lwp_start
   81:     29141       proc                                                     lwp_exit
   82: 
   83: 
   84: ##  Running hello world 
   85: 
   86: Put the following into the file hello.d:
   87:     
   88:     BEGIN
   89:     {
   90:         trace("Hello world");
   91:         exit(0);
   92:     }
   93:     
   94: 
   95: Run the hello world script: 
   96:     
   97:     dtrace -s hello.d
   98:     
   99:     dtrace: script './hello.d' matched 1 probe
  100:     CPU     ID                    FUNCTION:NAME
  101:       0      1                           :BEGIN   Hello world
  102:     
  103: 
  104: A more complex example that traces the execution of a sleep operation
  105: in the kernel. Put it in sleep.d:
  106:     
  107:     #pragma D option flowindent
  108:     
  109:     fbt::syscall:entry
  110:     /execname == "sleep" && guard++ == 0/
  111:     {
  112:             self->traceme = 1;
  113:             printf("fd: %d", arg0);
  114:     }
  115:     
  116:     fbt::syscall:entry /self->traceme/ {}
  117:     
  118:     fbt::syscall:return
  119:     /self->traceme/
  120:     {
  121:             self->traceme = 0;
  122:             exit(0);
  123:     }
  124:     
  125: 
  126: Start the script running (dtrace -s sleep.d) and then execute a "sleep 2" in another shell. 

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