Torjus Håkestad
f637da487c
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>
91 lines
2.5 KiB
Markdown
91 lines
2.5 KiB
Markdown
# 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`:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## 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
|