diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5705f0fb..139a06c6 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index ee806e1a..25225bec 100644 --- a/README.md +++ b/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), diff --git a/collector/collector.go b/collector/collector.go index da109c96..8757f15b 100644 --- a/collector/collector.go +++ b/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.) diff --git a/collector/gmond.go b/collector/gmond.go index 573785d3..09840cd4 100644 --- a/collector/gmond.go +++ b/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{}, } diff --git a/collector/megacli.go b/collector/megacli.go index 6ceb78a1..9184e53b 100644 --- a/collector/megacli.go +++ b/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{ diff --git a/collector/ntp.go b/collector/ntp.go index 60c9b76e..ee4c9db5 100644 --- a/collector/ntp.go +++ b/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") }