Merge pull request #321 from discordianfish/fish/scope-clarify-deprecate

RFC: Limit node-exporter scope, mark collectors deprecated that don't fit

CONTRIBUTING.md

@@ -16,3 +16,26 @@ Prometheus uses GitHub to manage reviews of pull requests.
   and the _Formatting and style_ section of Peter Bourgon's [Go: Best
   Practices for Production
   Environments](http://peter.bourgon.org/go-in-production/#formatting-and-style).
+
+
+## Collector Implementation Guidelines
+
+The Node Exporter is not a general monitoring agent. Its sole purpose is to
+expose machine metrics, as oppose to service metrics, with the only exception
+being the textfile collector.
+
+The metrics should not get transformed in a way that is hardware specific and
+would require maintaining any form of vendor based mappings or conditions. If
+for example a proc file contains the magic number 42 as some identifier, the
+Node Exporter should expose it as it is and not keep a mapping in code to make
+this human readable. Instead, the textfile collector can be used to add a static
+metric which can be joined with the metrics exposed by the exporter to get human
+readable identifier.
+
+A Collector may only read `/proc` or `/sys` files, use system calls or local
+sockets to retrieve metrics. It may not require root privileges. Running
+external commands is not allowed for performance and reliability reasons. Use a
+dedicated exporter instead or gather the metrics via the textfile collector.
+
+The Node Exporter tries to support the most common machine metrics. For more
+exotic metrics, use the textfile collector or a dedicated Exporter.

README.md

@@ -4,8 +4,8 @@
 [![Docker Repository on Quay](https://quay.io/repository/prometheus/node-exporter/status)][quay]
 [![Docker Pulls](https://img.shields.io/docker/pulls/prom/node-exporter.svg?maxAge=604800)][hub]
 
-Prometheus exporter for machine metrics, written in Go with pluggable metric
-collectors.
+Prometheus exporter for hardware and OS metrics exposed by the kernel, written
+in Go with pluggable metric collectors.
 
 ## Collectors
 
@@ -43,21 +43,28 @@ Name     | Description | OS
 bonding | Exposes the number of configured and active slaves of Linux bonding interfaces. | Linux
 devstat | Exposes device statistics | Dragonfly, FreeBSD
 drbd | Exposes Distributed Replicated Block Device statistics | Linux
-gmond | Exposes statistics from Ganglia. | _any_
 interrupts | Exposes detailed interrupts statistics. | Linux, OpenBSD
 ipvs | Exposes IPVS status from `/proc/net/ip_vs` and stats from `/proc/net/ip_vs_stats`. | Linux
 ksmd | Exposes kernel and system statistics from `/sys/kernel/mm/ksm`. | Linux
 logind | Exposes session counts from [logind](http://www.freedesktop.org/wiki/Software/systemd/logind/). | Linux
-megacli | Exposes RAID statistics from MegaCLI. | Linux
-meminfo_numa | Exposes memory statistics from `/proc/meminfo_numa`. | Linux
+meminfo\_numa | Exposes memory statistics from `/proc/meminfo_numa`. | Linux
 mountstats | Exposes filesystem statistics from `/proc/self/mountstats`. Exposes detailed NFS client statistics. | Linux
 nfs | Exposes NFS client statistics from `/proc/net/rpc/nfs`. This is the same information as `nfsstat -c`. | Linux
-ntp | Exposes time drift from an NTP server. | _any_
 runit | Exposes service status from [runit](http://smarden.org/runit/). | _any_
 supervisord | Exposes service status from [supervisord](http://supervisord.org/). | _any_
 systemd | Exposes service and system status from [systemd](http://www.freedesktop.org/wiki/Software/systemd/). | Linux
 tcpstat | Exposes TCP connection status information from `/proc/net/tcp` and `/proc/net/tcp6`. (Warning: the current version has potential performance issues in high load situations.) | Linux
 
+### Deprecated
+
+*These collectors will be (re)moved in the future.*
+
+Name     | Description | OS
+---------|-------------|----
+gmond | Exposes statistics from Ganglia. | _any_
+megacli | Exposes RAID statistics from MegaCLI. | Linux
+ntp | Exposes time drift from an NTP server. | _any_
+
 ### Textfile Collector
 
 The textfile collector is similar to the [Pushgateway](https://github.com/prometheus/pushgateway),

collector/collector.go

@@ -16,20 +16,19 @@ package collector
 
 import (
 	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/common/log"
 )
 
 const Namespace = "node"
 
 var Factories = make(map[string]func() (Collector, error))
 
+func warnDeprecated(collector string) {
+	log.Warnf("The %s collector is deprecated and will be removed in the future!", collector)
+}
+
 // Interface a collector has to implement.
 type Collector interface {
 	// Get new metrics and expose them via prometheus registry.
 	Update(ch chan<- prometheus.Metric) (err error)
 }
-
-// TODO: Instead of periodically call Update, a Collector could be implemented
-// as a real prometheus.Collector that only gathers metrics when
-// scraped. (However, for metric gathering that takes very long, it might
-// actually be better to do them proactively before scraping to minimize scrape
-// time.)

collector/gmond.go

@@ -48,6 +48,7 @@ var illegalCharsRE = regexp.MustCompile(`[^a-zA-Z0-9_]`)
 
 // Takes a prometheus registry and returns a new Collector scraping ganglia.
 func NewGmondCollector() (Collector, error) {
+	warnDeprecated("gmond")
 	c := gmondCollector{
 		metrics: map[string]*prometheus.GaugeVec{},
 	}

collector/megacli.go

@@ -50,6 +50,7 @@ func init() {
 // Takes a prometheus registry and returns a new Collector exposing
 // RAID status through megacli.
 func NewMegaCliCollector() (Collector, error) {
+	warnDeprecated("megacli")
 	return &megaCliCollector{
 		cli: *megacliCommand,
 		driveTemperature: prometheus.NewGaugeVec(prometheus.GaugeOpts{

collector/ntp.go

@@ -41,6 +41,7 @@ func init() {
 // Takes a prometheus registry and returns a new Collector exposing
 // the offset between ntp and the current system time.
 func NewNtpCollector() (Collector, error) {
+	warnDeprecated("ntp")
 	if *ntpServer == "" {
 		return nil, fmt.Errorf("no NTP server specified, see -collector.ntp.server")
 	}