Torjus Håkestad
9c29505814
Add a new info metric that exposes the current system's flake revision and the latest remote revision as labels. This makes it easier to see exactly which revision is deployed vs available. Also adds version constant to Go code and extracts it in flake.nix, providing a single source of truth for the version. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
103 lines
3.0 KiB
Markdown
103 lines
3.0 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
|
|
```
|
|
|
|
## 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
|
|
|
|
Update the `const version` in `main.go`. The Nix build extracts the version from there automatically.
|
|
|
|
**When to bump**: If any Go code has changed, bump the version before committing. Do this automatically when asked to commit. On feature branches, only bump once per branch (check if version has already been bumped compared to master).
|
|
|
|
## 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
|