Files

Prometheus exporter for NixOS-specific metrics including:
- Generation collector: count, current, booted, age, config mismatch
- Flake collector: input age, input info, revision behind

Includes NixOS module, flake packaging, and documentation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-06 22:52:28 +01:00

2.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

nixos-exporter is a Prometheus exporter for NixOS-specific metrics. It exposes system state information that standard exporters don't cover: generation management, flake input freshness, and upgrade status.

Status: Implementation complete.

Build Commands

Run commands through the Nix development shell using nix develop -c:

# Build
nix develop -c go build ./...

# Run tests
nix develop -c go test ./...

# Run single test
nix develop -c go test -run TestName ./path/to/package

# Lint
nix develop -c golangci-lint run

# Vulnerability check
nix develop -c govulncheck ./...

# Test Nix build
nix build

# Run the binary (prefer this over go build + running binary)
# To pass arguments, use -- before them: nix run .#default -- --help
nix run .#default

Testing Procedures

Before committing, run the following checks:

nix develop -c go test ./... - Unit tests
nix develop -c golangci-lint run - Linting
nix develop -c govulncheck ./... - Vulnerability scanning
nix build - Verify nix build works

Architecture

Single binary with pluggable collectors:

nixos-exporter/
├── main.go                 # Entry point, HTTP server on :9971
├── collector/
│   ├── generation.go       # Core metrics (count, current, booted, age, mismatch)
│   └── flake.go            # Flake input freshness metrics (optional)
└── config/
    └── config.go           # YAML + CLI flag handling

Collectors

Generation collector (always enabled): Reads symlinks in /nix/var/nix/profiles/ and /run/current-system to determine generation state.

Flake collector (optional): Parses flake.lock JSON to extract lastModified timestamps per input.

Configuration

Supports YAML config file, CLI flags (--listen, --collector.flake, --flake.lock-path), and NixOS module integration via services.prometheus.exporters.nixos.

Commit Message Format

Use conventional commit format:

feat: add new feature
fix: fix a bug
docs: update documentation
refactor: refactor code without changing behavior
test: add or update tests
chore: maintenance tasks

Key Design Decisions

Go chosen for mature Prometheus client library and static binary output
Port 9971 allocated for this exporter
Follows nixpkgs services.prometheus.exporters.* module pattern
No root required - only reads symlinks and files

2.5 KiB Raw Blame History