nixos-exporter/CLAUDE.md

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:

1. nix develop -c go test ./... - Unit tests
2. nix develop -c golangci-lint run - Linting
3. nix develop -c govulncheck ./... - Vulnerability scanning
4. 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

Version Bumping

Follow semantic versioning:

• Patch (0.0.x): Bugfixes
• Minor (0.x.0): Non-breaking changes adding features
• Major (x.0.0): Breaking changes

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