diff options
Diffstat (limited to 'docs/developer-and-contributor-corner')
16 files changed, 116 insertions, 182 deletions
diff --git a/docs/developer-and-contributor-corner/README.md b/docs/developer-and-contributor-corner/README.md index d4d86382..81793812 100644 --- a/docs/developer-and-contributor-corner/README.md +++ b/docs/developer-and-contributor-corner/README.md @@ -1,3 +1,3 @@ # Developer and Contributor Corner -In this section of our Documentation you will find more advanced information, suited for developers and contributors alike.
\ No newline at end of file +In this section of our Documentation you will find more advanced information, suited for developers and contributors alike. diff --git a/docs/developer-and-contributor-corner/build-the-netdata-agent-yourself.md b/docs/developer-and-contributor-corner/build-the-netdata-agent-yourself.md index 99166ad9..d98784cc 100644 --- a/docs/developer-and-contributor-corner/build-the-netdata-agent-yourself.md +++ b/docs/developer-and-contributor-corner/build-the-netdata-agent-yourself.md @@ -1,3 +1,3 @@ # Build the Netdata Agent yourself -This section contains documentation on all the ways that you can build the Netdata Agent.
\ No newline at end of file +This section contains documentation on all the ways that you can build the Netdata Agent. diff --git a/docs/developer-and-contributor-corner/collect-apache-nginx-web-logs.md b/docs/developer-and-contributor-corner/collect-apache-nginx-web-logs.md index 55af82fb..9a307b0b 100644 --- a/docs/developer-and-contributor-corner/collect-apache-nginx-web-logs.md +++ b/docs/developer-and-contributor-corner/collect-apache-nginx-web-logs.md @@ -81,18 +81,13 @@ jobs: log_type: auto ``` -Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate -method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system. Netdata should pick up your web server's access log and -begin showing real-time charts! +Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate method](/docs/netdata-agent/start-stop-restart.md) for your system. Netdata should pick up your web server's access log and begin showing real-time charts! ### Custom log formats and fields -The web log collector is capable of parsing custom Nginx and Apache log formats and presenting them as charts, but we'll -leave that topic for a separate guide. +The web log collector is capable of parsing custom Nginx and Apache log formats and presenting them as charts, but we'll leave that topic for a separate guide. -We do have [extensive -documentation](/src/go/plugin/go.d/modules/weblog/README.md#custom-log-format) on how -to build custom parsing for Nginx and Apache logs. +We do have [extensive documentation](/src/go/plugin/go.d/modules/weblog/README.md) on how to build custom parsing for Nginx and Apache logs. ## Tweak web log collector alerts @@ -100,7 +95,7 @@ Over time, we've created some default alerts for web log monitoring. These alert web server is receiving more than 120 requests per minute. Otherwise, there's simply not enough data to make conclusions about what is "too few" or "too many." -- [web log alerts](https://raw.githubusercontent.com/netdata/netdata/master/src/health/health.d/web_log.conf). +- [web log alerts](https://raw.githubusercontent.com/netdata/netdata/master/src/health/health.d/web_log.conf). You can also edit this file directly with `edit-config`: @@ -108,5 +103,5 @@ You can also edit this file directly with `edit-config`: ./edit-config health.d/weblog.conf ``` -For more information about editing the defaults or writing new alert entities, see our +For more information about editing the defaults or writing new alert entities, see our [health monitoring documentation](/src/health/README.md). diff --git a/docs/developer-and-contributor-corner/collect-unbound-metrics.md b/docs/developer-and-contributor-corner/collect-unbound-metrics.md index ac997b7f..abfaca72 100644 --- a/docs/developer-and-contributor-corner/collect-unbound-metrics.md +++ b/docs/developer-and-contributor-corner/collect-unbound-metrics.md @@ -1,13 +1,3 @@ -<!-- -title: "Monitor Unbound DNS servers with Netdata" -sidebar_label: "Monitor Unbound DNS servers with Netdata" -date: 2020-03-31 -custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/collect-unbound-metrics.md -learn_status: "Published" -learn_topic_type: "Tasks" -learn_rel_path: "Miscellaneous" ---> - # Monitor Unbound DNS servers with Netdata [Unbound](https://nlnetlabs.nl/projects/unbound/about/) is a "validating, recursive, caching DNS resolver" from NLNet @@ -35,7 +25,7 @@ the TLS key files that will encrypt connections to the remote interface. Then ad documentation](https://nlnetlabs.nl/documentation/unbound/howto-setup/#setup-remote-control) for more details on using `unbound-control`, such as how to handle situations when Unbound is run under a unique user. -```conf +```text # enable remote-control remote-control: control-enable: yes @@ -137,5 +127,3 @@ Now that you're collecting metrics from your Unbound servers, let us know how it for improvement or refinement based on real-world use cases. Feel free to [file an issue](https://github.com/netdata/netdata/issues/new?assignees=&labels=bug%2Cneeds+triage&template=BUG_REPORT.yml) with your thoughts. - - diff --git a/docs/developer-and-contributor-corner/customize.md b/docs/developer-and-contributor-corner/customize.md index 03a6a842..7d9895dc 100644 --- a/docs/developer-and-contributor-corner/customize.md +++ b/docs/developer-and-contributor-corner/customize.md @@ -1,15 +1,15 @@ # Customize the standard dashboard -> ### Disclaimer +> **Disclaimer** > > This document is only applicable to the v1 version of the dashboard and doesn't affect the [Netdata Dashboard](/docs/dashboards-and-charts/README.md). -While the [Netdata dashboard](/src/web/gui/README.md) comes preconfigured with hundreds of charts and +While the [Netdata dashboard](/src/web/gui/README.md) comes pre-configured with hundreds of charts and thousands of metrics, you may want to alter your experience based on a particular use case or preferences. ## Dashboard settings -To change dashboard settings, click the on the **settings** icon +To change dashboard settings, click the on the **settings** icon  in the top panel. @@ -21,10 +21,9 @@ Here are a few popular settings: ### Change chart legend position -Find this setting under the **Visual** tab. By default, Netdata places the legend of dimensions _below_ charts. +Find this setting under the **Visual** tab. By default, Netdata places the legend of dimensions _below_ charts. Click this toggle to move the legend to the _right_ of charts. - ### Change theme Find this setting under the **Visual** tab. Choose between Dark (the default) and White. @@ -67,9 +66,9 @@ dashboard. Save the file, then navigate to your [Netdata config directory](/docs/netdata-agent/configuration/README.md) to edit `netdata.conf`. Add the following line to the `[web]` section to tell Netdata where to find your custom configuration. -```conf +```text [web] custom dashboard_info.js = your_dashboard_info_file.js ``` -Reload your browser tab to see your custom configuration.
\ No newline at end of file +Reload your browser tab to see your custom configuration. diff --git a/docs/developer-and-contributor-corner/kubernetes-k8s-netdata.md b/docs/developer-and-contributor-corner/kubernetes-k8s-netdata.txt index 011aac8d..5ebb963c 100644 --- a/docs/developer-and-contributor-corner/kubernetes-k8s-netdata.md +++ b/docs/developer-and-contributor-corner/kubernetes-k8s-netdata.txt @@ -19,7 +19,7 @@ troubleshoot issues with your cluster. Some k8s providers, like GKE (Google Kubernetes Engine), do deploy clusters bundled with monitoring capabilities, such as Google Stackdriver Monitoring. However, these pre-configured solutions might not offer the depth of metrics, -customization, or integration with your preferred alerting methods. +customization, or integration with your preferred alerting methods. Without this visibility, it's like you built an entire house and _then_ smashed your way through the finished walls to add windows. @@ -35,15 +35,15 @@ navigation and best practices are the same for every cluster. To follow this tutorial, you need: -- A free Netdata Cloud account. [Sign up](https://app.netdata.cloud/sign-up?cloudRoute=/spaces) if you don't have one +- A free Netdata Cloud account. [Sign up](https://app.netdata.cloud/sign-up?cloudRoute=/spaces) if you don't have one already. -- A working cluster running Kubernetes v1.9 or newer, with a Netdata deployment and connected parent/child nodes. See +- A working cluster running Kubernetes v1.9 or newer, with a Netdata deployment and connected parent/child nodes. See our [Kubernetes deployment process](/packaging/installer/methods/kubernetes.md) for details on deployment and - conneting to Cloud. -- The [`kubectl`](https://kubernetes.io/docs/reference/kubectl/overview/) command line tool, within [one minor version + connecting to Cloud. +- The [`kubectl`](https://kubernetes.io/docs/reference/kubectl/overview/) command line tool, within [one minor version difference](https://kubernetes.io/docs/tasks/tools/install-kubectl/#before-you-begin) of your cluster, on an administrative system. -- The [Helm package manager](https://helm.sh/) v3.0.0 or newer on the same administrative system. +- The [Helm package manager](https://helm.sh/) v3.0.0 or newer on the same administrative system. ### Install the `robot-shop` demo (optional) @@ -112,7 +112,6 @@ cluster](https://user-images.githubusercontent.com/1153921/109042169-19c8fa00-76 For example, the chart above shows a spike in the CPU utilization from `rabbitmq` every minute or so, along with a baseline CPU utilization of 10-15% across the cluster. - ## Pod and container metrics Click on the **Kubernetes xxxxxxx...** section to jump down to Netdata Cloud's unique Kubernetes visualizations for view @@ -233,5 +232,3 @@ clusters of all sizes. - [Netdata Agent ยท `kube-proxy` collector](/src/go/plugin/go.d/modules/k8s_kubeproxy/README.md) - [Netdata Agent ยท `cgroups.plugin`](/src/collectors/cgroups.plugin/README.md) - - diff --git a/docs/developer-and-contributor-corner/lamp-stack.md b/docs/developer-and-contributor-corner/lamp-stack.txt index 2df5a716..bc4611ac 100644 --- a/docs/developer-and-contributor-corner/lamp-stack.md +++ b/docs/developer-and-contributor-corner/lamp-stack.txt @@ -104,8 +104,7 @@ GRANT USAGE, REPLICATION CLIENT, PROCESS ON *.* TO 'netdata'@'localhost'; FLUSH PRIVILEGES; ``` -Run `sudo systemctl restart netdata`, or the [appropriate alternative for your -system](/packaging/installer/README.md#maintaining-a-netdata-agent-installation), to collect dozens of metrics every second for robust MySQL monitoring. +Run `sudo systemctl restart netdata`, or the [appropriate alternative for your system](/docs/netdata-agent/start-stop-restart.md), to collect dozens of metrics every second for robust MySQL monitoring. ## Enable PHP monitoring @@ -125,7 +124,7 @@ sudo nano /etc/php/7.4/fpm/pool.d/www.conf Find the line that reads `;pm.status_path = /status` and remove the `;` so it looks like this: -```conf +```text pm.status_path = /status ``` diff --git a/docs/developer-and-contributor-corner/monitor-cockroachdb.md b/docs/developer-and-contributor-corner/monitor-cockroachdb.txt index f0db12cc..d677c376 100644 --- a/docs/developer-and-contributor-corner/monitor-cockroachdb.md +++ b/docs/developer-and-contributor-corner/monitor-cockroachdb.txt @@ -37,8 +37,8 @@ configuring CockroachDB. Netdata only needs to regularly query the database's `_ display them on the dashboard. If your CockroachDB instance is accessible through `http://localhost:8080/` or `http://127.0.0.1:8080`, your setup is -complete. Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate -method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, and refresh your browser. You should see CockroachDB +complete. Restart Netdata with `sudo systemctl restart netdata`, or the appropriate +method for your system, and refresh your browser. You should see CockroachDB metrics in your Netdata dashboard! <figure> diff --git a/docs/developer-and-contributor-corner/monitor-debug-applications-ebpf.md b/docs/developer-and-contributor-corner/monitor-debug-applications-ebpf.md index 91d2a2ef..56f0276b 100644 --- a/docs/developer-and-contributor-corner/monitor-debug-applications-ebpf.md +++ b/docs/developer-and-contributor-corner/monitor-debug-applications-ebpf.md @@ -1,13 +1,3 @@ -<!-- -title: "Monitor, troubleshoot, and debug applications with eBPF metrics" -sidebar_label: "Monitor, troubleshoot, and debug applications with eBPF metrics" -description: "Use Netdata's built-in eBPF metrics collector to monitor, troubleshoot, and debug your custom application using low-level kernel feedback." -image: /img/seo/guides/troubleshoot/monitor-debug-applications-ebpf.png -custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/troubleshoot/monitor-debug-applications-ebpf.md -learn_status: "Published" -learn_rel_path: "Operations" ---> - # Monitor, troubleshoot, and debug applications with eBPF metrics When trying to troubleshoot or debug a finicky application, there's no such thing as too much information. At Netdata, @@ -48,7 +38,7 @@ your application's process name. Your file should now look like this: -```conf +```text ... # ----------------------------------------------------------------------------- # Custom applications to monitor with apps.plugin and ebpf.plugin @@ -60,15 +50,14 @@ dev: custom-app ... ``` -Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate -method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, to begin seeing metrics for this particular +Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate method](/docs/netdata-agent/start-stop-restart.md) for your system, to begin seeing metrics for this particular group+process. You can also add additional processes to the same group. You can set up `apps_groups.conf` to more show more precise eBPF metrics for any application or service running on your system, even if it's a standard package like Redis, Apache, or any other [application/service Netdata collects from](/src/collectors/COLLECTORS.md). -```conf +```text # ----------------------------------------------------------------------------- # Custom applications to monitor with apps.plugin and ebpf.plugin @@ -99,7 +88,7 @@ sudo ./edit-config ebpf.d.conf Replace `entry` with `return`: -```conf +```text [global] ebpf load mode = return disable apps = no @@ -109,8 +98,7 @@ Replace `entry` with `return`: network viewer = yes ``` -Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate -method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system. +Restart Netdata with `sudo systemctl restart netdata`, or the [appropriate method](/docs/netdata-agent/start-stop-restart.md) for your system. ## Get familiar with per-application eBPF metrics and charts @@ -139,7 +127,7 @@ In these charts, you can see first a spike in syscalls to open and close files f followed by a similar spike from the Apache benchmark. > ๐ Don't forget that you can view chart data directly via Netdata's API! -> +> > For example, open your browser and navigate to `http://NODE:19999/api/v1/data?chart=apps.file_open`, replacing `NODE` > with the IP address or hostname of your Agent. The API returns JSON of that chart's dimensions and metrics, which you > can use in other operations. @@ -245,10 +233,7 @@ Once you've added one or more nodes to a Space in Netdata Cloud, you can see agg dashboard under the same **Applications** or **eBPF** sections that you find on the local Agent dashboard. Or, [create new dashboards](/docs/dashboards-and-charts/dashboards-tab.md) using eBPF metrics from any number of distributed nodes to see how your application interacts with multiple Linux kernels on multiple Linux -systems. +systems. Now that you can see eBPF metrics in Netdata Cloud, you can [invite your team](/docs/netdata-cloud/organize-your-infrastructure-invite-your-team.md#invite-your-team) and share your findings with others. - - - diff --git a/docs/developer-and-contributor-corner/monitor-hadoop-cluster.md b/docs/developer-and-contributor-corner/monitor-hadoop-cluster.md index 98bf3d21..8638f6d6 100644 --- a/docs/developer-and-contributor-corner/monitor-hadoop-cluster.md +++ b/docs/developer-and-contributor-corner/monitor-hadoop-cluster.md @@ -1,12 +1,3 @@ -<!-- -title: "Monitor a Hadoop cluster with Netdata" -sidebar_label: "Monitor a Hadoop cluster with Netdata" -custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/monitor-hadoop-cluster.md -learn_status: "Published" -learn_topic_type: "Tasks" -learn_rel_path: "Miscellaneous" ---> - # Monitor a Hadoop cluster with Netdata Hadoop is an [Apache project](https://hadoop.apache.org/) is a framework for processing large sets of data across a @@ -27,8 +18,8 @@ alternative, like the guide available from For more specifics on the collection modules used in this guide, read the respective pages in our documentation: -- [HDFS](/src/go/plugin/go.d/modules/hdfs/README.md) -- [Zookeeper](/src/go/plugin/go.d/modules/zookeeper/README.md) +- [HDFS](/src/go/plugin/go.d/modules/hdfs/README.md) +- [Zookeeper](/src/go/plugin/go.d/modules/zookeeper/README.md) ## Set up your HDFS and Zookeeper installations @@ -164,7 +155,7 @@ jobs: address : 203.0.113.10:2182 ``` -Finally, [restart Netdata](/packaging/installer/README.md#maintaining-a-netdata-agent-installation). +Finally, [restart Netdata](/docs/netdata-agent/start-stop-restart.md). ```sh sudo systemctl restart netdata @@ -178,7 +169,7 @@ showing real-time metrics for both in your Netdata dashboard. ๐ The Netdata community helped us create sane defaults for alerts related to both HDFS and Zookeeper. You may want to investigate these to ensure they work well with your Hadoop implementation. -- [HDFS alerts](https://raw.githubusercontent.com/netdata/netdata/master/src/health/health.d/hdfs.conf) +- [HDFS alerts](https://raw.githubusercontent.com/netdata/netdata/master/src/health/health.d/hdfs.conf) You can also access/edit these files directly with `edit-config`: @@ -187,5 +178,4 @@ sudo /etc/netdata/edit-config health.d/hdfs.conf sudo /etc/netdata/edit-config health.d/zookeeper.conf ``` -For more information about editing the defaults or writing new alert entities, see our -[health monitoring documentation](/src/health/README.md). +For more information about editing the defaults or writing new alert entities, see our [health monitoring documentation](/src/health/README.md). diff --git a/docs/developer-and-contributor-corner/pi-hole-raspberry-pi.md b/docs/developer-and-contributor-corner/pi-hole-raspberry-pi.txt index df6bb080..e150cebd 100644 --- a/docs/developer-and-contributor-corner/pi-hole-raspberry-pi.md +++ b/docs/developer-and-contributor-corner/pi-hole-raspberry-pi.txt @@ -100,26 +100,6 @@ part of your system might affect another.  -### Enable temperature sensor monitoring - -You need to manually enable Netdata's built-in [temperature sensor -collector](/src/collectors/charts.d.plugin/sensors/README.md) to start collecting metrics. - -> Netdata uses a few plugins to manage its [collectors](/src/collectors/REFERENCE.md), each using a different language: Go, -> Python, Node.js, and Bash. While our Go collectors are undergoing the most active development, we still support the -> other languages. In this case, you need to enable a temperature sensor collector that's written in Bash. - -First, open the `charts.d.conf` file for editing. You should always use the `edit-config` script to edit Netdata's -configuration files, as it ensures your settings persist across updates to the Netdata Agent. - -```bash -cd /etc/netdata -sudo ./edit-config charts.d.conf -``` - -Uncomment the `sensors=force` line and save the file. Restart Netdata with `sudo systemctl restart netdata` to enable -Raspberry Pi temperature sensor monitoring. - ### Storing historical metrics on your Raspberry Pi By default, Netdata allocates 256 MiB in disk space to store historical metrics inside the [database diff --git a/docs/developer-and-contributor-corner/process.md b/docs/developer-and-contributor-corner/process.txt index 2902a24f..dbb36c55 100644 --- a/docs/developer-and-contributor-corner/process.md +++ b/docs/developer-and-contributor-corner/process.txt @@ -142,7 +142,7 @@ Inside the file are lists of process names, oftentimes using wildcards (`*`), th groups together. For example, the Netdata Agent looks for processes starting with `mysqld`, `mariad`, `postgres`, and others, and groups them into `sql`. That makes sense, since all these processes are for SQL databases. -```conf +```text sql: mysqld* mariad* postgres* postmaster* oracle_* ora_* sqlservr ``` @@ -170,7 +170,7 @@ the [section above](#configure-the-netdata-agent-to-recognize-a-specific-process the `database servers` section. Create new groups for MySQL and PostgreSQL, and move their process queries into the unique groups. -```conf +```text # ----------------------------------------------------------------------------- # database servers @@ -180,7 +180,7 @@ sql: mariad* postmaster* oracle_* ora_* sqlservr ``` Restart Netdata with `sudo systemctl restart netdata`, or -the [appropriate method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, to start collecting utilization metrics +the appropriate method for your system, to start collecting utilization metrics from your application. Time to [visualize your process metrics](#visualize-process-metrics). ### Custom applications @@ -194,7 +194,7 @@ to `# NETDATA processes accounting`. Above that, paste in the following text, which creates a new `custom-app` group with the `custom-app` process. Replace `custom-app` with the name of your application's Linux process. `apps_groups.conf` should now look like this: -```conf +```text ... # ----------------------------------------------------------------------------- # Custom applications to monitor with apps.plugin and ebpf.plugin @@ -207,7 +207,7 @@ custom-app: custom-app ``` Restart Netdata with `sudo systemctl restart netdata`, or -the [appropriate method](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) for your system, to start collecting utilization metrics +the appropriate method for your system, to start collecting utilization metrics from your application. ## Visualize process metrics diff --git a/docs/developer-and-contributor-corner/python-collector.md b/docs/developer-and-contributor-corner/python-collector.txt index 0b7aa96a..f846b347 100644 --- a/docs/developer-and-contributor-corner/python-collector.md +++ b/docs/developer-and-contributor-corner/python-collector.txt @@ -1,8 +1,8 @@ # Develop a custom data collector in Python -The Netdata Agent uses [data collectors](/src/collectors/README.md) to -fetch metrics from hundreds of system, container, and service endpoints. While the Netdata team and community has built -[powerful collectors](/src/collectors/COLLECTORS.md) for most system, container, +The Netdata Agent uses [data collectors](/src/collectors/README.md) to +fetch metrics from hundreds of system, container, and service endpoints. While the Netdata team and community has built +[powerful collectors](/src/collectors/COLLECTORS.md) for most system, container, and service/application endpoints, some custom applications can't be monitored by default. In this tutorial, you'll learn how to leverage the [Python programming language](https://www.python.org/) to build a @@ -17,16 +17,16 @@ execute. Python plugins require Python on the machine to be executed. Netdata us production-grade collectors. We generally do not accept contributions of Python modules to the GitHub project netdata/netdata. If you write a Python collector and -want to make it available for other users, you should create the pull request in https://github.com/netdata/community. +want to make it available for other users, you should create the pull request in <https://github.com/netdata/community>. ## What you need to get started - - A physical or virtual Linux system, which we'll call a _node_. - - A working [installation of Netdata](/packaging/installer/README.md) monitoring agent. +- A physical or virtual Linux system, which we'll call a _node_. +- A working [installation of Netdata](/packaging/installer/README.md) monitoring agent. ### Quick start -For a quick start, you can look at the +For a quick start, you can look at the [example plugin](https://raw.githubusercontent.com/netdata/netdata/master/src/collectors/python.d.plugin/example/example.chart.py). **Note**: If you are working 'locally' on a new collector and would like to run it in an already installed and running @@ -72,21 +72,21 @@ The basic elements of a Netdata collector are: - `data{}`: A dictionary containing the values to be displayed. - `get_data()`: The basic function of the plugin which will return to Netdata the correct values. -**Note**: All names are better explained in the -[External Plugins Documentation](/src/collectors/plugins.d/README.md). +**Note**: All names are better explained in the +[External Plugins Documentation](/src/plugins.d/README.md). Parameters like `priority` and `update_every` mentioned in that documentation are handled by the `python.d.plugin`, -not by each collection module. +not by each collection module. Let's walk through these jobs and elements as independent elements first, then apply them to example Python code. ### Determine how to gather metrics data -Netdata can collect data from any program that can print to stdout. Common input sources for collectors can be logfiles, +Netdata can collect data from any program that can print to stdout. Common input sources for collectors can be log files, HTTP requests, executables, and more. While this tutorial will offer some example inputs, your custom application will have different inputs and metrics. A great deal of the work in developing a Netdata collector is investigating the target application and understanding -which metrics it exposes and how to +which metrics it exposes and how to ### Create charts @@ -117,13 +117,14 @@ context, charttype]`, where: that is `A.B`, with `A` being the name of the collector, and `B` being the name of the specific metric. - `charttype`: Either `line`, `area`, or `stacked`. If null line is the default value. -You can read more about `family` and `context` in the [web dashboard](/src/web/README.md#families) doc. +You can read more about `family` and `context` in the [Netdata Charts](/docs/dashboards-and-charts/netdata-charts.md) doc. Once the chart has been defined, you should define the dimensions of the chart. Dimensions are basically the metrics to be represented in this chart and each chart can have more than one dimension. In order to define the dimensions, the "lines" list should be filled in with the required dimensions. Each dimension is a list: `dimension: [id, name, algorithm, multiplier, divisor]` + - `id` : The id of the dimension. Mandatory unique field (string) required in order to set a value. - `name`: The name to be presented in the chart. If null id will be used. - `algorithm`: Can be absolute or incremental. If null absolute is used. Incremental shows the difference from the @@ -145,6 +146,7 @@ Once you have process your data and get the required values, you need to assign This is done using the `data` dictionary, which is in the form: `"data": {dimension_id: value }`, where: + - `dimension_id`: The id of a defined dimension in a created chart. - `value`: The numerical value to associate with this dimension. @@ -153,6 +155,7 @@ This is done using the `data` dictionary, which is in the form: Next, set the order of chart appearance with the `ORDER` list, which is in the form: `"ORDER": [chart_name_1,chart_name_2, โฆ., chart_name_X]`, where: + - `chart_name_x`: is the chart name to be shown in X order. ### Give the charts data to Netdata for visualization @@ -160,19 +163,19 @@ Next, set the order of chart appearance with the `ORDER` list, which is in the f Our plugin should just rerun the data dictionary. If everything is set correctly the charts should be updated with the correct values. -## Framework classes +## Framework classes Every module needs to implement its own `Service` class. This class should inherit from one of the framework classes: -- `SimpleService` -- `UrlService` -- `SocketService` -- `LogService` -- `ExecutableService` +- `SimpleService` +- `UrlService` +- `SocketService` +- `LogService` +- `ExecutableService` -Also it needs to invoke the parent class constructor in a specific way as well as assign global variables to class variables. +Also it needs to invoke the parent class constructor in a specific way as well as assign global variables to class variables. -For example, the snippet below is from the +For example, the snippet below is from the [RabbitMQ collector](https://github.com/netdata/netdata/blob/91f3268e9615edd393bd43de4ad8068111024cc9/collectors/python.d.plugin/rabbitmq/rabbitmq.chart.py#L273). This collector uses an HTTP endpoint and uses the `UrlService` framework class, which only needs to define an HTTP endpoint for data collection. @@ -229,10 +232,11 @@ CHARTS = { ## Parse the data to extract or create the actual data to be represented -Every collector must implement `_get_data`. This method should grab raw data from `_get_raw_data`, +Every collector must implement `_get_data`. This method should grab raw data from `_get_raw_data`, parse it, and return a dictionary where keys are unique dimension names, or `None` if no data is collected. For example: + ```py def _get_data(self): try: @@ -374,7 +378,7 @@ class Service(SimpleService): To enrich the example, add another chart the collector which to present the humidity metric. -Add a new entry in the `CHARTS` dictionary with the definition for the new chart. +Add a new entry in the `CHARTS` dictionary with the definition for the new chart. ```python CHARTS = { @@ -410,7 +414,7 @@ ORDER = [ ] ``` -[Restart Netdata](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) with `sudo systemctl restart netdata` to see the new humidity +[Restart Netdata](/docs/netdata-agent/start-stop-restart.md) to see the new humidity chart:  @@ -467,8 +471,7 @@ ORDER = [ ] ``` -[Restart Netdata](/packaging/installer/README.md#maintaining-a-netdata-agent-installation) with `sudo systemctl restart netdata` to see the new -min/max/average temperature chart with multiple dimensions: +[Restart Netdata](/docs/netdata-agent/start-stop-restart.md) to see the new min/max/average temperature chart with multiple dimensions:  @@ -485,7 +488,7 @@ configuration in [YAML](https://www.tutorialspoint.com/yaml/yaml_basics.htm) for serially and will stop at the first job that returns data. If multiple jobs have the same name, only one of them can run. This enables you to define different "ways" to fetch data from a particular data source so that the collector has more chances to work out-of-the-box. For example, if the data source supports both `HTTP` and `linux socket`, you can - define 2 jobs named `local`, with each using a different method. + define 2 jobs named `local`, with each using a different method. - Check the `example` collector configuration file on [GitHub](https://github.com/netdata/netdata/blob/master/src/collectors/python.d.plugin/example/example.conf) to get a sense of the structure. @@ -521,26 +524,26 @@ variables and inform the user about the defaults. For example, take a look at th [GitHub](https://github.com/netdata/netdata/blob/master/src/collectors/python.d.plugin/example/example.conf). You can read more about the configuration file on the [`python.d.plugin` -documentation](/src/collectors/python.d.plugin/README.md). +documentation](/src/collectors/python.d.plugin/README.md). -You can find the source code for the above examples on [GitHub](https://github.com/papajohn-uop/netdata). +You can find the source code for the above examples on [GitHub](https://github.com/papajohn-uop/netdata). ## Pull Request Checklist for Python Plugins -Pull requests should be created in https://github.com/netdata/community. +Pull requests should be created in <https://github.com/netdata/community>. This is a generic checklist for submitting a new Python plugin for Netdata. It is by no means comprehensive. At minimum, to be buildable and testable, the PR needs to include: -- The module itself, following proper naming conventions: `collectors/python.d.plugin/<module_dir>/<module_name>.chart.py` -- A README.md file for the plugin under `collectors/python.d.plugin/<module_dir>`. -- The configuration file for the module: `collectors/python.d.plugin/<module_dir>/<module_name>.conf`. Python config files are in YAML format, and should include comments describing what options are present. The instructions are also needed in the configuration section of the README.md -- A basic configuration for the plugin in the appropriate global config file: `collectors/python.d.plugin/python.d.conf`, which is also in YAML format. Either add a line that reads `# <module_name>: yes` if the module is to be enabled by default, or one that reads `<module_name>: no` if it is to be disabled by default. -- A makefile for the plugin at `collectors/python.d.plugin/<module_dir>/Makefile.inc`. Check an existing plugin for what this should look like. -- A line in `collectors/python.d.plugin/Makefile.am` including the above-mentioned makefile. Place it with the other plugin includes (please keep the includes sorted alphabetically). -- Optionally, chart information in `src/web/gui/dashboard_info.js`. This generally involves specifying a name and icon for the section, and may include descriptions for the section or individual charts. -- Optionally, some default alert configurations for your collector in `health/health.d/<module_name>.conf` and a line adding `<module_name>.conf` in `health/Makefile.am`. +- The module itself, following proper naming conventions: `collectors/python.d.plugin/<module_dir>/<module_name>.chart.py` +- A README.md file for the plugin under `collectors/python.d.plugin/<module_dir>`. +- The configuration file for the module: `collectors/python.d.plugin/<module_dir>/<module_name>.conf`. Python config files are in YAML format, and should include comments describing what options are present. The instructions are also needed in the configuration section of the README.md +- A basic configuration for the plugin in the appropriate global config file: `collectors/python.d.plugin/python.d.conf`, which is also in YAML format. Either add a line that reads `# <module_name>: yes` if the module is to be enabled by default, or one that reads `<module_name>: no` if it is to be disabled by default. +- A makefile for the plugin at `collectors/python.d.plugin/<module_dir>/Makefile.inc`. Check an existing plugin for what this should look like. +- A line in `collectors/python.d.plugin/Makefile.am` including the above-mentioned makefile. Place it with the other plugin includes (please keep the includes sorted alphabetically). +- Optionally, chart information in `src/web/gui/dashboard_info.js`. This generally involves specifying a name and icon for the section, and may include descriptions for the section or individual charts. +- Optionally, some default alert configurations for your collector in `health/health.d/<module_name>.conf` and a line adding `<module_name>.conf` in `health/Makefile.am`. ## Framework class reference @@ -567,11 +570,11 @@ Example: `ceph`, `sensors` It is the lowest-level class which implements most of module logic, like: -- threading -- handling run times -- chart formatting -- logging -- chart creation and updating +- threading +- handling run times +- chart formatting +- logging +- chart creation and updating ### `LogService` @@ -589,11 +592,11 @@ Variable from config file: `command`. This allows to execute a shell command in a secure way. It will check for invalid characters in `command` variable and won't proceed if there is one of: -- '&' -- '|' -- ';' -- '>' -- '\<' +- '&' +- '|' +- ';' +- '>' +- '\<' For additional security it uses python `subprocess.Popen` (without `shell=True` option) to execute command. Command can be specified with absolute or relative name. When using relative name, it will try to find `command` in `PATH` environment variable as well as in `/sbin` and `/usr/sbin`. diff --git a/docs/developer-and-contributor-corner/raspberry-pi-anomaly-detection.md b/docs/developer-and-contributor-corner/raspberry-pi-anomaly-detection.txt index 41cf007e..9bdacf27 100644 --- a/docs/developer-and-contributor-corner/raspberry-pi-anomaly-detection.md +++ b/docs/developer-and-contributor-corner/raspberry-pi-anomaly-detection.txt @@ -23,11 +23,11 @@ Read on to learn all the steps and enable unsupervised anomaly detection on your First make sure Netdata is using Python 3 when it runs Python-based data collectors. -Next, open `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-netdataconf) +Next, open `netdata.conf` using [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) from within the [Netdata config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory). Scroll down to the `[plugin:python.d]` section to pass in the `-ppython3` command option. -```conf +```text [plugin:python.d] # update every = 1 command options = -ppython3 @@ -53,7 +53,7 @@ LLVM_CONFIG=llvm-config-9 pip3 install --user llvmlite numpy==1.20.1 netdata-pan ## Enable the anomalies collector -Now you're ready to enable the collector and [restart Netdata](/packaging/installer/README.md#maintaining-a-netdata-agent-installation). +Now you're ready to enable the collector and restart Netdata. ```bash sudo ./edit-config python.d.conf diff --git a/docs/developer-and-contributor-corner/running-through-cf-tunnels.md b/docs/developer-and-contributor-corner/running-through-cf-tunnels.md index 3179d580..588740bc 100644 --- a/docs/developer-and-contributor-corner/running-through-cf-tunnels.md +++ b/docs/developer-and-contributor-corner/running-through-cf-tunnels.md @@ -102,7 +102,7 @@ You can edit the configuration file using the `edit-config` script from the Netd destination = tcp:127.0.0.1:19999 ``` -[Restart the Agents](/packaging/installer/README.md#maintaining-a-netdata-agent-installation), and you are done! +[Restart the Agents](/docs/netdata-agent/start-stop-restart.md), and you are done! You should now be able to have a Local Dashboard that gets its metrics from Child instances, running through Cloudflare tunnels. diff --git a/docs/developer-and-contributor-corner/style-guide.md b/docs/developer-and-contributor-corner/style-guide.md index 94656bd7..b64a9df0 100644 --- a/docs/developer-and-contributor-corner/style-guide.md +++ b/docs/developer-and-contributor-corner/style-guide.md @@ -2,7 +2,7 @@ The _Netdata style guide_ establishes editorial guidelines for any writing produced by the Netdata team or the Netdata community, including documentation, articles, in-product UX copy, and more. -> ### Note +> **Note** > This document is meant to be accompanied by the [Documentation Guidelines](/docs/guidelines.md). If you want to contribute to Netdata's documentation, please read it too. Both internal Netdata teams and external contributors to any of Netdata's open-source projects should reference and adhere to this style guide as much as possible. @@ -30,7 +30,6 @@ you're around. In writing, you reflect tone in your word choice, punctuation, se The same idea about voice and tone applies to organizations, too. Our voice shouldn't change much between two pieces of content, no matter who wrote each, but the tone might be quite different based on who we think is reading. - ### Voice Netdata's voice is authentic, passionate, playful, and respectful. @@ -63,7 +62,7 @@ the [language, grammar, and mechanics](#language-grammar-and-mechanics) section - Would this language make sense to someone who doesn't work here? - Could someone quickly scan this document and understand the material? -- Create an information hierarchy with key information presented first and clearly called out to improve scannability. +- Create an information hierarchy with key information presented first and clearly called out to improve clarity and readability. - Avoid directional language like "sidebar on the right of the page" or "header at the top of the page" since presentation elements may adapt for devices. - Use descriptive links rather than "click here" or "learn more". @@ -236,8 +235,8 @@ must reflect the _current state of [production](https://app.netdata.cloud). Every link should clearly state its destination. Don't use words like "here" to describe where a link will take your reader. -| | | -|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| | | +|-----------------|-------------------------------------------------------------------------------------------| | Not recommended | To install Netdata, click [here](/packaging/installer/README.md). | | **Recommended** | To install Netdata, read the [installation instructions](/packaging/installer/README.md). | @@ -300,9 +299,9 @@ universal. Don't include full paths, beginning from the system's root (`/`), as these might not work on certain systems. -| | | -|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Not recommended | Use `edit-config` to edit Netdata's configuration: `sudo /etc/netdata/edit-config netdata.conf`. | +| | | +|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Not recommended | Use `edit-config` to edit Netdata's configuration: `sudo /etc/netdata/edit-config netdata.conf`. | | **Recommended** | Use `edit-config` to edit Netdata's configuration by first navigating to your [Netdata config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory), which is typically at `/etc/netdata`, then running `sudo edit-config netdata.conf`. | ### `sudo` @@ -394,27 +393,26 @@ the [Docusaurus documentation](https://v2.docusaurus.io/docs/markdown-features#c Notes inside files should render properly both in GitHub and in Learn, to do that, it is best to use the format listed below: -``` -> ### Note +```md +> **Note** > This is an info or a note block. -> ### Tip, Best Practice +> **Tip, Best Practice** > This is a tip or a best practice block. -> ### Warning, Caution +> **Warning, Caution** > This is a warning or a caution block. ``` Which renders into: - -> ### Note +> **Note** > This is an info or a note block. -> ### Tip, Best Practice +> **Tip, Best Practice** > This is a tip or a best practice block. -> ### Warning, Caution +> **Warning, Caution** > This is a warning or a caution block. ### Tabs @@ -450,21 +448,21 @@ The following tables describe the standard spelling, capitalization, and usage o | Term | Definition | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **claimed node** | A node that you've proved ownership of by completing the [connecting to Cloud process](/src/claim/README.md). The claimed node will then appear in your Space and any Rooms you added it to. | +| **Connected Node** | A node that you've proved ownership of by completing the [connecting to Cloud process](/src/claim/README.md). The claimed node will then appear in your Space and any Rooms you added it to. | | **Netdata** | The company behind the open-source Netdata Agent and the Netdata Cloud web application. Never use _netdata_ or _NetData_. <br /><br />In general, focus on the user's goals, actions, and solutions rather than what the company provides. For example, write _Learn more about enabling alert notifications on your preferred platforms_ instead of _Netdata sends alert notifications to your preferred platforms_. | | **Netdata Agent** | The free and open source [monitoring agent](https://github.com/netdata/netdata) that you can install on all of your distributed systems, whether they're physical, virtual, containerized, ephemeral, and more. The Agent monitors systems running Linux, Docker, Kubernetes, macOS, FreeBSD, and more, and collects metrics from hundreds of popular services and applications. | | **Netdata Cloud** | The web application hosted at [https://app.netdata.cloud](https://app.netdata.cloud) that helps you monitor an entire infrastructure of distributed systems in real time. <br /><br />Never use _Cloud_ without the preceding _Netdata_ to avoid ambiguity. | | **Netdata community forum** | The Discourse-powered forum for feature requests, Netdata Cloud technical support, and conversations about Netdata's monitoring and troubleshooting products. | -| **node** | A system on which the Netdata Agent is installed. The system can be physical, virtual, in a Docker container, and more. Depending on your infrastructure, you may have one, dozens, or hundreds of nodes. Some nodes are _ephemeral_, in that they're created/destroyed automatically by an orchestrator service. | +| **Node** | A system on which the Netdata Agent is installed. The system can be physical, virtual, in a Docker container, and more. Depending on your infrastructure, you may have one, dozens, or hundreds of nodes. Some nodes are _ephemeral_, in that they're created/destroyed automatically by an orchestrator service. | | **Space** | The highest level container within Netdata Cloud for a user to organize their team members and nodes within their infrastructure. A Space likely represents an entire organization or a large team. <br /><br />_Space_ is always capitalized. | -| **unreachable node** | A connected node with a disrupted [Agent-Cloud link](/src/aclk/README.md). Unreachable could mean the node no longer exists or is experiencing network connectivity issues with Cloud. | -| **visited node** | A node which has had its Agent dashboard directly visited by a user. A list of these is maintained on a per-user basis. | -| **Room** | A smaller grouping of nodes where users can view key metrics in real-time and monitor the health of many nodes with their alert status. Rooms can be used to organize nodes in any way that makes sense for your infrastructure, such as by a service, purpose, physical location, and more. <br /><br />_Room_ is always capitalized. | +| **Unreachable node** | A connected node with a disrupted [Agent-Cloud link](/src/aclk/README.md). Unreachable could mean the node no longer exists or is experiencing network connectivity issues with Cloud. | +| **Visited Node** | A node which has had its Agent dashboard directly visited by a user. A list of these is maintained on a per-user basis. | +| **Room** | A smaller grouping of nodes where users can view key metrics in real-time and monitor the health of many nodes with their alert status. Rooms can be used to organize nodes in any way that makes sense for your infrastructure, such as by a service, purpose, physical location, and more. <br /><br />_Room_ is always capitalized. | ### Other technical terms | Term | Definition | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **filesystem** | Use instead of _file system_. | -| **preconfigured** | The concept that many of Netdata's features come with sane defaults that users don't need to configure to find immediate value. | +| **pre-configured** | The concept that many of Netdata's features come with sane defaults that users don't need to configure to find immediate value. | | **real time**/**real-time** | Use _real time_ as a noun phrase, most often with _in_: _Netdata collects metrics in real time_. Use _real-time_ as an adjective: _Netdata collects real-time metrics from hundreds of supported applications and services. | |