From a5d33f95ba68263e6c0ca758c5b854530332d9ae Mon Sep 17 00:00:00 2001 From: jwijenbergh Date: Tue, 26 Apr 2022 11:44:11 +0200 Subject: Docs: Add more info about debugging (logging and FSM) --- docs/src/gettingstarted/debugging/README.md | 6 +++++ docs/src/gettingstarted/debugging/fsm.md | 30 ++++++++++++++++++++++ docs/src/gettingstarted/debugging/fsm_example.png | Bin 0 -> 331875 bytes docs/src/gettingstarted/debugging/logging.md | 8 ++++++ 4 files changed, 44 insertions(+) create mode 100644 docs/src/gettingstarted/debugging/README.md create mode 100644 docs/src/gettingstarted/debugging/fsm.md create mode 100644 docs/src/gettingstarted/debugging/fsm_example.png create mode 100644 docs/src/gettingstarted/debugging/logging.md (limited to 'docs/src/gettingstarted/debugging') diff --git a/docs/src/gettingstarted/debugging/README.md b/docs/src/gettingstarted/debugging/README.md new file mode 100644 index 0000000..e3a1ecd --- /dev/null +++ b/docs/src/gettingstarted/debugging/README.md @@ -0,0 +1,6 @@ +# Debugging + +To debug this library, e.g. to discover bugs or to see how it works internally, the library comes with a few nice additions. + +## The debug variable +To enable debugging, set debugging to True in the method that registers the code with the library (see [API](../api/index.html)). This sets the logging level to `INFO` (meaning show all messages), and generates a Finite State Machine (FSM) PNG file. We explain in more detail what these two components (logging and FSM) exactly are and how they can be used. diff --git a/docs/src/gettingstarted/debugging/fsm.md b/docs/src/gettingstarted/debugging/fsm.md new file mode 100644 index 0000000..891b0ea --- /dev/null +++ b/docs/src/gettingstarted/debugging/fsm.md @@ -0,0 +1,30 @@ +# Finite State Machine + +The eduvpn-common library uses a Finite State Machine internally to keep track of which state the client is in and to communicate data callbacks(e.g. to communicate the Authorization URL in the OAuth process to the client). + +## Viewing the FSM +To view the FSM in an image, set the debug variable to `True`. This outputs the graph with a `.graph` extension in the client-specified config directory (See [API](../../api/index.html)). The format of this graph is from [Mermaid](https://mermaid-js.github.io/mermaid/#/). + +If you have the [Mermaid command line client](https://github.com/mermaid-js/mermaid-cli) installed, the Go library will automatically provide a PNG file in the same directory of the `.graph` file. We recommend to use an image viewer that has auto-reload capabilities, such as [feh](https://feh.finalrewind.org/)[^1] for Linux. + +## FSM Example +The following is an example of the FSM when the client has obtained a Wireguard/OpenVPN configuration from an eduVPN server + +![](./fsm_example.png) + +The current state is highlighted in the cyan color. + +## State explanation +The states mean the following: + +- `DEREGISTERED`: The client has not registered with the library yet, the state variables are not initialized +- `NO_SERVER`: The client is registered, but has not chosen a server yet +- `CHOSEN_SERVER`: The client has chosen a server to connect to +- `OAuth_Started`: The OAuth process has been started. This means that the client needs to redirect to the browser so that the user can login and approve the application +- `Authenticated`: The OAuth process has finished. The client now has tokens and is thus authenticated +- `Request_Config`: The client is in the process of requesting an OpenVPN/Wireguard configuration from the server +- `Ask_Profile`: The server has multiple profiles for which a config can be obtained, the client must show an UI of the profiles. The user then selects one of these profiles to exit this state +- `Has_Config`: The client now has a configuration that it can use to connect using OpenVPN/Wireguard +- `Connected`: The client is connected to the VPN + +[^1]: We recommend the following arguments for feh: `feh --auto-reload --keep-zoom-vp directory/example.png`. This auto reloads the feh image viewer and keeps the zoom level when reloading diff --git a/docs/src/gettingstarted/debugging/fsm_example.png b/docs/src/gettingstarted/debugging/fsm_example.png new file mode 100644 index 0000000..c495124 Binary files /dev/null and b/docs/src/gettingstarted/debugging/fsm_example.png differ diff --git a/docs/src/gettingstarted/debugging/logging.md b/docs/src/gettingstarted/debugging/logging.md new file mode 100644 index 0000000..a1cfc97 --- /dev/null +++ b/docs/src/gettingstarted/debugging/logging.md @@ -0,0 +1,8 @@ +# Logging +As said, logging is used. The logging gets saved in a client-specified directory (see [API](../../api/index.html)). Logging has the following levels: + +- `INFO`: Messages purely for info, these do not indicate any errors. They are merely there for debugging purposes +- `WARNING`: This message indicates a warning, this can be e.g. non-fatal errors +- `ERROR`: Fatal errors which refuses the app from working + +By default only messages below or equal to `WARNING` are logged (`WARNING`, `ERROR`). However, if the debug variable is set to `True`, all messages will be logged into the log file. -- cgit v1.2.3