diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 000000000..c2c5e7f9a --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs"] + path = docs + url = git://github.com/BrightcoveOS/Diamond.wiki.git diff --git a/README.md b/README.md index f957ef195..974a51cd3 100644 --- a/README.md +++ b/README.md @@ -5,162 +5,8 @@ Diamond is a python daemon that collects system metrics and publishes them to Gr capable of collecting cpu, memory, network, i/o, load and disk metrics. Additionally, it features an API for implementing custom collectors for gathering metrics from almost any source. -Installation -===== - -** Installation/Building Dependencies ** - -- make -- rpm-build - -** Core Dependencies ** - -- CentOS or Ubuntu -- Python 2.4+ -- python-configobj - -** Unit Test Dependencies ** - -- Mock - http://www.voidspace.org.uk/python/mock/ - -** Collector Dependencies** - -*** MongoDBCollector *** - -- pymongo - -*** SNMPInterfaceCollector *** - -- pysnmp - -Usage -===== - -To install diamond: - - make install - -For testing, diamond can also be started directly without installing: - - cp conf/diamond.conf.example conf/diamond.conf - edit conf/diamond.conf - make run - -The *run* task will invoke diamond in debug mode for testing. - -Ant can also build packages for CentOS/RHEL, Ubuntu/Debian, or generate a tar ball. - - make buildrpm - sudo yum localinstall --nogpgcheck dist/diamond-0.2.0-1.noarch.rpm - - make builddeb - sudo dpkg -i dist/diamond-0.2.0-1.deb - - make tar - tar -xzvf dist/diamond-0.2.0.tar.gz - -Configuration -===== - -If you've installed diamond via a package, the configuration file is /etc/diamond/diamond.cfg. By default, diamond -will push to a graphite server host "graphite". You should probably change this to point to your own graphite server. - -Other configuration should not be necessary. - -By default diamond publishes metrics using the following form: - - systems... - -You can override the "systems" portion of the metric path by changing the "path_prefix" setting in the configuration file. - -Built-In Collectors -====== - -- CPUCollector -- DiskSpaceCollector -- DiskUsageCollector -- ExampleCollector -- FilestatCollector -- HAProxyCollector -- HttpdCollector -- InterruptCollector -- LoadAverageCollector -- MemoryCollector -- MongoDBCollector -- MySQLCollector -- NetworkCollector -- NginxCollector -- PingCollector -- SNMPCollector -- SNMPInterfaceCollector -- SockstatCollector -- TCPCollector -- UserScriptsCollector -- VMStatCollector - -Custom Collectors -====== - -Diamond collectors run within the diamond process and collect metrics that can be published to a graphite server. - -Collectors are subclasses of diamond.collector.Collector. In their simplest form, they need to implement a single method called "collect". - - import diamond.collector - - class ExampleCollector(diamond.collector.Collector): - - def collect(self): - """ - Overrides the Collector.collect method - """ - # Set Metric Name - metric_name = "my.example.metric" - - # Set Metric Value - metric_value = 42 - - # Publish Metric - self.publish(metric_name, metric_value) - -To run this collector in test mode you can invoke the diamond server with the -r option and specify the collector path. - -> python bin/diamond -f -v -r src/collectors/ExampleCollector/ExampleCollector.py -c conf/diamond.conf.example - -Diamond supports dynamic addition of collectors. Its configured to scan for new collectors on a regular interval (configured in diamond.cfg). -If diamond detects a new collector, or that a collectors module has changed (based on the file's mtime), it will be reloaded. - -Diamond looks for collectors in /usr/lib/diamond/collectors/ (on Ubuntu). By default diamond will invoke the *collect* method every 60 seconds. - -Diamond collectors that require a separate configuration file should place a .cfg file in /etc/diamond/collectors/. -The configuration file name should match the name of the diamond collector class. For example, a collector called -*examplecollector.ExampleCollector* could have its configuration file placed in /etc/diamond/collectors/ExampleCollector.cfg. - -Testing -===== - -Requirements: - -- python-mock -- python-configobj - -To run the tests - - make test - -Contacts -===== - -**Maintainer:** [Andy Kipp](mailto:akipp@brightove.com "Andy Kipp") - -Contributors -===== - -[Ivan Pouzyrevsky](https://github.com/sandello) - -[ooshlablu](https://github.com/ooshlablu) - -[oxcd8o](https://github.com/oxcd8o) - -[Rob Smith](https://github.com/kormoc) +The documentation can be found on our [wiki](https://github.com/BrightcoveOS/Diamond/wiki). For your +convenience the wiki is setup as a submodule of this checkout. You can get it via running -[Philip Cristiano](https://github.com/philipcristiano) + git submodule init + git submodule update diff --git a/docs b/docs new file mode 160000 index 000000000..ba456abc7 --- /dev/null +++ b/docs @@ -0,0 +1 @@ +Subproject commit ba456abc7560758a4ffdb61ecbd3f7e9391cfefe diff --git a/src/collectors/NginxCollector/README.md b/src/collectors/NginxCollector/README.md deleted file mode 100644 index e2f7f9ebf..000000000 --- a/src/collectors/NginxCollector/README.md +++ /dev/null @@ -1,15 +0,0 @@ -To enable the nginx status page to work with defaults, -add a file to /etc/nginx/sites-enabled/ (on Ubuntu) with the -following content: -
-  server {
-      listen 127.0.0.1:8080;
-      server_name localhost;
-      location /nginx_status {
-          stub_status on;
-          access_log /data/server/shared/log/access.log;
-          allow 127.0.0.1;
-          deny all;
-      }
-  }
-
diff --git a/src/collectors/SNMPInterfaceCollector/README.md b/src/collectors/SNMPInterfaceCollector/README.md deleted file mode 100644 index dce020eb0..000000000 --- a/src/collectors/SNMPInterfaceCollector/README.md +++ /dev/null @@ -1,40 +0,0 @@ -SNMPInterfaceCollector -===== - -The SNMPInterfaceCollector is designed for collecting interface data from remote SNMP-enabled devices such as routers and switches. - -Installation -===== - -The snmpinterfacecollector.py module should be installed into your Diamond installation collectors directory. This directory is defined -in diamond.cfg under the *collectors_path* directive. This defaults to */usr/lib/diamond/collectors/* on Ubuntu. - -The SNMPInterfaceCollector.cfg file should be installed into your diamond installation config directory. This directory is defined -in diamond.cfg under the *collectors_config_path* directive. This defaults to */etc/diamond/* on Ubuntu. - -Once the collector is installed and configured, you can wait for diamond to pick up the new collector automatically, or simply restart diamond. - -Configuration -===== - -Below is an example configuration for the SNMPInterfaceCollector. The collector can collect data any number of devices by adding configuration sections -under the *devices* header. By default the collector will collect every 60 seconds. This might be a bit excessive and put unnecessary load on the -devices being polled. You may wish to change this to every 300 seconds. However you need modify your graphite data retentions to handle this properly. - - # Options for SNMPInterfaceCollector - path = interface - interval = 60 - - [devices] - - [[router1]] - host = router1.example.com - port = 161 - community = public - - [[router2]] - host = router1.example.com - port = 161 - community = public - -Note: If you modify the SNMPInterfaceCollector configuration, you will need to restart diamond.