node_exporter/AGENTS.md

AGENTS.md

Rules

• Collector availability is controlled by Go build tags and OS-specific filenames; check //go:build lines before assuming a collector exists on the current OS.
• Use kingpin.Flag(), never kingpin.Flag().Envar(): the project has a "one-way-to-configure" policy of CLI flags only. Runtime env vars (GOMAXPROCS) and deprecated collectors are the only historical exceptions; maintainers have rejected env var flags for new code.
• Collector code must not shell out: .golangci.yml denies os/exec outside tests, and CONTRIBUTING.md says collectors may read /proc, /sys, use syscalls, or local sockets only.
• Keep metrics in the node namespace, follow the Prometheus metric naming conventions, and update README collector tables when adding, removing, enabling, disabling, or changing collector flags.
• Parse /proc files via the procfs dependency rather than adding ad-hoc parsing in a collector; extend procfs upstream if a needed file isn't covered yet.

Build And Test Commands

• Full CI-like local check is make; it runs vet, metric/rule checks, shared Prometheus checks, 32-bit tests when supported, and Linux e2e only.
• Focused unit tests: go test ./collector -run TestName or go test ./... -run TestName; use make test when tests need unpacked fixtures.
• make test unpacks collector/fixtures/sys.ttar and collector/fixtures/udev.ttar, then runs go test -short $(test-flags) ./....
• make build uses promu and writes ./node_exporter, which make test-e2e expects; root tests in node_exporter_test.go skip unless a binary exists at $GOPATH/bin/node_exporter.
• make test-e2e is Linux-only from the main Makefile path; it depends on make build, fixture unpacking, and make tools.
• make checkmetrics downloads/uses promtool and checks collector/fixtures/e2e-output*.txt; run it after metric output changes.
• Lint/format shortcuts: make format, make lint, make lint-fix, make yamllint, make unused.

Fixtures And Generated Outputs

• Do not edit unpacked collector/fixtures/sys/ or collector/fixtures/udev/ as source of truth; update collector/fixtures/sys.ttar and collector/fixtures/udev.ttar with make update_fixtures.
• To refresh e2e metric golden files, run make build tools first, then ./end-to-end-test.sh -u; it writes the appropriate collector/fixtures/e2e-output*.txt.
• end-to-end-test.sh filters collector flags by OS/build context using tools/tools match, so an ignored flag in e2e may mean the collector is build-tag-gated for that platform rather than broken (see Rules).

Toolchain Notes

• go.mod's Go directive is not the source of truth for the toolchain version CI actually uses; check the workflow's setup-go step and .promu.yml/.promu-cgo.yml, which can each pin a different version.
• Makefile.common is shared Prometheus infrastructure; comments say to open PRs against prometheus/prometheus/Makefile.common for generic changes.
• golangci-lint version comes from make print-golangci-lint-version (GOLANGCI_LINT_VERSION in Makefile.common), not from a locally installed default.
• Docker builds produce per-arch images named $(DOCKER_REPO)/node-exporter-linux-<arch>:$(DOCKER_IMAGE_TAG) and cover Dockerfile plus Dockerfile.* variants.

Node Mixin

• Mixin checks are separate: CI runs make promtool, make -C docs/node-mixin clean, make -C docs/node-mixin jb_install, then make -C docs/node-mixin and expects git diff --exit-code.
• docs/node-mixin requires jsonnet, jsonnetfmt, and jb; generated files are node_alerts.yaml, node_rules.yaml, and dashboards_out/.