Reports
=====================

Running Reports
-----------------

The toolkit has both CLI options and a Web interface.

Web Interface
^^^^^^^^^^^^^^^

To use the Web interface, navigate to the following URL in your web browser:

    https://my_domino/toolkit

This will bring up the Web interface, where you can perform various tasks using the toolkit.

You will be asked to login, you can get the credentials by doing one of the following steps (both require you to have kubernetes access):

1. Use the toolkit.sh

.. code-block:: bash

   ./toolkit.sh get-password

2. Run the following kubectl command

.. code-block:: bash

   # on macOS, it may be necessary to use base64 -D instead of -d
   kubectl get secret -n {platform namespace} domino-admin-toolkit-http -ojsonpath='{.data.admin-password}' | base64 -d; echo



From here you can click the run report button to run a fresh report:

.. image:: ../files/run_test.png
   :alt: Toolkit Web Interface
   :width: 600px


CLI
^^^^^

To use the CLI, follow these steps:

Pre Requisites: 

1. You will first need to download the toolkit.sh by running the following:

.. code-block:: bash

   curl -LsSO https://toolkit.re.domino.tech/toolkit.sh && chmod a+x ./toolkit.sh
   ./toolkit.sh

2. Access to the kubernetes cluster

Once you have this you can run any of the following commands


.. code-block:: yaml

   ./toolkit.sh help
   
   toolkit.sh version: master, n/a
   
   Usage: toolkit.sh [command] [options]
   
   Commands:
     install [options]  Install and start the admin toolkit
     uninstall          Uninstall the admin toolkit, deleting all resources
     start              Starts the admin toolkit if it is stopped
     stop               Stops the admin toolkit if it is running
     status             Shows whether admin toolkit is installed and running
     test    [options]  Run tests with given options and upload html report to S3
     pytest  [options]  Run pytest directly, see https://docs.pytest.org/en/7.1.x/how-to/usage.html
     exec    [command]  Execute a command in the toolkit container (by default /bin/bash), useful for debugging
     logs               Show toolkit container logs
     version            Show toolkit container version
     get-password       Retrieve the admin toolkit UI username and password
     help               Get this help message
   
   `install` command options:
     ./toolkit.sh install --tag|-t tag              Run specific docker image tag of the admin toolkit
     ./toolkit.sh install --daemonset               Enable daemonset functionality
     ./toolkit.sh install --daemonset-port|-d port  Set the host port the daemonset listens on. Default is port 5000.
     ./toolkit.sh install --no-ingress              Disable ingress route to toolkit pod.


   `test` command options:
     ./toolkit.sh test --help                  Show help including choice of parameters
     ./toolkit.sh test --exclude               Exclude tests for specific features
     ./toolkit.sh test --log-cli-level DEBUG   Show extra debugging output
     ./toolkit.sh test --local-only            Copy HTML file to host and do not send the report output to Domino's S3


Reading Reports
---------------------

Accessing the Reports
^^^^^^^^^^^^^^^^^^^^^^^^^
After running a report, it will be available under the "Actions" column. By clicking on the "view" icon, you'll be navigated to the detailed report page.

.. image:: ../files/report.png
   :alt: Toolkit Web Interface
   :width: 600px

Report Overview
^^^^^^^^^^^^^^^^^^^^
The report provides critical insights about your Domino deployment, including:

- The version of your Domino deployment.
- Kubernetes versions underpinning your deployment.
- Version and date of the toolkit's last build.

Additionally, the interface allows you to toggle between different types of checks, specifically: general, info, and pre-upgrade.

Understanding Report Results
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Passed
"""""""
**Description:** 
   The test successfully fulfilled its condition.

**Note:** 
   All "Info" checks will automatically pass. They're designed to gather potentially useful diagnostic information rather than determine success or failure.

Skipped
""""""""
**Description:** 
   The test was not applicable for various reasons.

**Note:** 
   Click on these to get more information. Typically, they're skipped because your deployment lacks the necessary type, setting, or version the check is designed for.

Failed
""""""
**Description:** 
   The test did not meet its condition.

**Note:** 
   A failed check doesn't directly indicate an ongoing issue. However, it helps identify the state of your deployment, be it during an issue or when Domino is healthy.

Error
"""""
**Description:** 
   There was a problem with the test itself.

**Note:** 
   A large number of errors might indicate a broader platform issue. If isolated, they can be ignored or reported as a toolkit issue.


Diagnostic Approach
^^^^^^^^^^^^^^^^^^^^^^^^^
The toolkit report doesn't always directly indicate the root cause of an issue. Instead, it aids in diagnosing potential problems. Proper debugging and engineering intelligence should be applied during investigations.

**Example**: Suppose a user reports that workspaces aren't starting. On checking the report:

.. image:: ../files/failed_check.png
   :alt: Failed Check Example
   :width: 600px

If a failed check indicates container restarts, but none of the affected containers are linked to workspace operations, then this check, although relevant for other platform concerns, is not pertinent to the current user issue.