btrfs_elixporter

A Prometheus metrics exporter for btrfs filesystem statistics, written in Elixir.

Overview

btrfs_elixporter reads btrfs filesystem statistics from the Linux kernel's sysfs interface (/sys/fs/btrfs/) and exposes them in Prometheus format over HTTP. It supports both daemon mode for continuous monitoring and oneshot mode for debugging.

Tutorial Project

This project serves as an Elixir learning resource. The codebase is comprehensively documented to teach Elixir concepts, patterns, and best practices. If you're learning Elixir, this project demonstrates:

• OTP applications and supervision trees
• GenServer behavior
• Pattern matching and guards
• Error handling strategies
• HTTP server implementation
• File I/O and directory traversal
• String parsing and data transformation
• Testing with ExUnit
• Documentation with ExDoc

See docs/code/README.md for detailed tutorial documentation.

Features

• Auto-discovery: Automatically discovers and monitors all btrfs filesystems
• Complete metrics: Exports all available sysfs statistics
• Smart consolidation: Groups related metrics with labels (Prometheus best practices)
• Daemon mode: Long-running HTTP server for continuous monitoring
• Oneshot mode: Read-once output for debugging and testing
• Configurable caching: Optional caching to handle high request rates
• Error tracking: Failures tracked as metrics, not silent errors
• IPv6 support: Full IPv4 and IPv6 support

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd btrfs_elixporter

# Get dependencies
mix deps.get

# Compile
mix compile

# Run tests
mix test

Running in Daemon Mode

# Default: localhost:9573, /metrics endpoint
mix run --no-halt

# Custom port
BTRFS_EXPORTER_PORT=9100 mix run --no-halt

# Custom bind address (all interfaces)
mix run --no-halt -- --bind 0.0.0.0

Access metrics at: http://localhost:9573/metrics

Running in Oneshot Mode

# Read from live sysfs and print to stdout
mix run -- --oneshot

# Read from test fixture
mix run -- --oneshot --path testsuite/test1/btrfs

Running with Docker/Podman

Build and run as a container:

# Build the container
docker build -t btrfs_elixporter:latest -f Containerfile .

# Run in daemon mode
docker run -d \
  --name btrfs_exporter \
  -p 9573:9573 \
  -v /sys/fs/btrfs:/mnt/btrfs-sysfs:ro \
  btrfs_elixporter:latest

See CONTAINER.md for complete container usage guide.

Configuration

Configuration supports three sources with precedence: CLI flags > Environment variables > Defaults

Command-Line Flags

--oneshot                  # Enable oneshot mode (read once, print, exit)
--path <path>              # Sysfs root path (default: /sys/fs/btrfs)
--port <port>              # HTTP server port (default: 9573)
--bind <address>           # Bind address (default: 127.0.0.1 and ::1)
--endpoint <path>          # Metrics endpoint (default: /metrics)
--cache-duration <seconds> # Cache TTL in seconds (default: 1)

Environment Variables

BTRFS_EXPORTER_PATH           # Sysfs path
BTRFS_EXPORTER_PORT           # HTTP port
BTRFS_EXPORTER_BIND           # Bind address
BTRFS_EXPORTER_ENDPOINT       # Metrics endpoint path
BTRFS_EXPORTER_CACHE_DURATION # Cache duration

Examples

# Daemon on custom port
mix run --no-halt -- --port 9100

# Oneshot with test data
mix run -- --oneshot --path testsuite/test2/btrfs

# Disable caching (always fresh data)
mix run --no-halt -- --cache-duration 0

# External access (security warning: no authentication!)
mix run --no-halt -- --bind 0.0.0.0 --port 9573

Metrics

All btrfs sysfs statistics are exported as Prometheus metrics. Examples:

# Allocation metrics (consolidated with labels)
btrfs_allocation_bytes{fsid="...", type="data", state="used"} 123456789
btrfs_allocation_bytes{fsid="...", type="metadata", state="reserved"} 0

# RAID profile metrics
btrfs_allocation_raid_bytes{fsid="...", type="data", profile="raid1", state="total"} 165295423488

# Device errors (consolidated)
btrfs_device_errors_total{fsid="...", device_id="1", error_type="write"} 0
btrfs_device_errors_total{fsid="...", device_id="1", error_type="read"} 0

# Commit statistics
btrfs_commit_stats_commits_total{fsid="..."} 12
btrfs_commit_stats_duration_milliseconds{fsid="...", statistic="last"} 12
btrfs_commit_stats_duration_milliseconds{fsid="...", statistic="max"} 305

# Cache metadata
btrfs_exporter_last_poll_timestamp_seconds{fsid="..."} 1728345678

# Error tracking
btrfs_error_lastTS{error="read_error", path="...", fsid="..."} 1728345678
btrfs_error_count{error="read_error", path="...", fsid="..."} 5

See SysfsMetricsMapping.md for complete transformation rules.

Documentation

Technical Specifications

• TechSpec.md - Functional and non-functional requirements
• SysfsMetricsMapping.md - Sysfs to Prometheus transformation rules
• current_plan.md - Development plan and task tracking
• Learning_log.md - Design decisions and learnings

Tutorial Documentation

• docs/code/README.md - Tutorial documentation overview
• docs/code/modules/ - Per-module detailed documentation
• docs/code/patterns/ - Elixir pattern guides

Generated API Documentation

# Generate HTML documentation
mix docs

# Open in browser
open doc/index.html

Testing

The project includes comprehensive unit tests (121 tests, 0 failures):

# Run all tests
mix test
# Output: 121 tests, 0 failures (3.6s)

# Run with coverage
mix test --cover

# Run specific test file
mix test test/btrfs_elixporter/config_test.exs

# Run tests with trace output
mix test --trace

# Regenerate documentation
mix docs

Test coverage:

• Config: 44 tests (CLI parsing, ENV vars, precedence)
• SysfsReader: 28 tests (filesystem discovery, file I/O, symlink handling)
• DataCollector: 19 tests (parsing, consolidation, Synology extensions)
• MetricsFormatter: 16 tests (Prometheus format, escaping, sorting)
• MetricsCache: 12 tests (ETS caching, TTL expiry)

Test data is provided in testsuite/ with various btrfs configurations (RAID levels, multiple filesystems, qgroups, vendor extensions).

Development

# Format code
mix format

# Check formatting
mix format --check-formatted

# Run type checking (if Dialyzer configured)
mix dialyzer

# Interactive shell with project loaded
iex -S mix

Architecture

High-level components:

1. Application Supervisor - OTP application entry point
2. HTTP Server - Serves /metrics endpoint
3. Metrics Collector - Discovers filesystems and reads sysfs
4. Sysfs Reader - File I/O abstraction (supports real and test paths)
5. Metrics Formatter - Converts to Prometheus text format
6. Cache Manager - Optional TTL-based caching
7. Error Tracker - Accumulates error metrics
8. Config Manager - Multi-source configuration

See docs/code/architecture.md for detailed design (to be written during implementation).

Contributing

1. Read the tutorial documentation to understand the codebase
2. Follow existing patterns and conventions
3. Add inline documentation (@moduledoc, @doc)
4. Update tutorial docs for significant changes
5. Add tests for new functionality
6. Ensure all tests pass: mix test
7. Format code: mix format

License

[TODO: Add license]

Authors

[TODO: Add authors]

Acknowledgments

• btrfs kernel developers for the sysfs interface
• Prometheus project for exporter guidelines
• Elixir community for excellent documentation standards