= Sentry.io Cash Reporting =

FlightGear can optionally report crashes and serious errors to Sentry.io. We have a sponsored
account provided gratis by Sentry; for access to this, ask on the developer list.

== Error conditions ==

If FlightGear crahses, SDentry will automatically submit a report. For non-crash errors,
we manually submit an exception report. At present this is done whenever we trigger the
'fatalMessageBox', and in other serious situations. Deciding where is appropriate (or not)
to report the error to Sentry is a key challenge of the system, since we don't want to
report user misconfiguration problems, but we do want to detect recurring and
systematic failures, eg broken aircraft.

In general since we have (almost) unlimited event limits on our sponsored plan, it's 
better to send errors and filter them on the server side, but this needs to be done 
with some intelligence; for example we do not (at present) report Nasal runtime
errors, since this might overload the system.

== Data Protection ==

We explicitly don't include any personal information in the reports, and disable IP address
collection. Since this makes it hard to cluster reports by user, we instead generate a UUID
corresponding to a FlightGear installation. This gives us a way to anonymously cluster reports
by user, without any personal data disclosure.

== Supplementatal Data ==

We record various pieces of configuration state as 'tags': such as the OS, graphics card,
key settings (eg, is multi-player enabled, which aircraft is being flown) as _tags_ in
Sentry terminology. This allows grouping of reports by similar tags; for example we can
identify that a particular crash only occurs with Intel Graphics, or when flying the
C172.

Additionally we record 'breadcrumbs'; these are included with an error report if one
is sent, and give an idea of the path of the user through the application, prior to the
crash. We have breadcrumbs for key events such as the splash-screen completing, the
user changing position, or scenery being reloaded.

WARN and ALERT level `SG_LOG` messages are currently included as breadcrumbs automatically;
this means it's important not casually add messages at the levels for non-serious conditions.
The integration code has a list of commonly ocurring but non-useful messages which are
skipped from sending; especially some OSG ones related to minor PNG and AC3D data issues.

Adding new tags or breadcrumbs should be done with care, but is generally useful, and
suggestions in this area are appreciated.

== API ==

All the API is contained in `sentryIntegration.hxx`, inside the `flightgear` namespace. 
The methods are no-ops if the Sentry SDK was not available at CMake time, and are also
no-ops if the user has disabled sentry reporting.