d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
36a8572ee8
freebsd-dev/usr.sbin/prometheus_sysctl_exporter/prometheus_sysctl_exporter.8

123 lines
4.0 KiB
Groff
Raw Normal View History

Add a Prometheus exporter for sysctl values. Now that we have our sysctl tree annotated with aggregation labels, let's go ahead and provide a very simple utility for exporting the sysctl tree in Prometheus' format. It can either be used in conjunction with the Prometheus node exporter or run through inetd(8). The reason why I'm opting for having it in the base system is because it has a pretty strong integration with some of sysctl's innards, such as access to iterators, name lookups, metadata and type information. As I am investigating whether we can add histograms as native types to sysctl as well, this integration will only get stronger as we go along. That's why it would be safer to oversee the development of this exporter ourselves, as opposed to having it as an external project. This exporter is remarkably compact, especially when compared to the official Linux binary of the Prometheus node exporter (16 KB vs 12 MB). I guess this could be an interesting aspect for monitoring embedded FreeBSD-based systems. Differential Revision: https://reviews.freebsd.org/D8792
2016-12-21 08:29:44 +00:00
.\" Copyright (c) 2016 Nuxi, https://nuxi.nl/
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
prometheus_sysctl_exporter(8): filter output using a regex Add two options, -i and -e, for filtering prometheus metrics. Each option takes a regular expression as an argument. The provided regex will be tested against the prometheus metric name. The -i option includes metrics matching the given regex. The -e option excludes metrics matching the given regex. Sponsored by: Modirum MDPay Sponsored by: Klara Inc. Reviewed by: 0mp, debdrup Differential Revision: https://reviews.freebsd.org/D32269
2021-10-08 01:00:27 +00:00
.Dd October 7, 2021
Add a Prometheus exporter for sysctl values. Now that we have our sysctl tree annotated with aggregation labels, let's go ahead and provide a very simple utility for exporting the sysctl tree in Prometheus' format. It can either be used in conjunction with the Prometheus node exporter or run through inetd(8). The reason why I'm opting for having it in the base system is because it has a pretty strong integration with some of sysctl's innards, such as access to iterators, name lookups, metadata and type information. As I am investigating whether we can add histograms as native types to sysctl as well, this integration will only get stronger as we go along. That's why it would be safer to oversee the development of this exporter ourselves, as opposed to having it as an external project. This exporter is remarkably compact, especially when compared to the official Linux binary of the Prometheus node exporter (16 KB vs 12 MB). I guess this could be an interesting aspect for monitoring embedded FreeBSD-based systems. Differential Revision: https://reviews.freebsd.org/D8792
2016-12-21 08:29:44 +00:00
.Dt PROMETHEUS_SYSCTL_EXPORTER 8
.Os
.Sh NAME
.Nm prometheus_sysctl_exporter
.Nd print kernel state as Prometheus metrics
.Sh SYNOPSIS
.Nm prometheus_sysctl_exporter
.Op Fl dgh
prometheus_sysctl_exporter(8): filter output using a regex Add two options, -i and -e, for filtering prometheus metrics. Each option takes a regular expression as an argument. The provided regex will be tested against the prometheus metric name. The -i option includes metrics matching the given regex. The -e option excludes metrics matching the given regex. Sponsored by: Modirum MDPay Sponsored by: Klara Inc. Reviewed by: 0mp, debdrup Differential Revision: https://reviews.freebsd.org/D32269
2021-10-08 01:00:27 +00:00
.Op Fl e Ar pattern
.Op Fl i Ar pattern
Add a Prometheus exporter for sysctl values. Now that we have our sysctl tree annotated with aggregation labels, let's go ahead and provide a very simple utility for exporting the sysctl tree in Prometheus' format. It can either be used in conjunction with the Prometheus node exporter or run through inetd(8). The reason why I'm opting for having it in the base system is because it has a pretty strong integration with some of sysctl's innards, such as access to iterators, name lookups, metadata and type information. As I am investigating whether we can add histograms as native types to sysctl as well, this integration will only get stronger as we go along. That's why it would be safer to oversee the development of this exporter ourselves, as opposed to having it as an external project. This exporter is remarkably compact, especially when compared to the official Linux binary of the Prometheus node exporter (16 KB vs 12 MB). I guess this could be an interesting aspect for monitoring embedded FreeBSD-based systems. Differential Revision: https://reviews.freebsd.org/D8792
2016-12-21 08:29:44 +00:00
.Op Ar prefix ...
.Sh DESCRIPTION
Prometheus is a monitoring system that gathers metrics from its targets
by fetching them through HTTP GET requests.
Metrics are identified by a name and an optional set of labels.
Sample values are required to be numerical.
.Pp
The
.Nm
utility prints the values of sysctl nodes to standard output,
formatted such that they can be scraped by Prometheus directly.
By default,
it prints metrics for all numerically representable nodes in the sysctl
namespace.
It is also possible to limit output to a smaller number of metrics by
specifying one or more prefixes as arguments.
.Pp
Metrics printed by this utility are named
.Ql sysctl_ ,
followed by the name of the sysctl node having its
.Ql .\&
separators replaced by
.Ql _ .
Components on which it is desirable to aggregate (e.g.,
names of devices) are omitted from the metric's name,
but are appended as labels instead.
.Pp
There are two different methods for exporting the output of
.Nm
to Prometheus.
The first method is to periodically invoke this utility through
.Xr cron 8
and store its output in a textfile.
The metrics in this textfile can then be served over HTTP using the
Prometheus node exporter's textfile collector.
The second method is to run this utility through
.Xr inetd 8 .
TCP port 9124 has been allocated for this purpose.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl d
Print descriptions of metrics when available.
prometheus_sysctl_exporter(8): filter output using a regex Add two options, -i and -e, for filtering prometheus metrics. Each option takes a regular expression as an argument. The provided regex will be tested against the prometheus metric name. The -i option includes metrics matching the given regex. The -e option excludes metrics matching the given regex. Sponsored by: Modirum MDPay Sponsored by: Klara Inc. Reviewed by: 0mp, debdrup Differential Revision: https://reviews.freebsd.org/D32269
2021-10-08 01:00:27 +00:00
.It Fl e Ar pattern
Same as
.Fl i ,
except exclude metrics that match
.Ar pattern .
Add a Prometheus exporter for sysctl values. Now that we have our sysctl tree annotated with aggregation labels, let's go ahead and provide a very simple utility for exporting the sysctl tree in Prometheus' format. It can either be used in conjunction with the Prometheus node exporter or run through inetd(8). The reason why I'm opting for having it in the base system is because it has a pretty strong integration with some of sysctl's innards, such as access to iterators, name lookups, metadata and type information. As I am investigating whether we can add histograms as native types to sysctl as well, this integration will only get stronger as we go along. That's why it would be safer to oversee the development of this exporter ourselves, as opposed to having it as an external project. This exporter is remarkably compact, especially when compared to the official Linux binary of the Prometheus node exporter (16 KB vs 12 MB). I guess this could be an interesting aspect for monitoring embedded FreeBSD-based systems. Differential Revision: https://reviews.freebsd.org/D8792
2016-12-21 08:29:44 +00:00
.It Fl g
Gzip compresses the HTTP response body.
.It Fl h
Precede the output with a HTTP response header.
This flag is required when running this utility through
.Xr inetd 8 .
prometheus_sysctl_exporter(8): filter output using a regex Add two options, -i and -e, for filtering prometheus metrics. Each option takes a regular expression as an argument. The provided regex will be tested against the prometheus metric name. The -i option includes metrics matching the given regex. The -e option excludes metrics matching the given regex. Sponsored by: Modirum MDPay Sponsored by: Klara Inc. Reviewed by: 0mp, debdrup Differential Revision: https://reviews.freebsd.org/D32269
2021-10-08 01:00:27 +00:00
.It Fl i Ar pattern
If specified, include metrics that match
.Ar pattern .
The format of
.Ar pattern
is to be a regular expression as described in
.Xr re_format 7 .
The provided regular expression is tested against the Prometheus
metric name.
Add a Prometheus exporter for sysctl values. Now that we have our sysctl tree annotated with aggregation labels, let's go ahead and provide a very simple utility for exporting the sysctl tree in Prometheus' format. It can either be used in conjunction with the Prometheus node exporter or run through inetd(8). The reason why I'm opting for having it in the base system is because it has a pretty strong integration with some of sysctl's innards, such as access to iterators, name lookups, metadata and type information. As I am investigating whether we can add histograms as native types to sysctl as well, this integration will only get stronger as we go along. That's why it would be safer to oversee the development of this exporter ourselves, as opposed to having it as an external project. This exporter is remarkably compact, especially when compared to the official Linux binary of the Prometheus node exporter (16 KB vs 12 MB). I guess this could be an interesting aspect for monitoring embedded FreeBSD-based systems. Differential Revision: https://reviews.freebsd.org/D8792
2016-12-21 08:29:44 +00:00
.El
.Sh SEE ALSO
.Xr cron 8 ,
.Xr inetd 8 ,
.Xr sysctl 8 ,
.Xr SYSCTL_ADD_NODE_WITH_LABEL 9
.Pp
Prometheus project:
.Pa https://prometheus.io/ .
.Pp
Prometheus exposition formats:
.Pa https://prometheus.io/docs/instrumenting/exposition_formats/ .
.Pp
Prometheus node exporter:
.Pa https://github.com/prometheus/node_exporter .
.Pp
Prometheus default port allocations:
.Pa https://github.com/prometheus/prometheus/wiki/Default-port-allocations .
.Sh HISTORY
.Nm
first appeared in
.Fx 12.0 .
.Sh AUTHORS
.An Nuxi : Pa https://nuxi.nl/ .
Reference in New Issue Copy Permalink