contrib/vmlog/README

   1 vmlog - high-speed logging for free VMs
   2 Copyright (c) 2006 Edwin Steiner <edwin.steiner@gmx.net>
   3 -----------------------------------------------------------------------
   4
   5 About
   6 -----
   7
   8 vmlog is a software module for doing fast call logging in free Java VMs and a
   9 set of tools for examining the created logfiles.
  10
  11 Some features of vmlog:
  12
  13         * high data density because of binary formats with hashed strings
  14         * high speed (ie. you can run big applications with full logging)
  15         * small, non-intrusive interface to several VMs
  16         * clean separation of threads
  17         * can ignore a user-specified list of methods
  18
  19 Right now there are complete interfaces for the following VMs:
  20
  21         * CACAO
  22         * jamvm 1.4.2
  23
  24
  25 License
  26 -------
  27
  28 vmlog is free software distributed under the GPL. See the file COPYING
  29 for details.
  30
  31
  32 How to compile a VM with vmlog
  33 ------------------------------
  34
  35 CACAO has vmlog support built-in. Use the configure flag --enable-vmlog
  36 to build it.
  37
  38 For other VMs, you need to do two things:
  39
  40         * patch the VM code with the provided vmlog_<vm>.patch
  41         * configure the VM with CFLAGS that include -Ivmlogdir
  42           where vmlogdir is the directory the contains the vmlog
  43           source code
  44
  45 You can then compile your VM with vmlog.
  46
  47
  48 Using vmlog
  49 -----------
  50
  51 To use it call the VM with at least the following option added to the command
  52 line:
  53
  54         -vmlog:prefix PREFIX
  55
  56 PREFIX is an arbitrary string that will be used as a prefix for the generated
  57 file names.
  58
  59 Note: For cacao you currently also have to add `-verbose:call` to activate
  60 the logging.
  61
  62
  63 Ignore Lists
  64 ------------
  65
  66 If you want vmlog to ignore certain methods do the following:
  67
  68         * put the full names of the methods (as displayed by vmlog)
  69           into a file, say "vmloginore.txt".
  70
  71         * type
  72
  73                 vmlogindex vmloginore vmloginore.txt
  74
  75         * add the following option to your VM command line:
  76
  77                 -vmlog:ignore vmloginore
  78
  79
  80 The Tools
  81 ---------
  82
  83 After running something with your prepared VM, you will find the following
  84 files:
  85
  86     PREFIX.idx          string index
  87         PREFIX.str          string data
  88         PREFIX.#.log        log for thread number #
  89
  90 Some things you can do now:
  91
  92         * Count called methods:
  93
  94                 vmlogdump PREFIX -c
  95
  96         * Show open call frames at the end of the log:
  97
  98                 vmlogdump PREFIX -o
  99
 100         * Dump all strings in the hash:
 101
 102                 vmlogdump PREFIX -s
 103
 104         * Print an indented call trace:
 105
 106                 vmlogdump PREFIX
 107
 108
 109 Comparing logs
 110 --------------
 111
 112 An important feature of vmlog is that you can compare the logs created by
 113 different VMs. To do this first do a normal vmlog run with the first VM.
 114 Then start the second VM with theese options:
 115
 116         -vmlog:prefix OTHERPREFIX -vmlog:strings PREFIX
 117
 118 where PREFIX is the PREFIX you used for the first VM run and OTHERPREFIX
 119 is a different string.
 120
 121 You can now compare the logs (for example of the first thread):
 122
 123         vmlogdiff OTHERPREFIX PREFIX.0.log OTHERPREFIX.0.log
 124
 125 Note: vmlogdiff is currently not fast enough, yet. You can add the
 126 `-v` option to it to see what it is doing (on stderr) at least.
 127
 128