Add glossary and improve text

mozilla-services · Oct 12, 2023 · 0f09219 · 0f09219
1 parent 83f7545
commit 0f09219
Show file tree

Hide file tree

Showing 8 changed files with 130 additions and 30 deletions.
diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -8,8 +8,6 @@ Configuration
 Symbols Service configuration
 =============================
 
-The Symbols Service covers uploading and downloading symbols.
-
 Gunicorn configuration:
 
 .. everett:option:: GUNICORN_TIMEOUT

diff --git a/docs/download.rst b/docs/download.rst
@@ -10,10 +10,10 @@ Download
 Basics
 ======
 
-The Tecken webapp handles requests for symbols files. Tecken takes the request,
-figures out which bucket the file is in, and returns a redirect to that bucket.
-This allows us to use multiple buckets for symbols without requiring everyone
-to maintain lists of buckets.
+The Tecken webapp handles requests for :term:`symbols files <symbols file>`.
+Tecken takes the request, figures out which bucket the file is in, and returns
+a redirect to that bucket. This allows us to use multiple buckets for symbols
+without requiring everyone to maintain lists of buckets.
 
 For example, at the time of this writing doing a ``GET`` for
 :base_url:`/firefox.pdb/448794C699914DB8A8F9B9F88B98D7412/firefox.sym` will

diff --git a/docs/frontend.rst b/docs/frontend.rst
@@ -5,15 +5,16 @@ Frontend Documentation
 Overview
 ========
 
-The Symbols Service webapp has a JavaScript React frontend. The frontend code
-tries to be as separate from the web server code as possible.  The frontend is
-a static app (written in React with ``react-router``) that communicates with
-the web server by making AJAX calls for JSON/REST and rendering in run-time.
+Tecken has a JavaScript React frontend. The frontend code tries to be as
+separate from the web server code as possible. The frontend is a static app
+(written in React with ``react-router``) that communicates with the web server
+by making AJAX calls for JSON/REST and rendering in run-time.
 
 The goal is for the web server (i.e. Django) to only return pure responses in
 JSON (or plain text or specific to some files) and never generate HTML
 templates.
 
+
 The Code
 ========
 

diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -0,0 +1,104 @@
+========
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   dump_syms
+       dump_syms is a tool for parsing the debugging information the compiler
+       provides (whether as DWARF or STABS sections in an ELF file or as
+       stand-alone PDB files) and writing that information back out in the
+       Breakpad symbol file format.
+
+       .. seealso::
+
+          `dump_syms <https://github.com/mozilla/dump_syms>`__
+              dump_syms project.
+
+
+   symbols
+   symbols file
+       When compiling a build, the compiler generates binaries with debugging
+       symbols in them.
+
+       The build system uses :term:`dump_syms` to extract the debugging symbols
+       from the binaries and put them in Breakpad-style symbol files.
+
+       An entry in the symbol file is something like "This set of bytes in this
+       binary correspond to function JammyJamJam on line 200 in source file
+       jampocalypso.c."
+
+       Let's create a symbol file.
+
+       We can create a new Rust project, build it, then extract symbols from
+       it using :term:`dump_syms`::
+
+           $ cargo new testproj
+           $ cd testproj
+           $ cargo build
+           $ dump_syms target/debug/testproj > testproj.sym
+
+       That creates a sym file like this::
+
+           MODULE Linux x86_64 D48F191186D67E69DF025AD71FB91E1F0 testproj
+           ...
+           FILE 5 /home/willkg/projects/testproj/src/main.rs
+           ...
+           FUNC 5380 44 0 testproj::main
+           5380 9 1 5
+           5389 36 2 5
+           53bf 5 3 5
+
+       This sym file is 6,809 lines for a "Hello, world!" binary.
+
+       .. seealso::
+
+          `Breakpad symbol format <https://chromium.googlesource.com/breakpad/breakpad/+/HEAD/docs/symbol_files.md>`__
+              Specification for Breakpad symbol file format.
+
+
+   symbolication
+       Symbolication is the act of converting an array of addresses and module
+       information into symbols of the function in the source code for that
+       address.
+
+       Here's an array of modules loaded in memory and a stack defined as an
+       array of memory offsets::
+
+           {"jobs": [{
+             "memoryMap": [
+               [ "firefox.pdb", "5F84ACF1D63667F44C4C44205044422E1" ],
+               [ "mozavcodec.pdb", "9A8AF7836EE6141F4C4C44205044422E1" ],
+               [ "Windows.Media.pdb", "01B7C51B62E95FD9C8CD73A45B4446C71" ],
+               [ "xul.pdb", "09F9D7ECF31F60E34C4C44205044422E1" ],
+               // ...
+             ],
+             "stacks": [[
+               [ 3, 6516407 ],
+               [ 3, 12856365 ],
+               [ 3, 12899916 ],
+               [ 3, 13034426 ],
+               [ 3, 13581214 ],
+               [ 3, 13646510 ],
+               // ...
+             ]]
+           }]}
+
+       We can use the sym files, look up the memory addresses, and find the
+       symbols for them. That gets us this::
+
+           0  xul.pdb  mozilla::ConsoleReportCollector::FlushReportsToConsole(unsigned long long, nsIConsoleReportCollector::ReportAction)
+           1  xul.pdb  mozilla::net::HttpBaseChannel::MaybeFlushConsoleReports()",
+           2  xul.pdb  mozilla::net::HttpChannelChild::OnStopRequest(nsresult const&, mozilla::net::ResourceTimingStructArgs const&, mozilla::net::nsHttpHeaderArray const&, nsTArray<mozilla::net::ConsoleReportCollected> const&)
+           3  xul.pdb  std::_Func_impl_no_alloc<`lambda at /builds/worker/checkouts/gecko/netwerk/protocol/http/HttpChannelChild.cpp:1001:11',void>::_Do_call()
+          ...
+
+       That's symbolication.
+
+       .. seealso::
+
+          `Mozilla Symbolication Server <https://symbolication.services.mozilla.com/>`__
+
+          `Eliot <https://mozilla-eliot.readthedocs.io/>`__
+              Documentation for the Mozilla Symbolication Server.
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,6 +8,7 @@
    overview
    upload
    download
+   glossary
 
 .. toctree::
    :caption: Developers/Admin of Tecken

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -9,8 +9,9 @@ Overview
 What is Tecken?
 ===============
 
-Tecken is the Mozilla Symbols Server which manages symbols generated by builds of Mozilla
-products (:ref:`upload <upload>`, :ref:`download <download>`).
+Tecken is the Mozilla Symbols Server which manages
+:term:`symbols files <symbols file>` generated by builds of Mozilla products
+(:ref:`upload <upload>`, :ref:`download <download>`).
 
 
 Architecture
@@ -36,11 +37,6 @@ The symbols webapp handles upload and download of symbols.
   symbol file in one of the AWS S3 buckets and returning an HTTP redirect
   to the final location.
 
-.. Warning::
-
-   The Symbols Service also has a symbolication API. This version of the
-   symbolication API is deprecated. Please switch to using the Symbolication
-   service at `<https://symbolication.services.mozilla.com/>`__ instead.
 
 Code is in the `tecken
 <https://github.com/mozilla-services/tecken/tree/main/tecken>`_ subdirectory.
@@ -55,7 +51,7 @@ Here's a bunch of top-level directories and what's in them::
     docker/                 -- Dockerfile and image building bits
     docs/                   -- documentation
     favicons/               -- favicons used by Symbols webapp
-    frontend/               -- Symbols webapp JS frontend
+    frontend/               -- Symbols webapp JavaScript frontend
     schemas/                -- API schemas
     tecken/                 -- Symbols service unit tests and code
 
@@ -67,8 +63,9 @@ These directories have test stuff in them::
 .. Note::
 
    Originally, there was just Tecken which handled upload, download, and
-   symbolication. Then we split symbolication into a separate service named
-   `Mozilla Symbolication Service <https://symbolication.services.mozilla.com/>`__.
+   :term:`symbolication`. Then we split symbolication into a separate service
+   named `Mozilla Symbolication Server
+   <https://symbolication.services.mozilla.com/>`__.
 
 
 The Logo

diff --git a/docs/redis.rst b/docs/redis.rst
@@ -5,8 +5,8 @@ Redis Documentation
 Usage
 =====
 
-The Symbols Service webapp uses Redis for miscellaneous caching and as a broker
-for message queue workers (TO BE UPDATED).
+Tecken uses Redis for miscellaneous caching and as a broker for message queue
+workers (TO BE UPDATED).
 
 
 Usage In Django

diff --git a/docs/upload.rst b/docs/upload.rst
@@ -13,22 +13,21 @@ Uploading symbols
 Basics
 ======
 
-Tecken lets you upload symbol files. It stores these symbol files allowing
-others to use the download API to access them for symbolicating stacks,
-profiling, debugging, etc.
+Tecken lets you upload :term:`symbols files <symbols file>`. It stores these
+symbols files allowing others to use the download API to access them for
+symbolicating stacks, profiling, debugging, etc.
 
-When building software, you can run `dump_syms
-<https://github.com/mozilla/dump_syms/>`_ to extract debugging information and
-generate Breakpad symbol files.
+When building software, you can run :term:`dump_syms` to extract debugging
+information and generate symbols files.
 
 You can upload your symbols ZIP file to Tecken using the upload API.
 
 
 Symbols ZIP file structure
 --------------------------
 
-To upload symbol files, you must first put them in a ZIP file. The ZIP file
-must consist of Breakpad symbol files in this structure::
+To upload symbols files, you must first put them in a ZIP file. The ZIP file
+must consist of symbols files in this structure::
 
     <module>/<debug_id>/<file>