Merge pull request #76 from nautobot/jlw-update-docs-standards

update docs to current standards
nautobot · Nov 30, 2023 · 1b93fa1 · 1b93fa1
2 parents db7ace2 + c148b67
commit 1b93fa1
Show file tree

Hide file tree

Showing 10 changed files with 316 additions and 375 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/admin/install.md b/docs/admin/install.md
@@ -37,9 +37,33 @@ Once installed, the plugin needs to be enabled in your Nautobot configuration. T
 PLUGINS = ["nautobot_capacity_metrics"]
 
 # PLUGINS_CONFIG = {
-#   "nautobot_capacity_metrics": {
-#     ADD YOUR SETTINGS HERE
-#   }
+#     "nautobot_capacity_metrics": {
+#         "app_metrics": {
+#             "gitrepositories": True,
+#             "jobs": True,
+#             "models": {
+#                 "dcim": {
+#                     "Site": True,
+#                     "Rack": True,
+#                     "Device": True,
+#                     "Interface": True,
+#                     "Cable": True,
+#                 },
+#                 "ipam": {
+#                     "IPAddress": True,
+#                     "Prefix": True,
+#                 },
+#                 "extras": {
+#                     "GitRepository": True
+#                 },
+#             },
+#             "queues": True,
+#             "versions": {
+#                 "basic": True,
+#                 "plugins": True,
+#             }
+#         }
+#     },
 # }
 ```
 
@@ -61,11 +85,15 @@ sudo systemctl restart nautobot nautobot-worker nautobot-scheduler
 
 ## App Configuration
 
-!!! warning "Developer Note - Remove Me!"
-    Any configuration required to get the App set up. Edit the table below as per the examples provided.
-
 The plugin behavior can be controlled with the following list of settings:
 
 | Key     | Example | Default | Description                          |
 | ------- | ------ | -------- | ------------------------------------- |
 | `app_metrics` | `{"models": {"dcim": "Device": True}}` | `{"models": {"dcim": {"Site": True, "Rack": True, "Device": True}, "ipam": {"IPAddress": True, "Prefix": True}}, "jobs": True, "queues": True, "versions": {"basic": False, "plugins": False}` | Specifies which metrics to publish for each app. |
+
+
+## Included Grafana Dashboard
+
+Included within this plugin is a Grafana dashboard which will work with the example configuration above. To install this dashboard import the JSON from [Grafana Dashboard](https://raw.githubusercontent.com/nautobot/nautobot-plugin-capacity-metrics/develop/docs/nautobot_grafana_dashboard.json) into Grafana.
+
+![Nautobot Grafana Dashboard](https://raw.githubusercontent.com/nautobot/nautobot-plugin-capacity-metrics/develop/docs/images/nautobot_grafana_dashboard.png)
diff --git a/docs/admin/uninstall.md b/docs/admin/uninstall.md
@@ -0,0 +1,16 @@
+
+# Uninstall the App from Nautobot
+
+Here you will find any steps necessary to cleanly remove the App from your Nautobot environment.
+
+## Database Cleanup
+
+Prior to removing the plugin from the `nautobot_config.py`, run the following command to roll back any migration specific to this plugin.
+
+```shell
+nautobot-server migrate nautobot_plugin_capacity_metrics zero
+```
+
+## Remove App configuration
+
+Remove the configuration you added in `nautobot_config.py` from `PLUGINS` & `PLUGINS_CONFIG`.
diff --git a/docs/images/icon-nautobot-capacity-metrics.svg b/docs/images/icon-nautobot-capacity-metrics.svg
diff --git a/docs/user/app_overview.md b/docs/user/app_overview.md
@@ -0,0 +1,19 @@
+# App Overview
+
+This document provides an overview of the App including critical information and import considerations when applying it to your Nautobot environment.
+
+!!! note
+    Throughout this documentation, the terms "app" and "plugin" will be used interchangeably.
+
+## Description
+
+An app for Nautobot that is meant to provide the ability to expose additional metrics for your Nautobot deployment along with the ability to build custom metrics.
+
+## Audience (User Personas) - Who should use this App?
+
+Capacity Metrics is targeted for Nautobot application admins to provide additional insight into their Nautobot deployment.
+
+## Authors and Maintainers
+
+- David Flores @davidban77
+
diff --git a/docs/user/app_use_cases.md b/docs/user/app_use_cases.md
@@ -0,0 +1,139 @@
+# Using the App
+
+This document describes common use-cases and scenarios for this App.
+
+## General Usage
+
+Configure your Prometheus server to collect the application metrics at `/api/plugins/capacity-metrics/app-metrics/`
+
+```yaml
+# Sample prometheus configuration
+scrape_configs:
+  - job_name: 'nautobot_app'
+    scrape_interval: 120s
+    metrics_path: /api/plugins/capacity-metrics/app-metrics
+    static_configs:
+      - targets: ['nautobot']
+```
+
+### Queue System Metrics Endpoint
+
+In addition to the default Nautobot system metrics which are exposed at `/metrics` which are largely centered around the Django system on which Nautobot is based this plugin provides some additional system metrics around the queuing system Nautobot uses to communicate with the Nautobot worker services.
+
+## Use-cases and common workflows
+
+### Add your own metrics
+
+This plugin supports some options to generate and publish your own application metrics behind the same endpoint.
+
+#### Option 1 - Register function(s) via nautobot_config.py
+
+It's possible to create your own function to generate some metrics and register it to the plugin in the nautobot_config.py.
+Here is an example where the custom function are centralized in a `metrics.py` file, located next to the main `nautobot_config.py`.
+
+```python
+# metrics.py
+from prometheus_client.core import GaugeMetricFamily
+
+def metric_prefix_utilization():
+    """Report prefix utilization as a metric per container."""
+    from ipam.models import Prefix  # pylint: disable=import-outside-toplevel
+
+    containers = Prefix.objects.filter(status="container").all()
+    g = GaugeMetricFamily(
+        "nautobot_prefix_utilization", "percentage of utilization per container prefix", labels=["prefix", "role", "site"]
+    )
+
+    for container in containers:
+
+        site = "none"
+        role = "none"
+        if container.role:
+            role = container.role.slug
+
+        if container.site:
+            site = container.site.slug
+
+        g.add_metric(
+            [str(container.prefix), site, role], container.get_utilization(),
+        )
+
+    yield g
+```
+
+The new function can be imported in the `nautobot_config.py` file and registered with the plugin.
+
+```python
+# nautobot_config.py
+from nautobot.metrics import metric_prefix_utilization
+PLUGINS_CONFIG = {
+    "nautobot_capacity_metrics": {
+      "app_metrics": {
+        "extras": [
+          metric_prefix_utilization
+        ]
+      }
+    }
+},
+```
+
+#### Option 2 - Registry for third party plugins
+
+Any plugin can include its own metrics to improve the visibility and/or the troubleshooting of the plugin itself.
+Third party plugins can register their own function(s) using the `ready()` function as part of their `PluginConfig` class.
+
+```python
+# my_plugin/__init__.py
+from nautobot_capacity_metrics import register_metric_func
+from nautobot.metrics import metric_circuit_bandwidth
+
+class MyPluginConfig(PluginConfig):
+    name = "nautobot_myplugin"
+    verbose_name = "Demo Plugin"
+    # [ ... ]
+    def ready(self):
+        super().ready()
+        register_metric_func(metric_circuit_bandwidth)
+```
+
+#### Option 3 - NOT AVAILABLE YET - Metrics directory
+
+In the future it will be possible to add metrics by adding them in a predefined directory, similar to jobs.
+
+## Plugin Configuration Parameters
+
+The behavior of the app_metrics feature can be controlled with the following list of settings (under `nautobot_capacity_metrics > app_metrics`):
+- `gitrepositories` boolean (default **False**), publish stats about the gitrepositories (success, warning, info, failure)
+- `jobs` boolean (default **False**), publish stats about the jobs (success, warning, info, failure)
+- `queues` boolean (default **False**), publish stats about Worker (nbr of worker, nbr and type of job in the different queues)
+- `models` nested dict, publish the count for a given object (Nbr Device, Nbr IP etc.. ). The first level must be the name of the module in lowercase (dcim, ipam etc..), the second level must be the name of the object (usually starting with a uppercase). Note that you can include models from plugins by specifying the module name under the "_module" key
+- `versions` nested dict, publish the versions of installed software
+
+    ```python
+    PLUGINS_CONFIG = {
+      "nautobot_capacity_metrics": {
+        "app_metrics": {
+          "models": {
+             "dcim": {"Site": True, "Rack": True, "Device": True},
+             "ipam": {"IPAddress": True, "Prefix": True},
+           },
+           "jobs": True,
+           "queues": True,
+           "versions": {
+             "basic": True,
+             "plugins": True,
+           }
+         }
+       }
+    }
+    ```
+
+## Screenshots
+
+![Metrics](https://raw.githubusercontent.com/nautobot/nautobot-plugin-capacity-metrics/develop/docs/images/capacity-metrics-screenshot-01.png "Metrics")
+
+![Device Per Status](https://raw.githubusercontent.com/nautobot/nautobot-plugin-capacity-metrics/develop/docs/images/capacity-metrics-screenshot-02.png "Device Per Status")
+
+![Rack Capacity](https://raw.githubusercontent.com/nautobot/nautobot-plugin-capacity-metrics/develop/docs/images/capacity-metrics-screenshot-03.png "Rack Capacity")
+
+![Prefix Capacity](https://raw.githubusercontent.com/nautobot/nautobot-plugin-capacity-metrics/develop/docs/images/capacity-metrics-screenshot-04.png "Prefix Capacity")
diff --git a/docs/user/external_interactions.md b/docs/user/external_interactions.md
@@ -0,0 +1,57 @@
+# External Interactions
+
+This document describes external dependencies and prerequisites for this App to operate, including system requirements, API endpoints, interconnection or integrations to other applications or services, and similar topics.
+
+## External System Integrations
+
+### Default Metrics for the application metrics endpoint
+
+The following metrics will be provided via the `/api/plugins/capacity-metrics/app-metrics` endpoint:
+
+```no-highlight
+# HELP nautobot_gitrepository_task_stats Per Git repository task statistics
+# TYPE nautobot_gitrepository_task_stats gauge
+nautobot_gitrepository_task_stats{module="repo1",name="main",status="success"} 1.0
+nautobot_gitrepository_task_stats{module="repo1",name="main",status="warning"} 0.0
+nautobot_gitrepository_task_stats{module="repo1",name="main",status="failure"} 0.0
+nautobot_gitrepository_task_stats{module="repo1",name="main",status="info"} 6.0
+nautobot_gitrepository_task_stats{module="repo1",name="total",status="success"} 1.0
+nautobot_gitrepository_task_stats{module="repo1",name="total",status="warning"} 0.0
+nautobot_gitrepository_task_stats{module="repo1",name="total",status="failure"} 0.0
+nautobot_gitrepository_task_stats{module="repo1",name="total",status="info"} 6.0
+# HELP nautobot_gitrepository_execution_status Git repository completion status
+# TYPE nautobot_gitrepository_execution_status gauge
+nautobot_gitrepository_execution_status{module="repo1",status="pending"} 0.0
+nautobot_gitrepository_execution_status{module="repo1",status="running"} 0.0
+nautobot_gitrepository_execution_status{module="repo1",status="completed"} 1.0
+nautobot_gitrepository_execution_status{module="repo1",status="errored"} 0.0
+nautobot_gitrepository_execution_status{module="repo1",status="failed"} 0.0
+# HELP nautobot_job_task_stats Per Job task statistics
+# TYPE nautobot_job_task_stats gauge
+nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="success"} 1.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="warning"} 0.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="failure"} 0.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="info"} 0.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="success"} 1.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="warning"} 0.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="failure"} 0.0
+nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="info"} 0.0
+# HELP nautobot_job_execution_status Job completion status
+# TYPE nautobot_job_execution_status gauge
+nautobot_job_execution_status{module="local/users/CheckUser",status="pending"} 0.0
+nautobot_job_execution_status{module="local/users/CheckUser",status="running"} 0.0
+nautobot_job_execution_status{module="local/users/CheckUser",status="completed"} 1.0
+nautobot_job_execution_status{module="local/users/CheckUser",status="errored"} 0.0
+nautobot_job_execution_status{module="local/users/CheckUser",status="failed"} 0.0
+# HELP nautobot_model_count Per Nautobot Model count
+# TYPE nautobot_model_count gauge
+nautobot_model_count{app="dcim",name="Site"} 24.0
+nautobot_model_count{app="dcim",name="Rack"} 24.0
+nautobot_model_count{app="dcim",name="Device"} 46.0
+nautobot_model_count{app="ipam",name="IPAddress"} 58.0
+nautobot_model_count{app="ipam",name="Prefix"} 18.0
+nautobot_model_count{app="extras",name="GitRepository"} 1.0
+# HELP nautobot_app_metrics_processing_ms Time in ms to generate the app metrics endpoint
+# TYPE nautobot_app_metrics_processing_ms gauge
+nautobot_app_metrics_processing_ms 59.48257
+```
diff --git a/docs/user/faq.md b/docs/user/faq.md
@@ -1,19 +1,20 @@
 # Frequently Asked Questions
 
-## Nautobot already expose a metrics endpoint, why do I need another one ?
+## Nautobot already exposes a metrics endpoint, why do I need another one?
 
-> System metrics and application level metrics are complementary with each other
-> - **SYSTEM Metrics** are very useful to instrument code, track ephemeral information and get a better visibility into what is happening. (Example of metrics: nbr of requests, requests per second, nbr of exceptions, response time, etc ...) The idea is that if we have multiple Nautobot instances running behind a load balancer each one will produce a different set of metrics and the monitoring system needs to collect these metrics from all running instances and aggregate them in a dashboard. Nautobot exposes some system metrics by default at `localhost/metrics`.
-> - **APPLICATION Metrics** are at a higher level and represent information that is the same across all instances of an application running behind a load balancer. if I have 3 instances of Nautobot running, there is no point to ask each of them how many Device objects I have in the database, since they will always return the same information. In this case, the goal is to expose only 1 endpoint that can be served by any running instance.
+System metrics and application level metrics are complementary with each other:
 
-## Do I need an API token to access the application metrics endpoint ? 
+- **SYSTEM Metrics** are very useful to instrument code, track ephemeral information and get a better visibility into what is happening. (Example of metrics: nbr of requests, requests per second, nbr of exceptions, response time, etc ...) The idea is that if we have multiple Nautobot instances running behind a load balancer each one will produce a different set of metrics and the monitoring system needs to collect these metrics from all running instances and aggregate them in a dashboard. Nautobot exposes some system metrics by default at `localhost/metrics`.
+- **APPLICATION Metrics** are at a higher level and represent information that is the same across all instances of an application running behind a load balancer. if I have 3 instances of Nautobot running, there is no point to ask each of them how many Device objects I have in the database, since they will always return the same information. In this case, the goal is to expose only 1 endpoint that can be served by any running instance.
 
-> No, currently no authentication is required (or possible).
+## Do I need an API token to access the application metrics endpoint? 
 
-## I don't see the plugin in the API documentation, is it expected ?
+No, currently no authentication is required (or possible).
 
-> Yes, this is expected. This API endpoint is not published in the swagger documentation because it's not a REST compatible endpoint.
+## I don't see the plugin in the API documentation, is it expected?
 
-## Does this plugin support Nautobot 2.0 ?
+Yes, this is expected. This API endpoint is not published in the swagger documentation because it's not a REST compatible endpoint.
 
-> Yes
+## Does this plugin support Nautobot 2.0?
+
+Yes
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -99,19 +99,23 @@ watch:
 nav:
   - Overview: "index.md"
   - User Guide:
+      - App Overview: "user/app_overview.md"
       - Getting Started: "user/app_getting_started.md"
+      - Using the App: "user/app_use_cases.md"
       - Frequently Asked Questions: "user/faq.md"
+      - External Interactions: "user/external_interactions.md"
   - Administrator Guide:
       - Install and Configure: "admin/install.md"
       - Upgrade: "admin/upgrade.md"
+      - Uninstall: "admin/uninstall.md"
       - Compatibility Matrix: "admin/compatibility_matrix.md"
       - Release Notes:
           - "admin/release_notes/index.md"
-          - v1.0: "admin/release_notes/version_1.0.md"
-          - v1.1: "admin/release_notes/version_1.1.md"
-          - v2.0: "admin/release_notes/version_2.0.md"
-          - v2.1: "admin/release_notes/version_2.1.md"
           - v3.0: "admin/release_notes/version_3.0.md"
+          - v2.1: "admin/release_notes/version_2.1.md"
+          - v2.0: "admin/release_notes/version_2.0.md"
+          - v1.1: "admin/release_notes/version_1.1.md"
+          - v1.0: "admin/release_notes/version_1.0.md"
   - Developer Guide:
       - Extending the App: "dev/extending.md"
       - Contributing to the App: "dev/contributing.md"

diff --git a/nautobot_capacity_metrics/api/urls.py b/nautobot_capacity_metrics/api/urls.py
@@ -1,11 +1,7 @@
 """Django URL patterns for nautobot_capacity_metrics plugin."""
-
-from django.conf import settings
 from django.urls import path
 from . import views
 
-PLUGIN_SETTINGS = settings.PLUGINS_CONFIG["nautobot_capacity_metrics"]["app_metrics"]
-
 urlpatterns = [
     path("app-metrics", views.AppMetricsView, name="nautobot_capacity_metrics_app_view"),
 ]