docs-mini/README.logging

   1 Logging in FlightGear
   2 ---------------------
   3
   4 [Note: JSBSim also has its own independent logging facilities, which
   5 are not discussed here.]
   6
   7 FlightGear can log any property values at any interval to one or more
   8 CSV files (which can be read and graphed using spreadsheets like
   9 Gnumeric or Excel).  Logging is defined in the '/logging' subbranch of
  10 the main property tree; under '/logging', each '/log' subbranch
  11 defines a separate log with its own output file and interval.  Here is
  12 a simple example that logs the rudder and aileron settings every
  13 second (1000ms) to the file steering.csv, using a comma (the default,
  14 anyway) as the field delimiter:
  15
  16  <logging>
  17   <log>
  18    <filename>steering.csv</filename>
  19    <interval-ms>1000</interval-ms>
  20    <delimiter>,</delimiter>
  21    <entry>
  22     <title>Rudder</title>
  23     <property>/controls/rudder</property>
  24    </entry>
  25    <entry>
  26     <title>Ailerons</title>
  27     <property>/controls/aileron</property>
  28    </entry>
  29   </log>
  30  </logging>
  31
  32 Each 'log' subbranch contains an optional 'filename' property
  33 (defaults to "fg_log.csv"), an optional 'delimiter' property (defaults
  34 to a comma), an optional 'interval-ms' property (defaults to 0, which
  35 logs every frame), and a series of 'entry' subbranches.  The
  36 'delimiter' property uses only the first character of the property
  37 value as the delimiter.  Note that the logger does no escaping, so you
  38 must choose a delimiter that will not appear in the property values
  39 (that's not hard, since most of the values are numeric, but watch for
  40 commas in the titles).
  41
  42 Each 'entry' subbranch contains a 'property' property specifying the
  43 name of the property to be logged, and an optional 'title' property
  44 specifying the title to use in the CSV file (defaults to the full path
  45 of the property).  The elapsed time in milliseconds since the start of
  46 the simulation is always included as the first entry with the title
  47 "Time", so there is no need to include it explicitly.
  48
  49 Here's a sample of the logging output for the above log:
  50
  51   Time,Rudder,Ailerons
  52   6522,0.000000,0.000000
  53   7668,-0.000000,0.000000
  54   8702,-0.000000,0.000000
  55   9705,-0.000000,0.000000
  56   10784,-0.000000,0.000000
  57   11792,-0.000000,0.000000
  58   12808,-0.000000,-0.210000
  59   13826,-0.000000,-0.344000
  60   14881,-0.000000,-0.066000
  61   15901,-0.000000,-0.806000
  62   16943,-0.000000,-0.936000
  63   17965,-0.000000,-0.534000
  64   19013,-0.000000,-0.294000
  65   20044,-0.000000,0.270000
  66   21090,-0.000000,-1.000000
  67   22097,-0.000000,-0.168000
  68
  69 Note that the requested interval is only a minimum; most of the time,
  70 the actual interval is slightly longer than the requested one.
  71
  72 The easiest way for an end-user to define logs is to put the log in a
  73 separate XML file (usually under the user's home directory), then
  74 refer to it using the --config option, like this:
  75
  76   fgfs --config=log-config.xml
  77
  78 The output log files are always relative to the current directory.
  79
  80 --
  81
  82 David Megginson, 2002-03-12