Architecture Decision Records¶

The intention is to document deviations from a standard Model View Controller (MVC) design.

Troubleshooting's Design and Code Intent¶

Troubleshooting in Action¶

Troubleshooting was written to capture errors and include them in the output instead of failing or stalling. As a diagnostic tool, it does its best to run each check as designed and return the output rather than surfacing stack traces. Please keep this methodology. The goal is to collect as much data as possible in a single run.

Troubleshooting Checks¶

Checks are written as a combination of Python code and YAML-formatted data. The check.yaml file handles argument passing, and entry_point.py is written so that a dictionary can be passed by importing the check.yaml file with parameters around how check.py will be run. This allows run_check.py to pass a check dictionary to entry_point.py without needing to know the details.

Each check is a standardized file with properties for enabling or disabling by default. This allows checks to be rolled out incrementally or toggled off by a Nautobot admin. Checks also have parameters, some of which may be immutable, to structure the arguments a user can pass into Troubleshooting.

First Set of Checks¶

Utilize the subprocess module for running commands against a host.
Entry point is a wrapper for the subprocess module.
Focus on human-readable responses. A JSON output option is always included.
Support output into a zip file.

Subsequent Checks¶

Should follow the same development guidelines as the first set of checks.
Each check should have a check.yaml file with an entry point into a check.py file.

Scripts in Troubleshooting¶

run_check.py — handles running checks as actions.
helpers.py — common/generic functionality relied upon by Troubleshooting.
update_readme.py — updates the readme in the troubleshooting_checks folder to keep check information current.

Troubleshooting Input¶

Troubleshooting can be run in the following ways:

All enabled checks — searches for all troubleshooting_checks/*.yaml files and runs checks with enabled: true. Outputs a zip file with results stored as YAML files.
```
nautobot_troubleshooting
```

Single check — runs a specific check by name.

nautobot_troubleshooting --check_name date

Troubleshooting Output¶

Via a temp directory with a zip file output (default).
Via output to the screen.

Examples¶

# YAML output structure

check_name:
    command: check_name command being run
    command_result: capture and return result of running command
    command_result_status: enum options of `Success`, `Failure`, `Error`
    command_result_type: best estimate for string, json, or raw text in `command_result`
    command_result_error: capture and return any errors when running the command through the entry_point
    entry_point_error: capture and return any errors when running the entry_point script

{
    "check_name": {
        "command": "date",
        "command_result": "Mon Oct 9 02:04:26 UTC 2023",
        "command_result_status": "success",
        "command_result_type": "string",
        "command_result_error": "None",
        "entry_point_error": "None"
    }
}