mirror of
https://github.com/prometheus-community/windows_exporter.git
synced 2026-10-17 10:09:05 +02:00
docs: add shared agent instructions and Claude guidance (#2603)
Signed-off-by: Jan-Otto Kröpke <mail@jkroepke.de>
This commit is contained in:
Jan-Otto Kröpke
@@ -0,0 +1,207 @@
|
||||
# Agent instructions
|
||||
|
||||
Follow [`CONTRIBUTING.md`](CONTRIBUTING.md) for all changes. These instructions
|
||||
apply throughout the repository; also read any `AGENTS.md` in the area you edit.
|
||||
|
||||
## Project and source map
|
||||
|
||||
`windows_exporter` is a Go Prometheus exporter for Windows. Most collectors and
|
||||
native bindings require Windows; a successful cross-build does not validate
|
||||
their runtime behavior.
|
||||
|
||||
- [`cmd/windows_exporter`](cmd/windows_exporter): executable, flags, process
|
||||
settings, Windows service startup and shutdown.
|
||||
- [`pkg/collector`](pkg/collector): collector registration, configuration,
|
||||
initialization, filtered views, scrape scheduling and resource ownership.
|
||||
- [`internal/collector`](internal/collector): built-in collectors. Each implements
|
||||
`GetName`, `Build`, `Collect` and `Close` from
|
||||
[`pkg/collector/types.go`](pkg/collector/types.go).
|
||||
- [`internal/pdh`](internal/pdh) and [`internal/pdh/registry`](internal/pdh/registry):
|
||||
performance counter queries and perflib decoding. [`internal/mi`](internal/mi)
|
||||
provides Management Infrastructure queries; [`internal/ole`](internal/ole) and
|
||||
[`internal/headers`](internal/headers) contain native Windows bindings.
|
||||
- [`internal/config`](internal/config), [`internal/httphandler`](internal/httphandler)
|
||||
and [`internal/log`](internal/log): YAML/CLI configuration, HTTP scraping and
|
||||
logging.
|
||||
- [`docs/collector.<name>.md`](docs): collector flags, metric names, types, labels
|
||||
and examples. [`docs/collector-template.md`](docs/collector-template.md) is the
|
||||
documentation template.
|
||||
- [`contrib/mixin`](contrib/mixin): Jsonnet recording rules, alerts and dashboard
|
||||
sources. [`dashboard`](dashboard) contains the generated Grafana dashboard;
|
||||
[`docs/runbooks`](docs/runbooks) documents the alerts.
|
||||
- [`installer`](installer), [`kubernetes`](kubernetes) and [`tools`](tools): MSI
|
||||
packaging, deployment examples, CI fixtures and end-to-end helpers.
|
||||
|
||||
New collectors need discussion with maintainers first. Prefer the configurable
|
||||
`performancecounter` collector where it can provide the requested metrics, as
|
||||
described in `CONTRIBUTING.md`.
|
||||
|
||||
## Development and checks
|
||||
|
||||
Use the Go version specified in [`go.mod`](go.mod) and the linter version pinned
|
||||
in [`Makefile`](Makefile). Do not change versions to work around a local tooling
|
||||
problem. Follow [`.golangci.yaml`](.golangci.yaml), [`.editorconfig`](.editorconfig)
|
||||
and [`.gitattributes`](.gitattributes); keep LF line endings and the existing
|
||||
license headers. Use structured `slog` attributes and the existing Windows API
|
||||
wrappers (`golang.org/x/sys/windows`, `NewLazySystemDLL`).
|
||||
|
||||
Before committing, run the repository checks from its root:
|
||||
|
||||
```sh
|
||||
make fmt
|
||||
make lint
|
||||
make test
|
||||
```
|
||||
|
||||
If GNU Make is unavailable on Windows, use the equivalent commands from the
|
||||
current Makefile. Its current formatter and linter commands are:
|
||||
|
||||
```powershell
|
||||
go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.14.0 fmt
|
||||
go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.14.0 run ./...
|
||||
go test ./...
|
||||
```
|
||||
|
||||
For collector or concurrency changes, also run the affected packages natively
|
||||
on Windows with `go test -race -count=1 -timeout=10m <packages>`. Add regression
|
||||
tests for behavior changes and benchmarks for performance improvements. Check
|
||||
actual emitted metric values, types and labels through registry gathering;
|
||||
configuration or struct assertions alone do not prove publication is correct.
|
||||
|
||||
Read [`docs/ci-testing.md`](docs/ci-testing.md) before changing fixtures or test
|
||||
skip rules. `WINDOWS_EXPORTER_TEST_COLLECTORS` lists collectors provisioned by CI;
|
||||
their failures must fail tests. Optional roles may be absent locally. Report
|
||||
skipped coverage and checks blocked by missing tools, permissions, services or
|
||||
network access in the PR. Do not claim that cross-compilation or a fixture test
|
||||
exercised a live Windows role.
|
||||
|
||||
## Collector implementation rules
|
||||
|
||||
- Preserve metric names, label sets, types, units, defaults and configuration
|
||||
compatibility unless the change intentionally updates that contract. Update
|
||||
the corresponding collector documentation and affected queries together.
|
||||
Follow existing deprecation patterns when replacing published metrics.
|
||||
- Determine metric types per counter, using `pdh.Collector.MetricType` where
|
||||
appropriate. Raw PDH values can be cumulative numerators, ticks or counts,
|
||||
even when the Windows counter name says average, percentage or seconds.
|
||||
Convert units explicitly; expose the base/operation count needed for ratios.
|
||||
Never publish an invalid sample as zero: that can look like a counter reset.
|
||||
- Keep the typed PDH/registry collectors and `perfdata` tags. Preserve duplicate
|
||||
instance occurrences within a sample; their suffixes are not stable identities.
|
||||
Do not remove every name ending in `_Total`: legitimate process and database
|
||||
names can use that suffix. Use the shared aggregate-instance policy.
|
||||
- Keep `Build`, `Collect` and `Close` serialized for each collector instance.
|
||||
Filtered `WithCollectors` views share execution state and do not own shutdown;
|
||||
the original `Collection` owns collectors and MI resources. A timed-out call
|
||||
may still be running: prevent overlap, drain late metrics and do not free its
|
||||
resources while it runs. Honor the supplied scrape budget in blocking APIs.
|
||||
- Release resources after partial initialization and on error paths. A non-nil
|
||||
PDH collector returned with an error still belongs to the caller and must be
|
||||
closed. Sub-collector cleanup closures must read the initialized field when
|
||||
called; method values captured before initialization can retain nil receivers.
|
||||
Stop background workers before releasing the resources they use, and recover
|
||||
panics inside the goroutine that can panic.
|
||||
- Inspect every independent cause in joined errors. An expected no-data or
|
||||
unsupported-subsystem error must not hide an unrelated failure. Preserve valid
|
||||
metrics from successful parts of a scrape and the existing child-success
|
||||
metrics for collectors with sub-collectors.
|
||||
- Match native function signatures, struct layouts and buffer-size units to the
|
||||
Windows API contract. Query required buffer sizes safely and retry when they
|
||||
grow. Distinguish bytes from UTF-16 characters, signed integers from bit
|
||||
patterns, and MI NULL values from populated unions. Respect borrowed/owned
|
||||
pointers, allocator-specific cleanup and COM thread initialization; use the
|
||||
native COM helpers rather than restoring the removed `go-ole` dependency.
|
||||
- Keep CLI and YAML validation consistent. Reject unknown fields, unsupported
|
||||
sub-collector names and invalid values; preserve CLI precedence and repeated
|
||||
flag/list behavior. Changes to config shapes also need schema, flag parsing
|
||||
and documentation updates.
|
||||
- For textfiles, keep HELP/type metadata consistent across files and preserve
|
||||
unrelated valid series when reporting duplicates or parse failures. Publish
|
||||
producer output by replacing a temporary file in the same directory. File
|
||||
mtime indicates accepted input; a producer's last-success timestamp indicates
|
||||
data freshness. Use emitted exporter/collector signals in alert examples.
|
||||
|
||||
These rules draw on the latest 150 PRs reviewed for this guide (#2451 through
|
||||
#2602, including open and closed proposals). Representative merged changes are
|
||||
[scrape lifecycle #2541](https://github.com/prometheus-community/windows_exporter/pull/2541),
|
||||
[filtered ownership #2587](https://github.com/prometheus-community/windows_exporter/pull/2587),
|
||||
[PDH types and validity #2543](https://github.com/prometheus-community/windows_exporter/pull/2543),
|
||||
[MI return values #2537](https://github.com/prometheus-community/windows_exporter/pull/2537),
|
||||
[native COM #2551](https://github.com/prometheus-community/windows_exporter/pull/2551)
|
||||
and [joined collection errors #2574](https://github.com/prometheus-community/windows_exporter/pull/2574).
|
||||
Check the current source and PR status before treating an open proposal as
|
||||
implemented behavior.
|
||||
|
||||
## Live exporter validation
|
||||
|
||||
The development environment may already have an exporter running at
|
||||
`http://localhost:9182`. Check availability and `windows_exporter_build_info`
|
||||
before using it as a baseline; it may have a different revision, configuration
|
||||
or enabled collector set from your checkout.
|
||||
|
||||
```powershell
|
||||
(Invoke-WebRequest -Uri 'http://localhost:9182/metrics' -TimeoutSec 30).Content
|
||||
(Invoke-WebRequest -Uri 'http://localhost:9182/metrics?collect[]=cpu' -TimeoutSec 30).Content
|
||||
```
|
||||
|
||||
Inspect `windows_exporter_collector_success`,
|
||||
`windows_exporter_collector_duration_seconds` and
|
||||
`windows_exporter_collector_timeout`, plus the affected metric families. HTTP 200
|
||||
alone does not mean every collector succeeded. PDH rate counters need a second
|
||||
sample after initialization.
|
||||
|
||||
To validate changed code, build a separate executable and run it on an unused
|
||||
port with the relevant collectors, then scrape it from another shell:
|
||||
|
||||
```powershell
|
||||
go build -o windows_exporter.dev.exe ./cmd/windows_exporter/
|
||||
.\windows_exporter.dev.exe --web.listen-address=127.0.0.1:9183 --collectors.enabled=cpu
|
||||
```
|
||||
|
||||
Adjust the collector list for the change. Leave the existing exporter instance
|
||||
running unless the user requests changes to it.
|
||||
|
||||
## Dashboards, rules and runbooks
|
||||
|
||||
Read [`contrib/mixin/README.md`](contrib/mixin/README.md) and
|
||||
[`dashboard/README.md`](dashboard/README.md) before editing monitoring artifacts.
|
||||
Edit the Jsonnet/Grafonnet source under `contrib/mixin/dashboards`, including its
|
||||
tab modules and shared builders, and regenerate
|
||||
`dashboard/windows-exporter-dashboard.json`. Do not hand-edit generated JSON.
|
||||
|
||||
From `contrib/mixin`, install the pinned tools with `make tools`, ensure they
|
||||
are on `PATH`, then run `make fmt`, `make generate`, `make check-dashboards` and
|
||||
`make test`. Keep generated artifacts in sync. The tests cover Jsonnet format,
|
||||
dashboard parity, promtool rules/tests, offline pint lint and runbook coverage.
|
||||
Preserve target/device labels, apply counter rates before aggregation, and
|
||||
handle zero denominators. Keep optional-role alerts configurable and provide a
|
||||
runbook for each alert. Check required collector availability and the Grafana
|
||||
version documented by the dashboard.
|
||||
|
||||
## Pull requests
|
||||
|
||||
Branch from current upstream `main`, keep commits focused and sign off each
|
||||
commit with `git commit -s` for the DCO. Preserve unrelated local changes; use a
|
||||
separate worktree when needed. Follow [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md)
|
||||
and use the `subsystem: description` title format required by
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) and
|
||||
[`.github/workflows/pr-check.yaml`](.github/workflows/pr-check.yaml).
|
||||
Explain the problem, resulting behavior and validation, including any limits.
|
||||
|
||||
## Pull request labels
|
||||
|
||||
Before merging, apply at least one label from [`.github/release.yml`](.github/release.yml):
|
||||
|
||||
- `💥 breaking-change`: breaking changes
|
||||
- `✨ enhancement`: user-visible functionality
|
||||
- `🐞 bug`: fixes
|
||||
- `🛠️ dependencies`: dependency updates
|
||||
- `📖 docs`: documentation
|
||||
- `chore`: internal performance work, tests, CI, or maintenance
|
||||
|
||||
Add `💥 breaking-change` alongside any other applicable label. Labeling is an
|
||||
AI-agent-only operation; do not tell external contributors to apply labels.
|
||||
|
||||
Keep this guide accurate when an authorized change reveals a useful repository
|
||||
convention or pitfall. Put detailed component guidance in a scoped `AGENTS.md`
|
||||
when needed, and keep `CLAUDE.md` as a pointer to the shared instructions.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Claude Code guidance
|
||||
|
||||
Read [`AGENTS.md`](AGENTS.md) for this repository's shared agent instructions,
|
||||
development workflow, implementation rules and pull request requirements.
|
||||
Follow [`CONTRIBUTING.md`](CONTRIBUTING.md) for all changes.
|
||||
|
||||
## Component guidance
|
||||
|
||||
Also read any `AGENTS.md` in the directories you work on. Scoped instructions
|
||||
describe the conventions and pitfalls of those components.
|
||||
|
||||
## Maintaining guidance
|
||||
|
||||
When an authorized change establishes a useful implementation detail or debugging
|
||||
technique, update the relevant `AGENTS.md`. Add scoped guidance when a component
|
||||
needs more detail, and keep shared project rules in the root `AGENTS.md` so they
|
||||
stay consistent across agents.
|
||||
Reference in New Issue
Block a user