17 files changed, 480 insertions, 0 deletions
diff --git a/integrations/templates/README.md b/integrations/templates/README.md
new file mode 100644
index 000000000..3dcc5ad04
--- /dev/null
+++ b/integrations/templates/README.md
@@ -0,0 +1,27 @@
+This directory contains templates used to generate the `integrations.js` file.
+
+Templating is done using Jinja2 as a templating engine. Full documentation
+can be found at https://jinja.palletsprojects.com/en/ (the ‘Template
+Designer Documentation’ is the relevant part for people looking to
+edit the templates, it’s not linked directly here to avoid embedding
+version numbers in the links).
+
+The particular instance of Jinja2 used has the following configuration
+differences from the defaults:
+
+- Any instances of curly braces in are replaced with square brackets
+  (so instead of `{{ variable }}`, the syntax used here is `[[ variable
+  ]]`. This is done so that templating commands for the frontend can be
+  included without having to do any special escaping for them.
+- `trim_blocks` and `lstrip_blocks` are both enabled, meaning that
+  the first newline after a block will be _removed_, as will any leading
+  whitespace on the same line as a block.
+
+Each markdown template corresponds to the key of the same name in the
+integrations objects in that file. Those templates get passed the
+integration data using the name `entry`, plus the composed related
+resource data using the name `rel_res`.
+
+The `integrations.js` template is used to compose the final file. It gets
+passed the JSON-formatted category and integration data using the names
+`categories` and `integrations` respectively.
diff --git a/integrations/templates/alerts.md b/integrations/templates/alerts.md
new file mode 100644
index 000000000..ca8bd66e6
--- /dev/null
+++ b/integrations/templates/alerts.md
@@ -0,0 +1,14 @@
+## Alerts
+
+[% if entry.alerts %]
+
+The following alerts are available:
+
+| Alert name  | On metric | Description |
+|:------------|:----------|:------------|
+[% for alert in entry.alerts %]
+| [ [[ alert.name ]] ]([[ alert.link ]]) | [[ alert.metric ]] | [[ alert.info ]] |
+[% endfor %]
+[% else %]
+There are no alerts configured by default for this integration.
+[% endif %]
diff --git a/integrations/templates/integrations.js b/integrations/templates/integrations.js
new file mode 100644
index 000000000..7af65508c
--- /dev/null
+++ b/integrations/templates/integrations.js
@@ -0,0 +1,6 @@
+// DO NOT EDIT THIS FILE DIRECTLY
+// It gets generated by integrations/gen_integrations.py in the Netdata repo
+
+export const categories = [[ categories ]]
+export const integrations = [[ integrations ]]
+
diff --git a/integrations/templates/metrics.md b/integrations/templates/metrics.md
new file mode 100644
index 000000000..95fa7504b
--- /dev/null
+++ b/integrations/templates/metrics.md
@@ -0,0 +1,49 @@
+[% if entry.metrics.scopes %]
+## Metrics
+
+[% if entry.metrics.folding.enabled %]
+{% details summary="[[ entry.metrics.folding.title ]]" %}
+[% endif %]
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+[[ entry.metrics.description ]]
+
+[% for scope in entry.metrics.scopes %]
+### Per [[ scope.name ]]
+
+[[ scope.description ]]
+
+[% if scope.labels %]
+Labels:
+
+| Label      | Description     |
+|:-----------|:----------------|
+[% for label in scope.labels %]
+| [[ label.name ]] | [[ label.description ]] |
+[% endfor %]
+[% else %]
+This scope has no labels.
+[% endif %]
+
+Metrics:
+
+| Metric | Dimensions | Unit |[% for a in entry.metrics.availability %] [[ a ]] |[% endfor %]
+
+|:------|:----------|:----|[% for a in entry.metrics.availability %]:---:|[% endfor %]
+
+[% for metric in scope.metrics %]
+| [[ metric.name ]] | [% for d in metric.dimensions %][[ d.name ]][% if not loop.last %], [% endif %][% endfor %] | [[ metric.unit ]] |[% for a in entry.metrics.availability %] [% if not metric.availability|length or a in metric.availability %]•[% else %] [% endif %] |[% endfor %]
+
+[% endfor %]
+
+[% endfor %]
+[% if entry.metrics.folding.enabled %]
+{% /details %}
+[% endif %]
+[% else %]
+## Metrics
+
+[[ entry.metrics.description ]]
+[% endif %]
diff --git a/integrations/templates/overview.md b/integrations/templates/overview.md
new file mode 100644
index 000000000..b89e51543
--- /dev/null
+++ b/integrations/templates/overview.md
@@ -0,0 +1,7 @@
+[% if entry.integration_type == 'collector' %]
+[% include 'overview/collector.md' %]
+[% elif entry.integration_type == 'exporter' %]
+[% include 'overview/exporter.md' %]
+[% elif entry.integration_type == 'notification' %]
+[% include 'overview/notification.md' %]
+[% endif %]
diff --git a/integrations/templates/overview/collector.md b/integrations/templates/overview/collector.md
new file mode 100644
index 000000000..0030b2533
--- /dev/null
+++ b/integrations/templates/overview/collector.md
@@ -0,0 +1,67 @@
+# [[ entry.meta.monitored_instance.name ]]
+
+## Overview
+
+[[ entry.overview.data_collection.metrics_description ]]
+
+[[ entry.overview.data_collection.method_description ]]
+
+[% if entry.overview.supported_platforms.include %]
+This collector is only supported on the following platforms:
+
+[% for platform in entry.overview.supported_platforms.include %]
+- [[ platform ]]
+[% endfor %]
+[% elif entry.overview.supported_platforms.exclude %]
+This collector is supported on all platforms except for the following platforms:
+
+[% for platform in entry.overview.supported_platforms.exclude %]
+- [[ platform ]]
+[% endfor %]
+[% else %]
+This collector is supported on all platforms.
+[% endif %]
+
+[% if entry.overview.multi_instance %]
+This collector supports collecting metrics from multiple instances of this integration, including remote instances.
+[% else %]
+This collector only supports collecting metrics from a single instance of this integration.
+[% endif %]
+
+[% if entry.overview.additional_permissions.description %]
+[[ entry.overview.additional_permissions.description ]]
+[% endif %]
+
+[% if related %]
+[[ entry.meta.name ]] can be monitored further using the following other integrations:
+
+[% for res in related %]
+- {% relatedResource id="[[ res.id ]]" %}[[ res.name ]]{% /relatedResource %}
+[% endfor %]
+
+[% endif %]
+### Default Behavior
+
+#### Auto-Detection
+
+[% if entry.overview.default_behavior.auto_detection.description %]
+[[ entry.overview.default_behavior.auto_detection.description ]]
+[% else %]
+This integration doesn't support auto-detection.
+[% endif %]
+
+#### Limits
+
+[% if entry.overview.default_behavior.limits.description %]
+[[ entry.overview.default_behavior.limits.description ]]
+[% else %]
+The default configuration for this integration does not impose any limits on data collection.
+[% endif %]
+
+#### Performance Impact
+
+[% if entry.overview.default_behavior.performance_impact.description %]
+[[ entry.overview.default_behavior.performance_impact.description ]]
+[% else %]
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+[% endif %]
diff --git a/integrations/templates/overview/exporter.md b/integrations/templates/overview/exporter.md
new file mode 100644
index 000000000..218a67b7d
--- /dev/null
+++ b/integrations/templates/overview/exporter.md
@@ -0,0 +1,9 @@
+# [[ entry.meta.name ]]
+
+[[ entry.overview.exporter_description ]]
+[% if entry.overview.exporter_limitations %]
+
+## Limitations
+
+[[ entry.overview.exporter_limitations ]]
+[% endif %]
diff --git a/integrations/templates/overview/notification.md b/integrations/templates/overview/notification.md
new file mode 100644
index 000000000..37e5785a4
--- /dev/null
+++ b/integrations/templates/overview/notification.md
@@ -0,0 +1,9 @@
+# [[ entry.meta.name ]]
+
+[[ entry.overview.notification_description ]]
+[% if entry.overview.notification_limitations %]
+
+## Limitations
+
+[[ entry.overview.notification_limitations ]]
+[% endif %]
diff --git a/integrations/templates/platform_info.md b/integrations/templates/platform_info.md
new file mode 100644
index 000000000..dfa0b1980
--- /dev/null
+++ b/integrations/templates/platform_info.md
@@ -0,0 +1,9 @@
+[% if entries %]
+The following releases of this platform are supported:
+
+| Version | Support Tier | Native Package Architectures | Notes |
+|:-------:|:------------:|:----------------------------:|:----- |
+[% for e in entries %]
+| [[ e.version ]] | [[ e.support ]] | [[ ', '.join(e.arches) ]] | [[ e.notes ]] |
+[% endfor %]
+[% endif %]
diff --git a/integrations/templates/related_resources.md b/integrations/templates/related_resources.md
new file mode 100644
index 000000000..b7a199e8b
--- /dev/null
+++ b/integrations/templates/related_resources.md
@@ -0,0 +1,7 @@
+[% if related %]
+You can further monitor this integration by using:
+
+[% for item in related %]
+- {% relatedResource id="[[ item.id ]]" %}[[ item.name ]]{% /relatedResource %}: [[ item.info.description ]]
+[% endfor %]
+[% endif %]
diff --git a/integrations/templates/setup.md b/integrations/templates/setup.md
new file mode 100644
index 000000000..101f5bcbc
--- /dev/null
+++ b/integrations/templates/setup.md
@@ -0,0 +1,108 @@
+## Setup
+
+[% if entry.setup.description %]
+[[ entry.setup.description ]]
+[% else %]
+### Prerequisites
+[% if entry.setup.prerequisites.list %]
+
+[% for prereq in entry.setup.prerequisites.list %]
+#### [[ prereq.title ]]
+
+[[ prereq.description ]]
+
+[% endfor %]
+
+[% else %]
+
+No action required.
+
+[% endif %]
+### Configuration
+
+#### File
+
+[% if entry.setup.configuration.file.name %]
+The configuration file name for this integration is `[[ entry.setup.configuration.file.name ]]`.
+[% if 'section_name' in entry.setup.configuration.file %]
+Configuration for this specific integration is located in the `[[ entry.setup.configuration.file.section_name ]]` section within that file.
+[% endif %]
+
+[% if entry.plugin_name == 'go.d.plugin' %]
+[% include 'setup/sample-go-config.md' %]
+[% elif entry.plugin_name == 'python.d.plugin' %]
+[% include 'setup/sample-python-config.md' %]
+[% elif entry.plugin_name == 'charts.d.plugin' %]
+[% include 'setup/sample-charts-config.md' %]
+[% elif entry.plugin_name == 'ioping.plugin' %]
+[% include 'setup/sample-charts-config.md' %]
+[% elif entry.plugin_name == 'apps.plugin' %]
+[% include 'setup/sample-apps-config.md' %]
+[% elif entry.plugin_name == 'ebpf.plugin' %]
+[% include 'setup/sample-netdata-config.md' %]
+[% elif entry.setup.configuration.file.name == 'netdata.conf' %]
+[% include 'setup/sample-netdata-config.md' %]
+[% endif %]
+
+You can edit the configuration file using the `edit-config` script from the
+Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory).
+
+```bash
+cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
+sudo ./edit-config [[ entry.setup.configuration.file.name ]]
+```
+[% else %]
+There is no configuration file.
+[% endif %]
+#### Options
+
+[[ entry.setup.configuration.options.description ]]
+
+[% if entry.setup.configuration.options.list %]
+[% if entry.setup.configuration.options.folding.enabled %]
+{% details summary="[[ entry.setup.configuration.options.folding.title ]]" %}
+[% endif %]
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+[% for item in entry.setup.configuration.options.list %]
+| [[ item.name ]] | [[ item.description ]] | [[ item.default ]] | [[ item.required ]] |
+[% endfor %]
+
+[% for item in entry.setup.configuration.options.list %]
+[% if 'detailed_description' in item %]
+##### [[ item.name ]]
+
+[[ item.detailed_description ]]
+
+[% endif %]
+[% endfor %]
+[% if entry.setup.configuration.options.folding.enabled %]
+{% /details %}
+[% endif %]
+[% elif not entry.setup.configuration.options.description %]
+There are no configuration options.
+
+[% endif %]
+#### Examples
+[% if entry.setup.configuration.examples.list %]
+
+[% for example in entry.setup.configuration.examples.list %]
+##### [[ example.name ]]
+
+[[ example.description ]]
+
+[% if example.folding.enabled %]
+{% details summary="[[ entry.setup.configuration.examples.folding.title ]]" %}
+[% endif %]
+```yaml
+[[ example.config ]]
+```
+[% if example.folding.enabled %]
+{% /details %}
+[% endif %]
+[% endfor %]
+[% else%]
+There are no configuration examples.
+
+[% endif %]
+[% endif %]
diff --git a/integrations/templates/setup/sample-apps-config.md b/integrations/templates/setup/sample-apps-config.md
new file mode 100644
index 000000000..eb4837943
--- /dev/null
+++ b/integrations/templates/setup/sample-apps-config.md
@@ -0,0 +1,41 @@
+A custom format is used.
+
+Each configuration line has a form like:
+
+```
+group_name: app1 app2 app3
+```
+
+Where `group_name` defines an application group, and `app1`, `app2`, and `app3` are process names to match for
+that application group.
+
+Each group can be given multiple times, to add more processes to it.
+
+The process names are the ones returned by:
+
+ -  `ps -e` or `/proc/PID/stat`
+ -  in case of substring mode (see below): `/proc/PID/cmdline`
+
+To add process names with spaces, enclose them in quotes (single or double):
+`'Plex Media Serv' "my other process"`
+
+Note that spaces are not supported for process groups. Use a dash "-" instead.
+
+You can add an asterisk (\*) at the beginning and/or the end of a process to do wildcard matching:
+
+ - `*name` suffix mode: will search for processes ending with 'name' (/proc/PID/stat)
+ - `name*` prefix mode: will search for processes beginning with 'name' (/proc/PID/stat)
+ - `*name*` substring mode: will search for 'name' in the whole command line (/proc/PID/cmdline)
+
+If you enter even just one `*name*` (substring), apps.plugin will process /proc/PID/cmdline for all processes,
+just once (when they are first seen).
+
+To add processes with single quotes, enclose them in double quotes: "process with this ' single quote"
+
+To add processes with double quotes, enclose them in single quotes: 'process with this " double quote'
+
+The order of the entries in this list is important, the first that matches a process is used, so put important
+ones at the top. Processes not matched by any row, will inherit it from their parents or children.
+
+The order also controls the order of the dimensions on the generated charts (although applications started after
+apps.plugin is started, will be appended to the existing list of dimensions the netdata daemon maintains).
diff --git a/integrations/templates/setup/sample-charts-config.md b/integrations/templates/setup/sample-charts-config.md
new file mode 100644
index 000000000..affd2b35c
--- /dev/null
+++ b/integrations/templates/setup/sample-charts-config.md
@@ -0,0 +1,6 @@
+The file format is POSIX shell script. Generally, the structure is:
+
+```sh
+OPTION_1="some value"
+OPTION_2="some other value"
+```
diff --git a/integrations/templates/setup/sample-go-config.md b/integrations/templates/setup/sample-go-config.md
new file mode 100644
index 000000000..8be9abb5f
--- /dev/null
+++ b/integrations/templates/setup/sample-go-config.md
@@ -0,0 +1,9 @@
+The file format is YAML. Generally, the structure is:
+
+```yaml
+update_every: 1
+autodetection_retry: 0
+jobs:
+  - name: some_name1
+  - name: some_name1
+```
diff --git a/integrations/templates/setup/sample-netdata-config.md b/integrations/templates/setup/sample-netdata-config.md
new file mode 100644
index 000000000..429f71167
--- /dev/null
+++ b/integrations/templates/setup/sample-netdata-config.md
@@ -0,0 +1,10 @@
+The file format is a modified INI syntax. The general structure is:
+
+```toml
+[section1]
+    option 1 = some value
+    option 2 = some other value
+
+[section2]
+    option 3 = some third value
+```
diff --git a/integrations/templates/setup/sample-python-config.md b/integrations/templates/setup/sample-python-config.md
new file mode 100644
index 000000000..529674555
--- /dev/null
+++ b/integrations/templates/setup/sample-python-config.md
@@ -0,0 +1,10 @@
+The file format is YAML. Generally, the structure is:
+
+```yaml
+update_every: 1
+autodetection_retry: 0
+
+job_name:
+  job_option1: some_value
+  job_option2: some_other_vlaue
+```
diff --git a/integrations/templates/troubleshooting.md b/integrations/templates/troubleshooting.md
new file mode 100644
index 000000000..f78d49a7f
--- /dev/null
+++ b/integrations/templates/troubleshooting.md
@@ -0,0 +1,92 @@
+[% if entry.integration_type == 'collector' %]
+[% if entry.meta.plugin_name is in(['go.d.plugin', 'python.d.plugin', 'charts.d.plugin']) %]
+## Troubleshooting
+
+### Debug Mode
+
+To troubleshoot issues with the `[[ entry.meta.module_name ]]` collector, run the `[[ entry.meta.plugin_name ]]` with the debug option enabled. The output
+should give you clues as to why the collector isn't working.
+
+- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
+  your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
+
+  ```bash
+  cd /usr/libexec/netdata/plugins.d/
+  ```
+
+- Switch to the `netdata` user.
+
+  ```bash
+  sudo -u netdata -s
+  ```
+
+[% if entry.meta.plugin_name == 'go.d.plugin' %]
+- Run the `go.d.plugin` to debug the collector:
+
+  ```bash
+  ./go.d.plugin -d -m [[ entry.meta.module_name ]]
+  ```
+
+[% elif entry.meta.plugin_name == 'python.d.plugin' %]
+- Run the `python.d.plugin` to debug the collector:
+
+  ```bash
+  ./python.d.plugin [[ entry.meta.module_name ]] debug trace
+  ```
+
+[% elif entry.meta.plugin_name == 'charts.d.plugin' %]
+- Run the `charts.d.plugin` to debug the collector:
+
+  ```bash
+  ./charts.d.plugin debug 1 [[ entry.meta.module_name ]]
+  ```
+
+[% endif %]
+[% else %]
+[% if entry.troubleshooting.problems.list %]
+## Troubleshooting
+
+[% endif %]
+[% endif %]
+[% elif entry.integration_type == 'notification' %]
+[% if 'cloud-notifications' in entry._src_path|string %]
+[% if entry.troubleshooting.problems.list %]
+## Troubleshooting
+
+[% endif %]
+[% else %]
+## Troubleshooting
+
+### Test Notification
+
+You can run the following command by hand, to test alerts configuration:
+
+```bash
+# become user netdata
+sudo su -s /bin/bash netdata
+
+# enable debugging info on the console
+export NETDATA_ALARM_NOTIFY_DEBUG=1
+
+# send test alarms to sysadmin
+/usr/libexec/netdata/plugins.d/alarm-notify.sh test
+
+# send test alarms to any role
+/usr/libexec/netdata/plugins.d/alarm-notify.sh test "ROLE"
+```
+
+Note that this will test _all_ alert mechanisms for the selected role.
+
+[% endif %]
+[% elif entry.integration_type == 'exporter' %]
+[% if entry.troubleshooting.problems.list %]
+## Troubleshooting
+
+[% endif %]
+[% endif %]
+[% for item in entry.troubleshooting.problems.list %]
+### [[ item.name ]]
+
+[[ description ]]
+
+[% endfor %]