Ceph Exporter for Prometheus Telemetry

This program acts as a Prometheus exporter, periodically scraping status metadata from an operational Ceph environment. All gathered cluster intelligence is acquired by communicating with the cluster's monitors via a suitable abstraction layer wrapping the rados_mon_command() function call. Consequently, initial setup is minimal—only a functional Ceph deployment is required.

A complete catalog of all time-series data harvested is documented within the METRICS.md reference document.

Prerequisites & Configuration

It is strongly recommended to execute this exporter on a node capable of network communication with the Ceph cluster. Similar to any standard Ceph client application, proper operation necessitates the presence of:

• ceph.conf: The primary configuration file detailing cluster parameters.
• ceph.client.<user>.keyring: The requisite secret file for authenticating against the cluster.

The ceph_exporter attempts to automatically locate these artifacts in recognized standard paths, referencing the official documentation on configuration file locations. If automatic discovery fails, configuration must be supplied via environment variables:

• CEPH_CLUSTER: Designates the cluster's identifier (defaults to ceph).
• CEPH_CONFIG: Specifies the path to the Ceph client configuration file (defaults to /etc/ceph/ceph.conf).
• CEPH_USER: Identifies the client persona authorized for cluster access (defaults to admin).

We leverage the official Golang client library from Ceph to execute necessary remote operations.

This exporter has been validated for use with Ceph versions Nautilus, Pacific, and Reef. Compatibility with earlier or non-LTS releases is not guaranteed.

Runtime Environment Variables

Variable Name	Purpose	Default Value
TELEMETRY_ADDR	The network socket (Host:Port) where the exporter exposes its metrics endpoint.	*:9128
TELEMETRY_PATH	The URI path utilized by Prometheus for metric retrieval.	/metrics
EXPORTER_CONFIG	Filesystem path pointing to the exporter's internal configuration file.	/etc/ceph/exporter.yml
RGW_MODE	Activates collection of statistics related to RGW (0=off, 1=on, 2=background operation).	0
CEPH_CLUSTER	Name assigned to the target Ceph cluster.	ceph
CEPH_CONFIG	Location of the Ceph configuration manifest file.	/etc/ceph/ceph.conf
CEPH_USER	The authorized Ceph principal for connection purposes.	admin
CEPH_RADOS_OP_TIMEOUT	Sets operation timeouts (rados_osd_op_timeout and rados_mon_op_timeout) for cluster interaction (a value of 0s signifies no timeout restriction).	30s
LOG_LEVEL	Controls the verbosity of logging output. Acceptable values: [trace, debug, info, warn, error, fatal, panic].	info
TLS_CERT_FILE_PATH	Filesystem route to the X.509 certificate file necessary for securing the metrics endpoint via TLS (key file path must also be provided).	(Empty)
TLS_KEY_FILE_PATH	Filesystem route to the private key file corresponding to the TLS certificate (cert file path must also be specified).	(Empty)

Deployment Instructions

The standard Go toolchain method for building or installing should succeed, assuming the requisite cgo dependencies for go-ceph are satisfied.

bash $ go install -tags nautilus

bash $ go build -o ceph_exporter -tags nautilus

The binary is compiled with specific support for Nautilus, but it generally retains functionality across Octopus and Pacific releases.

Containerization via Docker

Official Image Registry

The officially maintained Docker artifact is accessible at digitalocean/ceph_exporter.

Local Image Generation

It is entirely feasible to construct a customized image locally from the source code. By default, the ceph_exporter exposes its metrics service on TCP port 9128.

The exporter requires access to the Ceph configuration secrets to initiate communication with the cluster monitors. This can be achieved by mounting the directory containing both ceph.conf and the user's keyring file directly over the default path /etc/ceph expected by Ceph utilities.

A representative command for building the image might be:

bash $ docker build -t digitalocean/ceph_exporter .

A flag, --build-args TEST=true, can be appended to the preceding command to incorporate Golang unit test execution during the build phase:

bash docker build -t digitalocean/ceph_exporter . --build-arg TEST=true --no-cache

You are now ready to instantiate the ceph_exporter container.

bash $ docker run -v /etc/ceph:/etc/ceph -p=9128:9128 -it digitalocean/ceph_exporter

You must ensure that the containerized exporter can reach the cluster monitors across the network. If it requires access to the host machine's network interfaces, utilizing the --net=host runtime flag is advised, which subsequently negates the need for explicit port mapping (-p).

Configure your Prometheus instance to periodically poll the exporter at :9128 on the host machine (or whatever port you designated during execution).

Collaboration Guidelines

For insights on submitting modifications or enhancements to this repository, please consult the dedicated CONTRIBUTING guidelines document.

Illustrative Visualization

Refer to the ./examples directory for a docker-compose manifest useful for rapidly deploying a testing environment integrated with Grafana. Consult the comments within the docker-compose file for instructions on environment-specific adjustments. The setup utilizes Docker volumes for data persistence, following guidelines in the Docker volumes documentation.

If you operate an instance of promdash, you can engineer dashboard views similar to:

Copyright @ 2016-2023 DigitalOcean™ Inc. WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," according to ISO. It is commonly referred to as "the cloud".

== Defining Characteristics == In 2011, the National Institute of Standards and Technology (NIST) enumerated five "essential characteristics" defining cloud systems. The precise stipulations from NIST are:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service." By 2023, the International Organization for Standardization (ISO) had refined and augmented this criteria set.

== Chronology ==

The trajectory of cloud computing traces back to the 1960s, marked by the rising popularity of initial time-sharing concepts through remote job entry (RJE). The prevailing operational model during this epoch was the "data center" approach, where users submitted tasks to dedicated operators who executed them on mainframe systems. This era focused heavily on innovation and experimentation to broaden access to high-capacity computational resources for a larger user base via time-sharing, thereby enhancing infrastructure, platform, and application efficacy, and boosting end-user productivity. The semantic construct "cloud" referring to virtualized functionalities originated in 1994, utilized by General Magic to delineate the aggregate of potential "locations" reachable by mobile agents within their Telescript framework. This analogy is attributed to David Hoffman, a communications specialist at General Magic, who based it on its established convention within networking and telecommunications contexts. The term "cloud computing" gained mainstream recognition in 1996 when Compaq Computer Corporation drafted a strategic blueprint for prospective computation and the Internet. The organization's primary objective was to superch