Merging upstream version 1.43.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 235 insertions, 92 deletions

diff --git a/collectors/perf.plugin/README.md b/collectors/perf.plugin/README.md
index a8bd4b0e..fb8a0cd6 100644..120000
--- a/collectors/perf.plugin/README.md
+++ b/collectors/perf.plugin/README.md
@@ -1,87 +1 @@
-<!--
-title: "Monitor CPU performance statistics (perf.plugin)"
-custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/perf.plugin/README.md"
-sidebar_label: "CPU performance statistics (perf.plugin)"
-learn_status: "Published"
-learn_topic_type: "References"
-learn_rel_path: "Integrations/Monitor/System metrics"
--->
-
-# Monitor CPU performance statistics (perf.plugin)
-
-`perf.plugin` collects system-wide CPU performance statistics from Performance Monitoring Units (PMU) using
-the `perf_event_open()` system call.
-
-## Important Notes
-
-If you are using [our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/methods/packages.md), you will need to install
-the `netdata-plugin-perf` package using your system package manager.
-
-Accessing hardware PMUs requires root permissions, so the plugin is setuid to root.
-
-Keep in mind that the number of PMUs in a system is usually quite limited and every hardware monitoring
-event for every CPU core needs a separate file descriptor to be opened.
-
-## Charts
-
-The plugin provides statistics for general hardware and software performance monitoring events:
-
-Hardware events:
-
-1.  CPU cycles
-2.  Instructions
-3.  Branch instructions
-4.  Cache operations
-5.  BUS cycles
-6.  Stalled frontend and backend cycles
-
-Software events:
-
-1.  CPU migrations
-2.  Alignment faults
-3.  Emulation faults
-
-Hardware cache events:
-
-1.  L1D cache operations
-2.  L1D prefetch cache operations
-3.  L1I cache operations
-4.  LL cache operations
-5.  DTLB cache operations
-6.  ITLB cache operations
-7.  PBU cache operations
-
-## Configuration
-
-The plugin is disabled by default because the number of PMUs is usually quite limited and it is not desired to
-allow Netdata to struggle silently for PMUs, interfering with other performance monitoring software. If you need to
-enable the perf plugin, edit /etc/netdata/netdata.conf and set:
-
-```raw
-[plugins]
-    perf = yes
-```
-
-```raw
-[plugin:perf]
-    update every = 1
-    command options = all
-```
-
-You can use the `command options` parameter to pick what data should be collected and which charts should be
-displayed. If `all` is used, all general performance monitoring counters are probed and corresponding charts
-are enabled for the available counters. You can also define a particular set of enabled charts using the
-following keywords: `cycles`, `instructions`, `branch`, `cache`, `bus`, `stalled`, `migrations`, `alignment`,
-`emulation`, `L1D`, `L1D-prefetch`, `L1I`, `LL`, `DTLB`, `ITLB`, `PBU`.
-
-## Debugging
-
-You can run the plugin by hand:
-
-```raw
-sudo /usr/libexec/netdata/plugins.d/perf.plugin 1 all debug
-```
-
-You will get verbose output on what the plugin does.
-
-
+integrations/cpu_performance.md
\ No newline at end of file
diff --git a/collectors/perf.plugin/integrations/cpu_performance.md b/collectors/perf.plugin/integrations/cpu_performance.md
new file mode 100644
index 00000000..a4adeb1c
--- /dev/null
+++ b/collectors/perf.plugin/integrations/cpu_performance.md
@@ -0,0 +1,191 @@
+<!--startmeta
+custom_edit_url: "https://github.com/netdata/netdata/edit/master/collectors/perf.plugin/README.md"
+meta_yaml: "https://github.com/netdata/netdata/edit/master/collectors/perf.plugin/metadata.yaml"
+sidebar_label: "CPU performance"
+learn_status: "Published"
+learn_rel_path: "Data Collection/Linux Systems"
+message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
+endmeta-->
+
+# CPU performance
+
+
+<img src="https://netdata.cloud/img/bolt.svg" width="150"/>
+
+
+Plugin: perf.plugin
+Module: perf.plugin
+
+<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
+
+## Overview
+
+This collector monitors CPU performance metrics about cycles, instructions, migrations, cache operations and more.
+
+It uses syscall (2) to open a file descriptior to monitor the perf events.
+
+This collector is only supported on the following platforms:
+
+- Linux
+
+This collector supports collecting metrics from multiple instances of this integration, including remote instances.
+
+It needs setuid to use necessary syscall to collect perf events. Netada sets the permission during installation time.
+
+### Default Behavior
+
+#### Auto-Detection
+
+This integration doesn't support auto-detection.
+
+#### Limits
+
+The default configuration for this integration does not impose any limits on data collection.
+
+#### Performance Impact
+
+The default configuration for this integration is not expected to impose a significant performance impact on the system.
+
+
+## Metrics
+
+Metrics grouped by *scope*.
+
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
+
+
+
+### Per CPU performance instance
+
+These metrics refer to the entire monitored application.
+
+This scope has no labels.
+
+Metrics:
+
+| Metric | Dimensions | Unit |
+|:------|:----------|:----|
+| perf.cpu_cycles | cpu, ref_cpu | cycles/s |
+| perf.instructions | instructions | instructions/s |
+| perf.instructions_per_cycle | ipc | instructions/cycle |
+| perf.branch_instructions | instructions, misses | instructions/s |
+| perf.cache | references, misses | operations/s |
+| perf.bus_cycles | bus | cycles/s |
+| perf.stalled_cycles | frontend, backend | cycles/s |
+| perf.migrations | migrations | migrations |
+| perf.alignment_faults | faults | faults |
+| perf.emulation_faults | faults | faults |
+| perf.l1d_cache | read_access, read_misses, write_access, write_misses | events/s |
+| perf.l1d_cache_prefetch | prefetches | prefetches/s |
+| perf.l1i_cache | read_access, read_misses | events/s |
+| perf.ll_cache | read_access, read_misses, write_access, write_misses | events/s |
+| perf.dtlb_cache | read_access, read_misses, write_access, write_misses | events/s |
+| perf.itlb_cache | read_access, read_misses | events/s |
+| perf.pbu_cache | read_access | events/s |
+
+
+
+## Alerts
+
+There are no alerts configured by default for this integration.
+
+
+## Setup
+
+### Prerequisites
+
+#### Install perf plugin
+
+If you are [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure the `netdata-plugin-perf` package is installed.
+
+
+#### Enable the pref plugin
+
+The plugin is disabled by default because the number of PMUs is usually quite limited and it is not desired to allow Netdata to struggle silently for PMUs, interfering with other performance monitoring software.
+
+To enable it, use `edit-config` from the Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`, to edit the `netdata.conf` file.
+
+```bash
+cd /etc/netdata   # Replace this path with your Netdata config directory, if different
+sudo ./edit-config netdata.conf
+```
+
+Change the value of the `perf` setting to `yes` in the `[plugins]` section. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system.
+
+
+
+### Configuration
+
+#### File
+
+The configuration file name for this integration is `netdata.conf`.
+Configuration for this specific integration is located in the `[plugin:perf]` section within that file.
+
+The file format is a modified INI syntax. The general structure is:
+
+```ini
+[section1]
+    option1 = some value
+    option2 = some other value
+
+[section2]
+    option3 = some third value
+```
+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 netdata.conf
+```
+#### Options
+
+You can get the available options running:
+
+```bash
+/usr/libexec/netdata/plugins.d/perf.plugin  --help
+````
+
+
+<details><summary>Config options</summary>
+
+| Name | Description | Default | Required |
+|:----|:-----------|:-------|:--------:|
+| update every | Data collection frequency. | 1 | False |
+| command options | Command options that specify charts shown by plugin. `cycles`, `instructions`, `branch`, `cache`, `bus`, `stalled`, `migrations`, `alignment`, `emulation`, `L1D`, `L1D-prefetch`, `L1I`, `LL`, `DTLB`, `ITLB`, `PBU`. | 1 | True |
+
+</details>
+
+#### Examples
+
+##### All metrics
+
+Monitor all metrics available.
+
+```yaml
+[plugin:perf]
+    command options = all
+
+```
+##### CPU cycles
+
+Monitor CPU cycles.
+
+<details><summary>Config</summary>
+
+```yaml
+[plugin:perf]
+    command options = cycles
+
+```
+</details>
+
+
+
+## Troubleshooting
+
+### Debug Mode
+
+
+
+
diff --git a/collectors/perf.plugin/metadata.yaml b/collectors/perf.plugin/metadata.yaml
index d7539b50..eada3351 100644
--- a/collectors/perf.plugin/metadata.yaml
+++ b/collectors/perf.plugin/metadata.yaml
@@ -40,7 +40,22 @@ modules:
           description: ""
     setup:
       prerequisites:
-        list: []
+        list:
+          - title: Install perf plugin
+            description: |
+              If you are [using our official native DEB/RPM packages](https://github.com/netdata/netdata/blob/master/packaging/installer/UPDATE.md#determine-which-installation-method-you-used), make sure the `netdata-plugin-perf` package is installed.
+          - title: Enable the pref plugin
+            description: |
+              The plugin is disabled by default because the number of PMUs is usually quite limited and it is not desired to allow Netdata to struggle silently for PMUs, interfering with other performance monitoring software.
+
+              To enable it, use `edit-config` from the Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md), which is typically at `/etc/netdata`, to edit the `netdata.conf` file.
+
+              ```bash
+              cd /etc/netdata   # Replace this path with your Netdata config directory, if different
+              sudo ./edit-config netdata.conf
+              ```
+
+              Change the value of the `perf` setting to `yes` in the `[plugins]` section. Save the file and restart the Netdata Agent with `sudo systemctl restart netdata`, or the [appropriate method](https://github.com/netdata/netdata/blob/master/docs/configure/start-stop-restart.md) for your system.
       configuration:
         file:
           name: "netdata.conf"
@@ -49,7 +64,7 @@ modules:
         options:
           description: |
             You can get the available options running:
-            
+
             ```bash
             /usr/libexec/netdata/plugins.d/perf.plugin  --help
             ````
@@ -62,7 +77,7 @@ modules:
               default_value: 1
               required: false
             - name: command options
-              description: Command options that specify charts shown by plugin.
+              description: Command options that specify charts shown by plugin. `cycles`, `instructions`, `branch`, `cache`, `bus`, `stalled`, `migrations`, `alignment`, `emulation`, `L1D`, `L1D-prefetch`, `L1I`, `LL`, `DTLB`, `ITLB`, `PBU`.
               default_value: 1
               required: true
         examples:
@@ -84,7 +99,28 @@ modules:
                     command options = cycles
     troubleshooting:
       problems:
-        list: []
+        list:
+          - name: Debug Mode
+            description: |
+              You can run `perf.plugin` with the debug option enabled, to troubleshoot issues with it. 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
+                ```
+
+              - Run the `perf.plugin` in debug mode:
+
+                ```bash
+                ./perf.plugin 1 all debug
+                ```
     alerts: []
     metrics:
       folding:
diff --git a/collectors/perf.plugin/perf_plugin.c b/collectors/perf.plugin/perf_plugin.c
index 68c0f917..31dae03e 100644
--- a/collectors/perf.plugin/perf_plugin.c
+++ b/collectors/perf.plugin/perf_plugin.c
@@ -1298,6 +1298,8 @@ int main(int argc, char **argv) {
     error_log_errors_per_period = 100;
     error_log_throttle_period = 3600;
 
+    log_set_global_severity_for_external_plugins();
+
     parse_command_line(argc, argv);
 
     errno = 0;
@@ -1328,7 +1330,7 @@ int main(int argc, char **argv) {
         if(unlikely(netdata_exit)) break;
 
         if(unlikely(debug && iteration))
-            fprintf(stderr, "perf.plugin: iteration %zu, dt %llu usec\n"
+            fprintf(stderr, "perf.plugin: iteration %zu, dt %"PRIu64" usec\n"
                     , iteration
                     , dt
             );