### Startup Configuration Examples

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Examples of starting the exporter using environment variables or a configuration file.

```bash
export TELEMETRY_ADDR=":9128"
export TELEMETRY_PATH="/metrics"
export CEPH_CLUSTER="prod"
export CEPH_CONFIG="/etc/ceph/ceph.conf"
export CEPH_USER="admin"
export CEPH_RADOS_OP_TIMEOUT="30s"
export LOG_LEVEL="info"
export RGW_MODE="0"
ceph_exporter
```

```bash
export EXPORTER_CONFIG="/opt/ceph_exporter/config.yml"
ceph_exporter
```

--------------------------------

### Cluster Capacity Metrics Example

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

Example output for cluster capacity metrics showing the cluster label and metric values.

```text
ceph_cluster_capacity_bytes{cluster="prod"} 1.099511627776e+12
ceph_cluster_used_bytes{cluster="prod"} 5.497558138880e+11
ceph_cluster_available_bytes{cluster="prod"} 5.497558138880e+11
```

--------------------------------

### Install and Build Ceph Exporter

Source: https://github.com/digitalocean/ceph_exporter/blob/main/README.md

Commands to install or build the binary from source with specific Ceph version tags.

```bash
$ go install -tags nautilus
```

```bash
$ go build -o ceph_exporter -tags nautilus
```

--------------------------------

### Config and ClusterConfig Structs

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Configuration structures for managing multi-cluster setups via YAML.

```go
type Config struct {
    Cluster []*ClusterConfig
}
```

```go
type ClusterConfig struct {
    ClusterLabel string `yaml:"cluster_label"`
    User         string `yaml:"user"`
    ConfigFile   string `yaml:"config_file"`
}
```

--------------------------------

### Example YAML configuration

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

A sample YAML file demonstrating the structure for defining multiple Ceph clusters.

```yaml
cluster:
  - cluster_label: prod-cluster
    user: admin
    config_file: /etc/ceph/ceph.conf
  - cluster_label: test-cluster
    user: test
    config_file: /etc/ceph/test-ceph.conf
```

--------------------------------

### Commit Message Examples

Source: https://github.com/digitalocean/ceph_exporter/blob/main/CONTRIBUTING.md

Examples of descriptive and non-descriptive commit messages for project history.

```text
monitor: expose metrics for clock skew
  - scrape monitor's skew value from ceph's status
```

```text
new monitor metrics
```

--------------------------------

### Enable RGW Metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Configure RGW collection mode via environment variables before starting the exporter.

```bash
export RGW_MODE=1  # foreground collection
# or
export RGW_MODE=2  # background collection
ceph_exporter
```

--------------------------------

### HTTPS Metrics Request

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Example request when TLS is enabled via certificate and key file paths.

```text
GET https://localhost:9128/metrics
```

--------------------------------

### Run Ceph Exporter Container

Source: https://github.com/digitalocean/ceph_exporter/blob/main/README.md

Command to start the container with the required Ceph configuration volume mounted.

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

--------------------------------

### Multi-Cluster YAML Configuration

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Example of a YAML configuration file to monitor multiple Ceph clusters.

```yaml
cluster:
  - cluster_label: cluster-a
    user: admin
    config_file: /etc/ceph/cluster-a.conf
  - cluster_label: cluster-b
    user: monitor_user
    config_file: /etc/ceph/cluster-b.conf
```

--------------------------------

### Use Version in Collectors

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Examples of using version checks to handle differences in metrics and JSON structures.

```go
if version.IsAtLeast(Pacific) {
    // Pacific adds DAEMON_OLD_VERSION health check
    c.healthChecksMap["DAEMON_OLD_VERSION"] = 2
}
```

```go
if version.IsAtLeast(Octopus) {
    // Octopus changed OSDMap JSON structure
    actualOsdMap = osdMap{
        NumOSDs:        stats.OSDMap["num_osds"].(float64),
        NumUpOSDs:      stats.OSDMap["num_up_osds"].(float64),
        // ...
    }
} else {
    // Pre-Octopus structure
    innerMap := stats.OSDMap["osdmap"].(map[string]interface{})
    actualOsdMap = osdMap{
        NumOSDs:        innerMap["num_osds"].(float64),
        // ...
    }
}
```

--------------------------------

### GET /

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Provides a simple HTML status page for health checks and manual verification.

```APIDOC
## GET /

### Description
Returns a simple HTML page containing a link to the metrics endpoint. Useful for verifying that the exporter is running.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Content-Type** (string) - text/html
- **Body** (string) - HTML page with a link to /metrics
```

--------------------------------

### Status Endpoint Request

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Example HTTP request for the status endpoint.

```http
GET / HTTP/1.1
Host: localhost:9128
```

--------------------------------

### Metrics Endpoint Request

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Example HTTP request for the metrics endpoint.

```http
GET /metrics HTTP/1.1
Host: localhost:9128
Accept: text/plain
```

--------------------------------

### Get Ceph versions command

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Returns the JSON-marshaled command required to query Ceph versions.

```go
func CephVersionsCmd() ([]byte, error)
```

--------------------------------

### GET /metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Retrieves all registered metrics from active collectors in Prometheus exposition format.

```APIDOC
## GET /metrics

### Description
Returns the current metrics from the Ceph cluster in Prometheus text format. This endpoint triggers a synchronous collection process from all registered collectors.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **Content-Type** (string) - text/plain; version=0.0.4
- **Body** (string) - Prometheus exposition format text output containing all registered metrics.
```

--------------------------------

### Prometheus Multiple Cluster Configuration

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Configuration for filtering metrics by cluster label in multi-cluster setups.

```yaml
scrape_configs:
  - job_name: 'ceph'
    static_configs:
      - targets: ['localhost:9128']
    metric_relabel_configs:
      # Optional: keep only specific clusters
      - source_labels: [cluster]
        regex: 'prod|staging'
        action: keep
```

--------------------------------

### Configuration Priority Logic

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Demonstrates the internal logic for selecting between a configuration file and environment variables.

```go
// Priority 1: Check for config file
if fileExists(*exporterConfig) {
    cfg, err := ParseConfig(*exporterConfig)
    clusterConfigs = cfg.Cluster
} else {
    // Priority 2: Use environment variables
    clusterConfigs = []*ClusterConfig{
        {
            ClusterLabel: *cephCluster,
            User:         *cephUser,
            ConfigFile:   *cephConfig,
        },
    }
}
```

--------------------------------

### Initialize RadosConn

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Constructor for creating a new RadosConn instance and establishing the cluster connection.

```go
func NewRadosConn(user, configFile string, timeout time.Duration, logger *logrus.Logger) (*RadosConn, error)
```

--------------------------------

### Enable TLS

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Set environment variables for certificate and key paths to enable TLS for the exporter.

```bash
export TLS_CERT_FILE_PATH=/etc/ceph/exporter-cert.pem
export TLS_KEY_FILE_PATH=/etc/ceph/exporter-key.pem
ceph_exporter
```

--------------------------------

### Build Docker Image

Source: https://github.com/digitalocean/ceph_exporter/blob/main/README.md

Commands to build the Docker image locally, optionally including unit tests.

```bash
$ docker build -t digitalocean/ceph_exporter .
```

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

--------------------------------

### Define Version Methods

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Methods for comparing versions and formatting them as strings.

```go
func (version *Version) IsAtLeast(constraint *Version) bool
```

```go
func (version *Version) String() string
```

--------------------------------

### Initialize OSDCollector

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Constructor function for creating a new OSDCollector instance.

```go
func NewOSDCollector(exporter *Exporter) *OSDCollector
```

--------------------------------

### Initialize Rados Connection and Execute Commands

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Establishes a connection to a Ceph cluster using configuration files and executes monitor commands or retrieves pool statistics.

```go
// Create a connection to the Ceph cluster
conn, err := rados.NewRadosConn(
    "admin",                      // user
    "/etc/ceph/ceph.conf",        // config file
    30*time.Second,               // timeout
    logrus.New(),                 // logger
)
if err != nil {
    panic(err)
}

// Execute a monitor command
cmd, _ := json.Marshal(map[string]interface{}{
    "prefix": "df",
    "format": "json",
})
buf, info, err := conn.MonCommand(cmd)
if err != nil {
    panic(err)
}

// Get pool stats
stats, err := conn.GetPoolStats("rbd")
if err != nil {
    panic(err)
}
println(stats.ObjectsUnfound)
```

--------------------------------

### Initialize Exporter

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Constructor for creating an Exporter instance. It registers default collectors and performs initial version detection.

```go
func NewExporter(conn Conn, cluster string, config string, user string, rgwMode int, logger *logrus.Logger) *Exporter
```

--------------------------------

### RGWCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Initializes a new RGWCollector instance with background mode support.

```go
func NewRGWCollector(exporter *Exporter, background bool) *RGWCollector
```

--------------------------------

### Check file existence

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Utility function to verify if a file exists and is a regular file.

```go
func fileExists(path string) bool
```

--------------------------------

### MonCommand

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Executes a raw monitor command against the Ceph cluster.

```APIDOC
## func (c *RadosConn) MonCommand(args []byte) (buffer []byte, info string, err error)

### Description
Executes a raw monitor command (typically JSON-formatted).

### Parameters
- **args** ([]byte) - Required - JSON-marshaled command dictionary

### Returns
- **buffer** ([]byte) - JSON response from Ceph
- **info** (string) - Human-readable info string
- **err** (error) - Execution error, or nil on success
```

--------------------------------

### PoolInfoCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Initializes a new instance of the PoolInfoCollector using the provided Exporter.

```go
func NewPoolInfoCollector(exporter *Exporter) *PoolInfoCollector
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Set the log level to debug for troubleshooting.

```bash
export LOG_LEVEL=debug
ceph_exporter
```

--------------------------------

### Initialize collectors

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Creates the set of enabled collectors based on the configured RGW mode.

```go
func (exporter *Exporter) initCollectors() map[string]versionedCollector
```

--------------------------------

### Version.String

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Converts the Version struct back into a string representation.

```APIDOC
## func (version *Version) String() string

### Description
Formats the version as a string representation (e.g., "16.2.0" or "16.2.0-1-abc123"). Includes revision and commit if they are non-empty.
```

--------------------------------

### MonitorCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Initializes a new MonitorCollector instance using the provided Exporter.

```go
func NewMonitorCollector(exporter *Exporter) *MonitorCollector
```

--------------------------------

### conn.MonCommand

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Executes a monitor command on the Ceph cluster.

```APIDOC
## conn.MonCommand

### Description
Sends a monitor command to the Ceph cluster and returns the result.

### Parameters
- **cmd** ([]byte) - JSON-marshaled command map containing the prefix and format.
```

--------------------------------

### Version.IsAtLeast

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Compares the current version against a constraint version to determine if it is equal or newer.

```APIDOC
## func (version *Version) IsAtLeast(constraint *Version) bool

### Description
Determines whether the version is at least as new as the constraint. Comparison order is Major → Minor → Patch → Revision. Commit hashes are not considered.

### Parameters
- **constraint** (*Version) - Required - The version to compare against.
```

--------------------------------

### MgrCommand

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Executes a manager command with arguments as separate byte slices.

```APIDOC
## func (c *RadosConn) MgrCommand(args [][]byte) (buffer []byte, info string, err error)

### Description
Executes a manager command with arguments as separate byte slices.

### Parameters
- **args** ([][]byte) - Required - Command parts (e.g., []byte{"osd", "tree"})

### Returns
- **buffer** ([]byte) - JSON response from Ceph
- **info** (string) - Human-readable info string
- **err** (error) - Execution error, or nil on success
```

--------------------------------

### rados.NewRadosConn

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Initializes a new connection to the Ceph cluster.

```APIDOC
## rados.NewRadosConn

### Description
Creates a new connection to the Ceph cluster using the provided credentials and configuration.

### Parameters
- **user** (string) - The Ceph user name.
- **configFile** (string) - Path to the ceph.conf file.
- **timeout** (time.Duration) - Connection timeout duration.
- **logger** (logrus.Logger) - Logger instance.
```

--------------------------------

### Run Ceph Exporter via Environment Variables

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Configure the exporter by setting environment variables before executing the binary.

```bash
export CEPH_CLUSTER=prod
export CEPH_CONFIG=/etc/ceph/ceph.conf
export CEPH_USER=admin
export TELEMETRY_ADDR=:9128
export TELEMETRY_PATH=/metrics
ceph_exporter
```

--------------------------------

### Initialize ClusterUsageCollector

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Constructor function to create and initialize the collector with cluster-labeled metrics.

```go
func NewClusterUsageCollector(exporter *Exporter) *ClusterUsageCollector
```

--------------------------------

### Execute Monitor Command

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Executes raw monitor commands and handles JSON post-processing for Ceph-specific float values.

```go
func (c *RadosConn) MonCommand(args []byte) (buffer []byte, info string, err error)
```

--------------------------------

### PoolUsageCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Initializes a new PoolUsageCollector instance.

```go
func NewPoolUsageCollector(exporter *Exporter) *PoolUsageCollector
```

--------------------------------

### Describe collector metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Sends metric descriptors for the capacity metrics to the provided channel.

```go
func (c *ClusterUsageCollector) Describe(ch chan<- *prometheus.Desc)
```

--------------------------------

### Execute Manager Command

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Executes manager commands using arguments provided as a slice of byte slices.

```go
func (c *RadosConn) MgrCommand(args [][]byte) (buffer []byte, info string, err error)
```

--------------------------------

### ParseConfig function signature

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Parses a YAML configuration file from the provided path and returns the Config structure or an error.

```go
func ParseConfig(p string) (*Config, error)
```

--------------------------------

### Define Config structure

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Represents the top-level configuration structure for the exporter, supporting multiple cluster configurations.

```go
type Config struct {
    Cluster []*ClusterConfig
}
```

--------------------------------

### Define Version structure

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Represents parsed Ceph version information with semantic versioning components.

```go
type Version struct {
    Major    int
    Minor    int
    Patch    int
    Revision int
    Commit   string
}
```

--------------------------------

### Describe metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Sends metric descriptors to the Prometheus channel. This method is invoked during registration.

```go
func (exporter *Exporter) Describe(ch chan<- *prometheus.Desc)
```

--------------------------------

### Define Predefined Version Constants

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Constants representing known Ceph releases for conditional metric collection.

```go
var (
    Nautilus *Version = &Version{Major: 14, Minor: 2, Patch: 0, Revision: 0, Commit: ""}
    Octopus  *Version = &Version{Major: 15, Minor: 2, Patch: 0, Revision: 0, Commit: ""}
    Pacific  *Version = &Version{Major: 16, Minor: 2, Patch: 0, Revision: 0, Commit: ""}
)
```

--------------------------------

### NewRadosConn

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Creates a new RadosConn instance and establishes a connection to the Ceph cluster.

```APIDOC
## func NewRadosConn(user, configFile string, timeout time.Duration, logger *logrus.Logger) (*RadosConn, error)

### Description
Creates a new RadosConn and establishes connection to the cluster.

### Parameters
- **user** (string) - Required - Ceph user (e.g., "admin")
- **configFile** (string) - Required - Path to Ceph configuration file
- **timeout** (time.Duration) - Required - Rados operation timeout; 0 disables
- **logger** (*logrus.Logger) - Required - Logger instance

### Returns
- (*RadosConn, error) - Connection ready for commands, or error on failure
```

--------------------------------

### Define cephOSDLabel struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Structure for storing OSD metadata including hostname and device type.

```go
type cephOSDLabel struct {
    Hostname string
    Type     string
}
```

--------------------------------

### Metrics Endpoint Response

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Sample output in Prometheus exposition format returned by the metrics endpoint.

```text
# HELP ceph_cluster_capacity_bytes Total capacity of the cluster
# TYPE ceph_cluster_capacity_bytes gauge
ceph_cluster_capacity_bytes{cluster="ceph"} 1.099511627776e+12

# HELP ceph_cluster_used_bytes Capacity of the cluster currently in use
# TYPE ceph_cluster_used_bytes gauge
ceph_cluster_used_bytes{cluster="ceph"} 5.497558138880e+11

# HELP ceph_health_status Health status of Cluster, can vary only between 3 states (err:2, warn:1, ok:0)
# TYPE ceph_health_status gauge
ceph_health_status{cluster="ceph"} 0
```

--------------------------------

### Retrieve Pool Statistics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Opens an IOContext to fetch unfound object counts for a specified pool.

```go
func (c *RadosConn) GetPoolStats(pool string) (*PoolStat, error)
```

--------------------------------

### Collect cluster metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Executes the ceph df detail command and sends the collected metrics to the channel.

```go
func (c *ClusterUsageCollector) Collect(ch chan<- prometheus.Metric, version *Version)
```

--------------------------------

### RbdMirrorStatusCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Initializes a new RbdMirrorStatusCollector instance.

```go
func NewRbdMirrorStatusCollector(exporter *Exporter) *RbdMirrorStatusCollector
```

--------------------------------

### Define format type and constants

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Controls the output format for Ceph commands, supporting JSON for metrics and plain text for parsing.

```go
type format string

const (
    jsonFormat  format = "json"
    plainFormat format = "plain"
)
```

--------------------------------

### Parse Ceph Version

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Parses a Ceph version string from command output.

```go
func ParseCephVersion(cephVersion string) (*Version, error)
```

```go
v, err := ParseCephVersion("ceph version 16.2.0 (abc123def456...) pacific")
// v.Major = 16, v.Minor = 2, v.Patch = 0, v.Revision = 0
// v.Commit = ""

v2, err := ParseCephVersion("ceph version 15.2.1-2-def456 (xyz789...) octopus")
// v2.Major = 15, v2.Minor = 2, v2.Patch = 1, v2.Revision = 2
// v2.Commit = "def456"
```

--------------------------------

### Define cephPGDumpBrief struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Used for tracking placement group state duration.

```go
type cephPGDumpBrief struct {
    // PG state dump for inactivity detection
}
```

--------------------------------

### Define Error Variable

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Error returned by ParseCephVersion when input format is invalid.

```go
var ErrInvalidVersion error
```

--------------------------------

### Verify prometheus.Collector implementation

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Ensures the Exporter struct satisfies the prometheus.Collector interface at compile time.

```go
var _ prometheus.Collector = &ceph.Exporter{}
```

--------------------------------

### Define OSD Label Format

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

Use the OSD number rather than the full OSD identifier string.

```text
osd="0"   # OSD number (not "osd.0")
```

--------------------------------

### Change Metrics Endpoint Path

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Customize the URL path where metrics are exposed.

```bash
export TELEMETRY_PATH=/ceph-metrics
ceph_exporter
# Metrics available at http://localhost:9128/ceph-metrics
```

--------------------------------

### Adjust Timeouts and Address

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Configure RADOS operation timeouts and the telemetry address for large clusters.

```bash
export CEPH_RADOS_OP_TIMEOUT=60s
export TELEMETRY_ADDR=:9128
ceph_exporter
```

--------------------------------

### Define cephMonitorStats struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Represents monitor quorum membership.

```go
type cephMonitorStats struct {
    Quorum []int `json:"quorum"`
}
```

--------------------------------

### Metrics Endpoint Path

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

The default path for retrieving metrics, which can be customized via the TELEMETRY_PATH environment variable.

```text
GET /metrics
```

--------------------------------

### ClusterHealthCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Initializes the collector and populates the health check mapping with criticality levels.

```go
func NewClusterHealthCollector(exporter *Exporter) *ClusterHealthCollector
```

--------------------------------

### Define Pool Profile Labels

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

Profile labels distinguish between replicated and erasure-coded storage configurations.

```text
profile="replicated"
profile="ec"   # Erasure-coded
```

--------------------------------

### Define the Conn interface

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

This interface abstracts Ceph cluster connections to facilitate clean implementations and unit test mocking.

```go
type Conn interface {
    MonCommand([]byte) ([]byte, string, error)
    MgrCommand([][]byte) ([]byte, string, error)
    GetPoolStats(string) (*PoolStat, error)
}
```

--------------------------------

### Define Cluster Label

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

The cluster name is configured via the CEPH_CLUSTER environment variable or configuration file.

```text
cluster="prod"
```

--------------------------------

### Define cephOSDTree and osdNode structs

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Represents the OSD tree hierarchy retrieved from ceph osd tree.

```go
type cephOSDTree struct {
    Nodes []osdNode
}

type osdNode struct {
    ID       int64
    Name     string
    Type     string
    CrushWeight float64
}
```

--------------------------------

### Define cephOSDTreeDown struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Used for tracking down OSDs.

```go
type cephOSDTreeDown struct {
    // Down OSDs list
}
```

--------------------------------

### Collect metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Performs thread-safe metric collection from all registered collectors using concurrent goroutines.

```go
func (exporter *Exporter) Collect(ch chan<- prometheus.Metric)
```

--------------------------------

### CrashesCollector Constructor

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Initializes a new CrashesCollector instance.

```go
func NewCrashesCollector(exporter *Exporter) *CrashesCollector
```

--------------------------------

### Pool Type Constants

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Defines constants for identifying pool types, where 1 represents replicated pools and 3 represents erasure-coded pools.

```go
const (
    poolReplicated = 1
    poolErasure    = 3
)
```

--------------------------------

### Prometheus Scrape Job Configuration

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Standard configuration for a Prometheus scrape job targeting the Ceph Exporter.

```yaml
global:
  scrape_interval: 30s
  scrape_timeout: 10s

scrape_configs:
  - job_name: 'ceph'
    static_configs:
      - targets: ['localhost:9128']
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
```

--------------------------------

### ParseCephVersion

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/03-version-handling.md

Parses a raw Ceph version string into a Version struct. Returns an error if the input format is invalid.

```APIDOC
## func ParseCephVersion(cephVersion string) (*Version, error)

### Description
Parses a Ceph version string from command output (typically `ceph version` response) into a structured `Version` object.

### Parameters
- **cephVersion** (string) - Required - Full version string from ceph (e.g., "ceph version 16.2.0 ...")

### Returns
- **(*Version, error)** - Parsed version object, or `ErrInvalidVersion` if parsing fails.
```

--------------------------------

### Metric Naming Convention

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

The standard format for all metrics exported by the ceph_exporter.

```text
ceph_{subsystem}_{metric_name}_{unit}
```

--------------------------------

### Conn Interface Methods

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

The Conn interface defines the primary methods for interacting with the Ceph cluster, including command execution and pool statistics retrieval.

```APIDOC
## MonCommand

### Description
Executes a monitor command on the Ceph cluster.

### Signature
`MonCommand(cmd []byte) ([]byte, string, error)`

### Parameters
- **cmd** ([]byte) - Required - The JSON command to execute.

---

## MgrCommand

### Description
Executes a manager command on the Ceph cluster.

### Signature
`MgrCommand(args [][]byte) ([]byte, string, error)`

### Parameters
- **args** ([][]byte) - Required - An array of command parts.

---

## GetPoolStats

### Description
Retrieves statistics for a specific pool, including the count of unfound objects.

### Signature
`GetPoolStats(poolName string) (*PoolStat, error)`

### Parameters
- **poolName** (string) - Required - The name of the pool to query.

### Returns
- **PoolStat** (struct) - Contains the field `ObjectsUnfound` (uint64).
```

--------------------------------

### Set RBD mirror

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Checks for the presence of rbd-mirror daemons and updates the collector set accordingly.

```go
func (exporter *Exporter) setRbdMirror() error
```

--------------------------------

### Set Ceph version

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Executes the ceph version command and updates the internal Version struct.

```go
func (exporter *Exporter) setCephVersion() error
```

--------------------------------

### Parse Ceph versions

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

Parses the JSON output from the ceph versions command into a nested map structure.

```go
func ParseCephVersions(buf []byte) (map[string]map[string]float64, error)
```

--------------------------------

### Ceph Health Status Constants

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Defines the standard health status strings used for cluster monitoring.

```go
const (
    CephHealthOK   = "HEALTH_OK"   // status = 0
    CephHealthWarn = "HEALTH_WARN" // status = 1
    CephHealthErr  = "HEALTH_ERR"  // status = 2
)
```

--------------------------------

### Define versionedCollector Interface

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Interface definition for collectors to handle version-specific metrics and descriptions.

```go
type versionedCollector interface {
    Collect(ch chan<- prometheus.Metric, *Version)
    Describe(chan<- *prometheus.Desc)
}
```

--------------------------------

### Define versionedCollector interface

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

The versionedCollector interface allows for Ceph release-specific metric emission.

```go
type versionedCollector interface {
    Collect(chan<- prometheus.Metric, *Version)
    Describe(chan<- *prometheus.Desc)
}
```

--------------------------------

### Define Pool Labels

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

Pool labels identify the specific storage pool being reported.

```text
pool="rbd"
pool="cephfs_data"
```

--------------------------------

### Define RadosConn struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

The internal structure for managing Ceph connections, including configuration, timeouts, and logging.

```go
type RadosConn struct {
    user       string
    conn       *rados.Conn
    configFile string
    timeout    time.Duration
    logger     *logrus.Logger
}
```

--------------------------------

### Define ClusterConfig structure

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/04-configuration.md

Defines the configuration for a single Ceph cluster connection, including authentication and file path details.

```go
type ClusterConfig struct {
    ClusterLabel string `yaml:"cluster_label"`
    User         string `yaml:"user"`
    ConfigFile   string `yaml:"config_file"`
}
```

--------------------------------

### Describe ClusterHealthCollector metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Sends all metric descriptors including RBD Mirror to the Prometheus channel.

```go
func (c *ClusterHealthCollector) Describe(ch chan<- *prometheus.Desc)
```

--------------------------------

### RGWCollector Type Definition

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Defines the structure for monitoring Radosgw metrics, including background mode configuration.

```go
type RGWCollector struct {
    conn               Conn
    logger             *logrus.Logger
    backgroundMode     bool
    
    // Metrics for RGW usage per bucket
    RgwMetrics         *prometheus.GaugeVec
}
```

--------------------------------

### Status Endpoint Path

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

The root path used for health checks and manual verification.

```text
GET /
```

--------------------------------

### Define OSDCollector struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Defines the OSDCollector structure containing Prometheus GaugeVec metrics and internal state caches.

```go
type OSDCollector struct {
    conn                  Conn
    logger                *logrus.Logger
    
    osdScrubCache         map[int]int
    osdLabelsCache        map[int64]*cephOSDLabel
    oldestInactivePGMap   map[string]time.Time
    
    CrushWeight           *prometheus.GaugeVec
    Depth                 *prometheus.GaugeVec
    Reweight              *prometheus.GaugeVec
    Bytes                 *prometheus.GaugeVec
    UsedBytes             *prometheus.GaugeVec
    AvailBytes            *prometheus.GaugeVec
    Utilization           *prometheus.GaugeVec
    
    // Scratch/in-progress PGs
    PgsRemapped           *prometheus.GaugeVec
    
    // Scrubbing states
    ScrubState            *prometheus.GaugeVec
    FullRatio             *prometheus.GaugeVec
    NearFullRatio         *prometheus.GaugeVec
    BackfillFullRatio     *prometheus.GaugeVec
    
    // Diagnostic
    OldestInactivePGAge   *prometheus.GaugeVec
    CommitLatency         *prometheus.GaugeVec
    ApplyLatency          *prometheus.GaugeVec
}
```

--------------------------------

### Collect ClusterHealthCollector metrics

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Executes concurrent goroutines to parse Ceph status and report metrics.

```go
func (c *ClusterHealthCollector) Collect(ch chan<- prometheus.Metric, version *Version)
```

--------------------------------

### Define cephTimeSyncStatus struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Represents inter-monitor clock synchronization status derived from ceph mon stat.

```go
type cephTimeSyncStatus struct {
    TimeChecks map[string]struct {
        Health  string
        Latency json.Number
        Skew    json.Number
    } `json:"time_skew_status"`
}
```

--------------------------------

### Ceph Exporter Architecture Flow

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/00-index.md

Visual representation of the metric collection pipeline from Prometheus scrape to parallel collector execution.

```text
                        ┌─ ClusterUsageCollector
                        ├─ ClusterHealthCollector
Prometheus Scrape       │
      ↓                 ├─ MonitorCollector
/metrics                │
      ↓                 ├─ OSDCollector
   Exporter             │
      ↓                 ├─ PoolInfoCollector
   Collect()            │
      ↓                 ├─ PoolUsageCollector
(acquire mutex)         │
      ↓                 ├─ CrashesCollector
Per-Collector           │
Collect()               ├─ RGWCollector (conditional)
(in parallel)           │
      ↓                 └─ RbdMirrorStatusCollector (dynamic)
Send Metrics
      ↓
Prometheus
```

--------------------------------

### Handle Ceph Infinity Values

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Utility function to sanitize JSON responses by converting invalid 'inf' or 'Inf' values to 'null'.

```go
func handleCephInf(buf []byte) []byte
```

--------------------------------

### Define ClusterUsageCollector struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/05-cluster-collectors.md

Defines the structure for the collector, including the connection, logger, and Prometheus gauges for capacity metrics.

```go
type ClusterUsageCollector struct {
    conn   Conn
    logger *logrus.Logger
    
    GlobalCapacity    prometheus.Gauge
    UsedCapacity      prometheus.Gauge
    AvailableCapacity prometheus.Gauge
}
```

--------------------------------

### Define the PoolStat type

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Represents pool statistics, specifically tracking the count of unfound objects.

```go
type PoolStat struct {
    ObjectsUnfound uint64
}
```

--------------------------------

### Define Monitor Label

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/08-prometheus-metrics.md

The monitor label identifies the specific monitor node.

```text
monitor="mon.0"
```

--------------------------------

### MonitorCollector Definition

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Collector struct for monitor-specific metrics like clock skew and quorum size.

```go
type MonitorCollector struct {
    conn          Conn
    logger        *logrus.Logger
    ClockSkew     *prometheus.GaugeVec
    Latency       *prometheus.GaugeVec
    NodesinQuorum prometheus.Gauge
    CephVersions  *prometheus.GaugeVec
    CephFeatures  *prometheus.GaugeVec
}
```

--------------------------------

### MonitorCollector Type Definition

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Defines the structure of the MonitorCollector, including its connection, logger, and Prometheus metrics.

```go
type MonitorCollector struct {
    conn             Conn
    logger           *logrus.Logger
    
    ClockSkew        *prometheus.GaugeVec
    Latency          *prometheus.GaugeVec
    NodesinQuorum    prometheus.Gauge
    CephVersions     *prometheus.GaugeVec
    CephFeatures     *prometheus.GaugeVec
}
```

--------------------------------

### Status Endpoint Response

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

HTML response body for the status endpoint.

```html
<html>
<head><title>Ceph Exporter</title></head>
<body>
<h1>Ceph Exporter</h1>
<p><a href='/metrics'>Metrics</a></p>
</body>
</html>
```

--------------------------------

### Define Exporter struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/01-core-exporter.md

The Exporter struct implements the Prometheus Collector interface and holds cluster configuration and state.

```go
type Exporter struct {
    mu        sync.Mutex
    Conn      Conn
    Cluster   string
    Config    string
    User      string
    RgwMode   int
    RbdMirror bool
    Logger    *logrus.Logger
    Version   *Version
    cc        map[string]versionedCollector
}
```

--------------------------------

### Prometheus Scrape Timeout Configuration

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/07-http-endpoints.md

Configuration ensuring the scrape timeout exceeds the Ceph operation timeout.

```yaml
scrape_configs:
  - job_name: 'ceph'
    scrape_timeout: 45s
    static_configs:
      - targets: ['localhost:9128']
```

--------------------------------

### GetPoolStats

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Retrieves unfound object count for a specific pool.

```APIDOC
## func (c *RadosConn) GetPoolStats(pool string) (*PoolStat, error)

### Description
Retrieves unfound object count for a specific pool by opening an IOContext.

### Parameters
- **pool** (string) - Required - Pool name

### Returns
- (*PoolStat, error) - Count of unfound objects, or error on failure
```

--------------------------------

### conn.GetPoolStats

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/02-connection-interface.md

Retrieves statistics for a specific Ceph pool.

```APIDOC
## conn.GetPoolStats

### Description
Fetches statistics for the specified pool name.

### Parameters
- **poolName** (string) - The name of the pool to query.
```

--------------------------------

### PoolUsageCollector

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Provides per-pool data usage metrics for Ceph clusters.

```APIDOC
## PoolUsageCollector

### Constructor
`func NewPoolUsageCollector(exporter *Exporter) *PoolUsageCollector`

### Exported Metrics
| Metric | Type | Labels | Description |
|--------|------|--------|-------------|
| `ceph_pool_objects` | GaugeVec | pool | RADOS objects in pool |
| `ceph_pool_bytes` | GaugeVec | pool | Logical bytes stored |
| `ceph_pool_dirty_bytes` | GaugeVec | pool | Unflushed cache bytes |
| `ceph_pool_raw_bytes` | GaugeVec | pool | Physical bytes (with replication) |
| `ceph_pool_raw_bytes_used` | GaugeVec | pool | Physical bytes used |
| `ceph_pool_raw_bytes_avail` | GaugeVec | pool | Physical bytes available |
| `ceph_pool_unfound_objects` | GaugeVec | pool | Lost/unfound objects (via GetPoolStats) |
```

--------------------------------

### OSDCollector Definition and Internal Types

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Collector struct for OSD-level metrics and associated internal data structures.

```go
type OSDCollector struct {
    conn                Conn
    logger                *logrus.Logger
    osdScrubCache       map[int]int
    osdLabelsCache      map[int64]*cephOSDLabel
    oldestInactivePGMap map[string]time.Time
    CrushWeight         *prometheus.GaugeVec
    Depth               *prometheus.GaugeVec
    Reweight            *prometheus.GaugeVec
    Bytes               *prometheus.GaugeVec
    UsedBytes           *prometheus.GaugeVec
    AvailBytes          *prometheus.GaugeVec
    // ... and 10+ additional metrics
}
```

```go
type cephOSDLabel struct {
    Hostname string
    Type     string
}

type cephOSDDF struct {
    OSD   int64 `json:"osd"`
    Class string `json:"crush_weight"`
    // ... additional fields
}

type CephOSDPerfStat struct {
    Commit float64
    Apply  float64
}
```

--------------------------------

### RbdMirrorStatusCollector Struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Defines the collector structure for RBD mirror daemon status and health metrics.

```go
type RbdMirrorStatusCollector struct {
    conn          Conn
    logger        *logrus.Logger
    MirrorUp      *prometheus.Desc
    PoolsHealth   *prometheus.GaugeVec
    ImagesHealth  *prometheus.GaugeVec
}
```

--------------------------------

### PoolInfoCollector Definition and Internal Types

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Collector struct for pool configuration metrics and associated internal types.

```go
type PoolInfoCollector struct {
    conn             Conn
    logger         *logrus.Logger
    PGNum            *prometheus.GaugeVec
    PlacementPGNum   *prometheus.GaugeVec
    MinSize          *prometheus.GaugeVec
    ActualSize       *prometheus.GaugeVec
    QuotaMaxBytes    *prometheus.GaugeVec
    QuotaMaxObjects  *prometheus.GaugeVec
    StripeWidth      *prometheus.GaugeVec
    ExpansionFactor  *prometheus.GaugeVec
}
```

```go
const (
    poolReplicated = 1
    poolErasure    = 3
)

type poolInfo struct {
    Name string
    // Additional fields
}

type cephPoolInfo struct {
    Pools []struct {
        PoolID int `json:"pool"`
        PGNum  int `json:"pg_num"`
        // ... more fields
    } `json:"pools"`
}
```

--------------------------------

### Define cephFeatureGroup struct

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/09-types-reference.md

Represents client feature support counts from ceph features.

```go
type cephFeatureGroup struct {
    Features string `json:"features"`
    Release  string `json:"release"`
    Num      int    `json:"num"`
}
```

--------------------------------

### PoolInfoCollector Type Definition

Source: https://github.com/digitalocean/ceph_exporter/blob/main/_autodocs/06-component-collectors.md

Defines the structure of the PoolInfoCollector, including the connection, logger, and various Prometheus GaugeVec metrics.

```go
type PoolInfoCollector struct {
    conn              Conn
    logger            *logrus.Logger
    
    PGNum             *prometheus.GaugeVec
    PlacementPGNum    *prometheus.GaugeVec
    MinSize           *prometheus.GaugeVec
    ActualSize        *prometheus.GaugeVec
    QuotaMaxBytes     *prometheus.GaugeVec
    QuotaMaxObjects   *prometheus.GaugeVec
    StripeWidth       *prometheus.GaugeVec
    ExpansionFactor   *prometheus.GaugeVec
}
```