diff options
author | Chris Akritidis <43294513+cakrit@users.noreply.github.com> | 2018-11-12 21:34:59 +0100 |
---|---|---|
committer | Costa Tsaousis <costa@tsaousis.gr> | 2018-11-12 22:34:59 +0200 |
commit | 3aae8f6c2ceea7f74cde61a2044aa50c5f252fae (patch) | |
tree | 781412f323c0183c520e4ff1c9fdac53a900b463 | |
parent | a29b433526f56fe983d88dc4e86585bad65916c4 (diff) |
Htmldoc (#4607)
* First html documentation debug set
* Test 2
* Relative path changed
* Updated comments
* Cleanup, installation draft added
* fixes
* test
* test
* test
* First html documentation debug set
* Test 2
* Relative path changed
* Updated comments
* Cleanup, installation draft added
* fixes
* test
* test
* test
* First set of major cleanup/deduplication
* 2nd major cleanup
* update getting started structure
* Cleanup in using netdata
* Final cleanup/deduplication
* Added initial CONTRIBUTING.md, updated some info related to contributing on the orchestrators
* Removed Why-Netdata (included in new README in master), added link to CONTRIBUTING.md
* First html documentation debug set
* Updated Makefile.am to ignore the new md and htmldoc generation files
* Removing files from rebase
* First html documentation debug set
* Test 2
* Relative path changed
* Updated comments
* Cleanup, installation draft added
* fixes
* test
* test
* test
* First html documentation debug set
* Test 2
* Relative path changed
* Updated comments
* Cleanup, installation draft added
* test
* test
* First set of major cleanup/deduplication
* 2nd major cleanup
* update getting started structure
* Cleanup in using netdata
* Final cleanup/deduplication
* Added initial CONTRIBUTING.md, updated some info related to contributing on the orchestrators
* Removed Why-Netdata (included in new README in master), added link to CONTRIBUTING.md
* First html documentation debug set
* Updated Makefile.am to ignore the new md and htmldoc generation files
* Removing files from rebase
* Fixed Makefile.am
* Same line header and badges
* Fixed broken link
* CPU monitoring is in apps plugin
* Removed obsolete files
* Remove obsolete files
* - Make the Health API part of health/README.md new file web/api/health/README.md
- Make installer/LAUNCH.md part of deamon/README.md
- Move installer/MAINTAINERS.md to packaging/maintainers/README.md
- Move installer/DOCKER.md to docker/README.md
- Move system/README.md to daemon/config/README.md
- Move web/CUSTOM-DASHBOARDS.md to web/gui/custom/README.md
- Move web/CONFLUENCE-DASHBOARDS.md to web/gui/confluence/README.md
* Resolve codacy issue $(..) syntax instead of `..`
* Fix following warnings and add svgs to the data_structures/README.md
- CHANGELOG.md
- CODE_OF_CONDUCT.md
- CONTRIBUTORS.md
- REDISTRIBUTED.md
- diagrams/data_structures/README.md
- docker/README.md
WARNING - Documentation file 'README.md' contains a link to 'collectors/plugins.d' which does not exist in the documentation directory.
WARNING - Documentation file 'README.md' contains a link to 'collectors/statsd.plugin' which does not exist in the documentation directory.
WARNING - Documentation file 'CONTRIBUTING.md' contains a link to 'web/CUSTOM-DASHBOARDS.md' which does not exist in the documentation directory.
WARNING - Documentation file 'CONTRIBUTING.md' contains a link to 'web/CONFLUENCE-DASHBOARDS.md' which does not exist in the documentation directory.
* Wrong urls in data_structures/README.md svgs
* Fix svg URLs number 2
* Modify the first line of the main README.md, to enable proper static html generation. Executed after copying the file to htmldoc/src
* Added back Why Netdata
* Fixed link to registry in Why-Netdata.md
* Added Why-Netdata to buildyaml and to Makefile.am
* Replaced http links causing mixed content warnings
* Made buildhtml ignore the directory node_modules created by Netlify
* Corrected CONTRIBUTING.MD to CONTRIBUTING.md
71 files changed, 5441 insertions, 312 deletions
diff --git a/.gitignore b/.gitignore index c3f327b37a..c64d759547 100644 --- a/.gitignore +++ b/.gitignore @@ -143,3 +143,8 @@ sitespeed-result/ # tests and temp files python.d/python-modules-installer.sh + +# documentation generated files +htmldoc/src +htmldoc/build +htmldoc/mkdocs.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..7b05bab2ea --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,92 @@ +# Contributing + +Thank you for considering contributing to Netdata. + +We love to receive contributions. Maintaining a platform for monitoring everything imaginable requires a broad understanding of a plethora of technologies, systems and applications. We rely on community contributions and user feedback to continue providing the best monitoring solution out there. + +There are many ways to contribute, with varying requirements of skills: + +## All NetData Users + +### Give Netdata a GitHub star + +This is the minimum open-source users should contribute back to the projects they use. Github stars help the project gain visibility, stand out. So, if you use Netdata, consider pressing that button. **It really matters**. + +### Spread the word + +Community growth allows the project to attract new talent willing to contribute. This talent is then developing new features and improves the project. These new features and improvements attract more users and so on. It is a loop. So, post about netdata, present it to local meetups you attend, let your online social network or twitter, facebook, reddit, etc. know you are using it. **The more people involved, the faster the project evolves**. + +### Provide feedback + +Is there anything that bothers you about netdata? Did you experience an issue while installing it or using it? Would you like to see it evolve to you need? Let us know. [Open a github issue](https://github.com/netdata/netdata/issues) to discuss it. Feedback is very important for open-source projects. We can't commit we will do everything, but your feedback influences our road-map significantly. **We rely on your feedback to make Netdata better**. + +#### Help the developers understand what they have to do + +NetData is all about simplicity and meaningful presentation. It's impossible for a handful of people to know which metrics really matter when monitoring a particular software or hardware component you are interested in. Be specific about what should be collected, how the information should be presented in the dashboard and which alarms make sense in most situations. + +## Experienced Users + +### Help other users + +As the project grows, an increasing share of our time is spent on supporting this community of users in terms of answering questions, of helping users understand how netdata works and find their way with it. Helping other users is crucial. It allows the developers and maintainers of the project to focus on improving it. + +### Improve documentation + +Most of our documentation is in markdown (.md) files inside the netdata GitHub project. What remains in our Wiki will soon be moved in there as well. Don't be afraid to edit any of these documents and submit a GitHub Pull Request with your corrections/additions. + + +## Developers + +We expect most contributions to be for new data collection plugins. You can read about how external plugins work [here](collectors/plugins.d/). Additional instructions are available for [Node.js plugins](collectors/node.d/) and [Python plugis](collectors/python.d/). + +Of course we appreciate contributions for any other part of the NetData agent, including the [deamon](deamon/), [backends for long term archiving](backends/), innovative ways of using the [REST API](web/api) to create cool [Custom Dashboards](web/gui/custom/) or to include NetData charts in other applications, similarly to what can be done with [Confluence](web/gui/confluence/). + + +### Contributions Ground Rules + +#### Code of Conduct and CLA + +We expect all contributors to abide by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). For a pull request to be accepted, you will also need to accept the [netdata contributors license agreement](CONTRIBUTORS.md), as part of the PR process. + +#### Performance and efficiency + +Everything on Netdata is about efficiency. We need netdata to always be the most lightweight monitoring solution available. We will reject to merge PRs that are not optimal in resource utilization and efficiency. + +Of course there are cases that such technical excellence is either not reasonable or not feasible. In these cases, we may require the feature or code submitted to be by disabled by default. + +#### Meaningful metrics + +Unlike other monitoring solutions, Netdata requires all metrics collected to have some structure attached to them. So, Netdata metrics have a name, units, belong to a chart that has a title, a family, a context, belong to an application, etc. + +This structure is what makes netdata different. Most other monitoring solution collect bulk metrics in terms of name-value pairs and then expect their users to give meaning to these metrics during visualization. This does not work. It is neither practical nor reasonable to give to someone 2000 metrics and let him/her visualize them in a meaningful way. + +So, netdata requires all metrics to have a meaning at the time they are collected. We will reject to merge PRs that loosely collect just a "bunch of metrics", but we are very keen to help you fix this. + +#### Automated Testing + +Netdata is a very large application to have automated testing end-to-end. But automated testing is required for crucial functions of it. + +Generally, all pull requests should be coupled with automated testing scenarios. However since we do not currently have a framework in place for testing everything little bit of it, we currently require automated tests for parts of Netdata that seem too risky to be changed without automated testing. + +Of course, manual testing is always required. + +#### Netdata is a distributed application + +Netdata is a distributed monitoring application. A few basic features can become quite complicated for such applications. We may reject features that alter or influence the nature of netdata, though we usually discuss the requirements with contributors and help them adapt their code to be better suited for Netdata. + +#### Operating systems supported + +Netdata should be running everywhere, on every production system out there. + +Although we focus on **supported operating systems**, we still want Netdata to run even on non-supported systems. This, of course, may require some more manual work from the users (to prepare their environment, or enable certain flags, etc). + +If your contributions limit the number of operating systems supported we will request from you to improve it. + +#### Documentation + +Your contributions should be bundled with related documentation to help users understand how to use the features you introduce. + +#### Maintenance + +When you contribute code to Netdata, you are automatically accepting that you will be responsible for maintaining that code in the future. So, if users need help, or report bugs, we will invite you to the related github issues to help them or fix the issues or bugs of your contributions. + diff --git a/Makefile.am b/Makefile.am index ddb9a699a1..c90db5ca3c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -44,6 +44,7 @@ EXTRA_DIST = \ CODE_OF_CONDUCT.md \ LICENSE \ REDISTRIBUTED.md \ + CONTRIBUTING.md \ $(NULL) SUBDIRS = \ @@ -61,6 +62,27 @@ dist_noinst_DATA= \ netdata.cppcheck \ netdata.spec \ package.json \ + doc/Add-more-charts-to-netdata.md \ + doc/Demo-Sites.md \ + doc/Donations-netdata-has-received.md \ + doc/Netdata-Security-and-Disclosure-Information.md \ + doc/Performance.md \ + doc/Running-behind-apache.md \ + doc/Running-behind-caddy.md \ + doc/Running-behind-lighttpd.md \ + doc/Running-behind-nginx.md \ + doc/Third-Party-Plugins.md \ + doc/a-github-star-is-important.md \ + doc/high-performance-netdata.md \ + doc/netdata-for-IoT.md \ + doc/netdata-security.md \ + doc/Why-Netdata.md \ + htmldoc/themes/material/partials/footer.html \ + installer/README.md \ + installer/UNINSTALL.md \ + installer/UPDATE.md \ + requirements.txt \ + runtime.txt \ $(NULL) # until integrated within build @@ -71,6 +93,8 @@ dist_noinst_SCRIPTS= \ kickstart-static64.sh \ netdata-installer.sh \ installer/functions.sh \ + htmldoc/buildhtml.sh \ + htmldoc/buildyaml.sh \ $(NULL) # ----------------------------------------------------------------------------- @@ -1,4 +1,4 @@ -# netdata [![Build Status](https://travis-ci.com/netdata/netdata.svg?branch=master)](https://travis-ci.com/netdata/netdata) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2231/badge)](https://bestpractices.coreinfrastructure.org/projects/2231) [![License: GPL v3+](https://img.shields.io/badge/License-GPL%20v3%2B-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![analytics](http://www.google-analytics.com/collect?v=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Freadme&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]() +# netdata [![Build Status](https://travis-ci.com/netdata/netdata.svg?branch=master)](https://travis-ci.com/netdata/netdata) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2231/badge)](https://bestpractices.coreinfrastructure.org/projects/2231) [![License: GPL v3+](https://img.shields.io/badge/License-GPL%20v3%2B-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![analytics](https://www.google-analytics.com/collect?v=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Freadme&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)]() [![Code Climate](https://codeclimate.com/github/netdata/netdata/badges/gpa.svg)](https://codeclimate.com/github/netdata/netdata) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/a994873f30d045b9b4b83606c3eb3498)](https://www.codacy.com/app/netdata/netdata?utm_source=github.com&utm_medium=referral&utm_content=netdata/netdata&utm_campaign=Badge_Grade) [![LGTM C](https://img.shields.io/lgtm/grade/cpp/g/netdata/netdata.svg?logo=lgtm)](https://lgtm.com/projects/g/netdata/netdata/context:cpp) [![LGTM JS](https://img.shields.io/lgtm/grade/javascript/g/netdata/netdata.svg?logo=lgtm)](https://lgtm.com/projects/g/netdata/netdata/context:javascript) [![LGTM PYTHON](https://img.shields.io/lgtm/grade/python/g/netdata/netdata.svg?logo=lgtm)](https://lgtm.com/projects/g/netdata/netdata/context:python) @@ -52,7 +52,7 @@ The following animated image, shows the top part of a typical netdata dashboard. *A typical netdata dashboard, in 1:1 timing. Charts can be panned by dragging them, zoomed in/out with `SHIFT` + `mouse wheel`, an area can be selected for zoom-in with `SHIFT` + `mouse selection`. Netdata is highly interactive and **real-time**, optimized to get the work done!* -> *We have a few online demos to see it in action: [http://my-netdata.io](http://my-netdata.io)* +> *We have a few online demos to check: [https://my-netdata.io](https://my-netdata.io)* ## User base @@ -73,7 +73,7 @@ When you install multiple netdata, they are integrated into **one distributed ap [![User Base](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_entries&dimensions=persons&label=user%20base&units=null&value_color=blue&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) [![Monitored Servers](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_entries&dimensions=machines&label=servers%20monitored&units=null&value_color=orange&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) [![Sessions Served](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_sessions&label=sessions%20served&units=null&value_color=yellowgreen&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) -*in the last 24 hours:*<br/> [![New Users Today](http://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_entries&dimensions=persons&after=-86400&options=unaligned&group=incremental-sum&label=new%20users%20today&units=null&value_color=blue&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) [![New Machines Today](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_entries&dimensions=machines&group=incremental-sum&after=-86400&options=unaligned&label=servers%20added%20today&units=null&value_color=orange&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) [![Sessions Today](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_sessions&after=-86400&group=incremental-sum&options=unaligned&label=sessions%20served%20today&units=null&value_color=yellowgreen&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) +*in the last 24 hours:*<br/> [![New Users Today](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_entries&dimensions=persons&after=-86400&options=unaligned&group=incremental-sum&label=new%20users%20today&units=null&value_color=blue&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) [![New Machines Today](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_entries&dimensions=machines&group=incremental-sum&after=-86400&options=unaligned&label=servers%20added%20today&units=null&value_color=orange&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) [![Sessions Today](https://registry.my-netdata.io/api/v1/badge.svg?chart=netdata.registry_sessions&after=-86400&group=incremental-sum&options=unaligned&label=sessions%20served%20today&units=null&value_color=yellowgreen&precision=0&v42)](https://registry.my-netdata.io/#menu_netdata_submenu_registry) ## Quick Start @@ -86,7 +86,7 @@ bash # install netdata, directly from github sources bash <(curl -Ss https://my-netdata.io/kickstart.sh) ``` -![](http://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart&group=sum&after=-3600&label=last+hour&units=installations&value_color=orange&precision=0) ![](http://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart&group=sum&after=-86400&label=today&units=installations&precision=0) +![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart&group=sum&after=-3600&label=last+hour&units=installations&value_color=orange&precision=0) ![](https://registry.my-netdata.io/api/v1/badge.svg?chart=web_log_nginx.requests_per_url&options=unaligned&dimensions=kickstart&group=sum&after=-86400&label=today&units=installations&precision=0) The above command will: @@ -130,7 +130,6 @@ Netdata is **open-source**, **free**, super **fast**, very **easy**, completely It has been designed by **SysAdmins**, **DevOps** and **Developers** for troubleshooting performance problems, not just visualize metrics. - ## News `Nov 6th, 2018` - **[netdata v1.11.0 released!](https://github.com/netdata/netdata/releases)** @@ -256,13 +255,13 @@ To improve visual anomaly detection across charts, the user can highlight a time ## What does it monitor Netdata data collection is **extensible** - you can monitor anything you can get a metric for. -Its [Plugin API](collectors/plugins.d) supports all programing languages (anything can be a netdata plugin, BASH, python, perl, node.js, java, Go, ruby, etc). +Its [Plugin API](collectors/plugins.d/) supports all programing languages (anything can be a netdata plugin, BASH, python, perl, node.js, java, Go, ruby, etc). - For better performance, most system related plugins (cpu, memory, disks, filesystems, networking, etc) have been written in `C`. - For faster development and easier contributions, most application related plugins (databases, web servers, etc) have been written in `python`. #### APM (Application Performance Monitoring) -- **statsd** - [netdata is a fully featured statsd server](collectors/statsd.plugin). +- **statsd** - [netdata is a fully featured statsd server](collectors/statsd.plugin/). - **go_expvar** - collects metrics exposed by applications written in the Go programming language using the expvar package. - **Spring Boot** - monitors running Java Spring Boot applications that expose their metrics with the use of the Spring Boot Actuator included in Spring Boot library. diff --git a/back |