From dd814a7c1a8de056a79f7238578b09236edd5506 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 10 Aug 2023 11:18:49 +0200 Subject: Adding upstream version 1.42.0. Signed-off-by: Daniel Baumann --- integrations/templates/README.md | 27 ++++++ integrations/templates/alerts.md | 14 +++ integrations/templates/integrations.js | 6 ++ integrations/templates/metrics.md | 49 ++++++++++ integrations/templates/overview.md | 7 ++ integrations/templates/overview/collector.md | 67 +++++++++++++ integrations/templates/overview/exporter.md | 9 ++ integrations/templates/overview/notification.md | 9 ++ integrations/templates/platform_info.md | 9 ++ integrations/templates/related_resources.md | 7 ++ integrations/templates/setup.md | 108 +++++++++++++++++++++ integrations/templates/setup/sample-apps-config.md | 41 ++++++++ .../templates/setup/sample-charts-config.md | 6 ++ integrations/templates/setup/sample-go-config.md | 9 ++ .../templates/setup/sample-netdata-config.md | 10 ++ .../templates/setup/sample-python-config.md | 10 ++ integrations/templates/troubleshooting.md | 92 ++++++++++++++++++ 17 files changed, 480 insertions(+) create mode 100644 integrations/templates/README.md create mode 100644 integrations/templates/alerts.md create mode 100644 integrations/templates/integrations.js create mode 100644 integrations/templates/metrics.md create mode 100644 integrations/templates/overview.md create mode 100644 integrations/templates/overview/collector.md create mode 100644 integrations/templates/overview/exporter.md create mode 100644 integrations/templates/overview/notification.md create mode 100644 integrations/templates/platform_info.md create mode 100644 integrations/templates/related_resources.md create mode 100644 integrations/templates/setup.md create mode 100644 integrations/templates/setup/sample-apps-config.md create mode 100644 integrations/templates/setup/sample-charts-config.md create mode 100644 integrations/templates/setup/sample-go-config.md create mode 100644 integrations/templates/setup/sample-netdata-config.md create mode 100644 integrations/templates/setup/sample-python-config.md create mode 100644 integrations/templates/troubleshooting.md (limited to 'integrations/templates') 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 %] -- cgit v1.2.3