flightgear/docs-mini/README.logging

Logging in FlightGear
---------------------

[Note: JSBSim also has its own independent logging facilities, which
are not discussed here.]

FlightGear can log any property values at any interval to one or more
CSV files (which can be read and graphed using spreadsheets like
Gnumeric or Excel).  Logging is defined in the '/logging' subbranch of
the main property tree; under '/logging', each '/log' subbranch
defines a separate log with its own output file and interval.  Here is
a simple example that logs the rudder and aileron settings every
second (1000ms) to the file steering.csv, using a comma (the default,
anyway) as the field delimiter:

 <logging>
  <log>
   <filename>steering.csv</filename>
   <interval-ms>1000</interval-ms>
   <delimiter>,</delimiter>
   <entry>
    <title>Rudder</title>
    <property>/controls/rudder</property>
   </entry>
   <entry>
    <title>Ailerons</title>
    <property>/controls/aileron</property>
   </entry>
  </log>
 </logging>

Each 'log' subbranch contains an optional 'filename' property
(defaults to "fg_log.csv"), an optional 'delimiter' property (defaults
to a comma), an optional 'interval-ms' property (defaults to 0, which
logs every frame), and a series of 'entry' subbranches.  The
'delimiter' property uses only the first character of the property
value as the delimiter.  Note that the logger does no escaping, so you
must choose a delimiter that will not appear in the property values
(that's not hard, since most of the values are numeric, but watch for
commas in the titles).

Each 'entry' subbranch contains a 'property' property specifying the
name of the property to be logged, and an optional 'title' property
specifying the title to use in the CSV file (defaults to the full path
of the property).  The elapsed time in milliseconds since the start of
the simulation is always included as the first entry with the title
"Time", so there is no need to include it explicitly.

Here's a sample of the logging output for the above log:

  Time,Rudder,Ailerons
  6522,0.000000,0.000000
  7668,-0.000000,0.000000
  8702,-0.000000,0.000000
  9705,-0.000000,0.000000
  10784,-0.000000,0.000000
  11792,-0.000000,0.000000
  12808,-0.000000,-0.210000
  13826,-0.000000,-0.344000
  14881,-0.000000,-0.066000
  15901,-0.000000,-0.806000
  16943,-0.000000,-0.936000
  17965,-0.000000,-0.534000
  19013,-0.000000,-0.294000
  20044,-0.000000,0.270000
  21090,-0.000000,-1.000000
  22097,-0.000000,-0.168000

Note that the requested interval is only a minimum; most of the time,
the actual interval is slightly longer than the requested one.

The easiest way for an end-user to define logs is to put the log in a
separate XML file (usually under the user's home directory), then
refer to it using the --config option, like this:

  fgfs --config=log-config.xml

The output log files are always relative to the current directory.

--

David Megginson, 2002-03-12