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 You need to do two things:
  36
  37         * patch the VM code with the provided vmlog_<vm>.patch
  38         * configure the VM with CFLAGS that include -Ivmlogdir
  39           where vmlogdir is the directory the contains the vmlog
  40           source code
  41
  42 You can then compile your VM with vmlog.
  43
  44
  45 Using vmlog
  46 -----------
  47
  48 To use it call the VM with at least the following option added to the command
  49 line:
  50
  51         -vmlog:prefix PREFIX
  52
  53 PREFIX is an arbitrary string that will be used as a prefix for the generated
  54 file names.
  55
  56 Note: For cacao you currently also have to add `-verbose:call` to activate
  57 the logging.
  58
  59
  60 Ignore Lists
  61 ------------
  62
  63 If you want vmlog to ignore certain methods do the following:
  64
  65         * put the full names of the methods (as displayed by vmlog)
  66           into a file, say "vmloginore.txt".
  67
  68         * type
  69
  70                 vmlogindex vmloginore vmloginore.txt
  71
  72         * add the following option to your VM command line:
  73
  74                 -vmlog:ignore vmloginore
  75
  76
  77 The Tools
  78 ---------
  79
  80 After running something with your prepared VM, you will find the following
  81 files:
  82
  83     PREFIX.idx          string index
  84         PREFIX.str          string data
  85         PREFIX.#.log        log for thread number #
  86
  87 Some things you can do now:
  88
  89         * Count called methods:
  90
  91                 vmlogdump PREFIX -c
  92
  93         * Show open call frames at the end of the log:
  94
  95                 vmlogdump PREFIX -o
  96
  97         * Dump all strings in the hash:
  98
  99                 vmlogdump PREFIX -s
 100
 101         * Print an indented call trace:
 102
 103                 vmlogdump PREFIX
 104
 105
 106 Comparing logs
 107 --------------
 108
 109 An important feature of vmlog is that you can compare the logs created by
 110 different VMs. To do this first do a normal vmlog run with the first VM.
 111 Then start the second VM with theese options:
 112
 113         -vmlog:prefix OTHERPREFIX -vmlog:strings PREFIX
 114
 115 where PREFIX is the PREFIX you used for the first VM run and OTHERPREFIX
 116 is a different string.
 117
 118 You can now compare the logs (for example of the first thread):
 119
 120         vmlogdiff OTHERPREFIX PREFIX.0.log OTHERPREFIX.0.log
 121
 122 Note: vmlogdiff is currently not fast enough, yet. You can add the
 123 `-v` option to it to see what it is doing (on stderr) at least.
 124
 125