diff --git a/doc/sphinx/toc/libweston.rst b/doc/sphinx/toc/libweston.rst
index cd56e0d10..b7e5b4c34 100644
--- a/doc/sphinx/toc/libweston.rst
+++ b/doc/sphinx/toc/libweston.rst
@@ -10,6 +10,7 @@ Libweston
    libweston/shell-utils.rst
    libweston/output-management.rst
    libweston/log.rst
+   libweston/debug-flight-recorder.rst
 
 `Libweston` is an effort to separate the re-usable parts of Weston into a
 library. `Libweston` provides most of the boring and tedious bits of correctly
diff --git a/doc/sphinx/toc/libweston/debug-flight-recorder.rst b/doc/sphinx/toc/libweston/debug-flight-recorder.rst
new file mode 100644
index 000000000..6724e11e7
--- /dev/null
+++ b/doc/sphinx/toc/libweston/debug-flight-recorder.rst
@@ -0,0 +1,51 @@
+.. _debugging flight recorder:
+
+
+Debugging with Flight Recorder
+==============================
+
+Weston can write debug scopes data to a circular ring buffer. This ring
+buffer can be accessed through a debug key, assuming you have a keyboard
+attached, or in case Weston dies, through a coredump. This document describes
+how to access that data in the later case.
+
+The ring buffer data can be accessed with a gdb python script that searches
+the coredump file for the that ring buffer address in order to retrieve
+data from it.
+
+Prior to setting this up make sure that flight recorder is configured
+accordingly.  Make sure that Weston is started with the debug scopes that
+you're interested into. For instance if you'd like to get the :samp:`drm-backend` one
+Weston should show when starting up:
+
+::
+
+        Flight recorder: enabled, scopes subscribed: drm-backend
+
+For that Weston needs to be started with :samp:`--debug -f drm-backend`.
+
+Also, make sure that the system is configured to generate a core dump.  Refer
+to :samp:`man core(5)` for how to do that.
+
+Next you'll need the `gdb python
+script <https://gitlab.freedesktop.org/wayland/weston/-/blob/main/doc/scripts/gdb/flight_rec.py>`_,
+as that will be needed to search for the ring buffer within the coredump.
+
+Finally, to make this easier and push everything from the ring buffer to a
+file, we would need to create a batch gdb file script to invoke the commands
+for us.
+
+As an example name that file :file:`test.gdb` and add the following to entries
+to it, making sure to adjust the path for the python script.
+
+::
+
+        source /path/to/flight_rec.py
+        display_flight_rec
+
+Then run the following commands to dump the contents of the ring buffer
+straight to a file:
+
+::
+
+        $ gdb --batch --command=/path/to/test.gdb -q /path/to/test/weston/binary --core /path/to/coredump &> dump.log.txt
diff --git a/doc/sphinx/toc/libweston/log.rst b/doc/sphinx/toc/libweston/log.rst
index 63bf1c644..989b9a6bb 100644
--- a/doc/sphinx/toc/libweston/log.rst
+++ b/doc/sphinx/toc/libweston/log.rst
@@ -141,8 +141,9 @@ force the contents to be printed on :samp:`stdout` file-descriptor.
 The user has first to specify which log scope to subscribe to.
 
 Specifying which scopes to subscribe for the flight-recorder can be done using
-:samp:`--flight-rec-scopes`. By default, the 'log' scope and 'drm-backend' are
-the scopes subscribed to.
+:samp:`-f|--flight-rec-scopes`. By default, only the 'log' scope is subscribed
+to. See :ref:`debugging flight recorder` on how retrieve the contents of the
+flight recorder in case Weston dies/crashes unexpectedly.
 
 weston-debug protocol
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx/toc/libweston/meson.build b/doc/sphinx/toc/libweston/meson.build
index f72ca5f26..1a912d8dd 100644
--- a/doc/sphinx/toc/libweston/meson.build
+++ b/doc/sphinx/toc/libweston/meson.build
@@ -2,6 +2,7 @@
 files = [
 	'compositor.rst',
 	'head.rst',
+        'debug-flight-recorder.rst',
 	'log.rst',
 	'output.rst',
 	'output-management.rst',