Cleanup opportunities

Concrete, low-risk maintenance work that someone could pick up. Numbers are derived from the current main (16034ecf3).

TODO / FIXME / HACK

Tag	Approximate count	Where
TODO	319	Across 126 files — concentrated in tsdb/ and promql/.
FIXME	7	Mostly in tsdb/ and model/labels/.
HACK	0–<10	Used very sparingly.

The TODOs are not all equal; some are author signatures of design decisions ("TODO(jesusvazquez): These should be updated after garbage collection"), some are genuine future work. A targeted "audit and triage TODOs in <area>" sub-PR is welcome but should be discussed before opening — see AGENTS.md on scope discipline.

Complexity hotspots

These files are large and hot. New work in them is high-velocity, but a refactor pass would also be welcome (with benchmarks):

File	Lines (approx)	Notes
promql/engine.go	4,743	The query engine. Well-tested but dense.
cmd/prometheus/main.go	2,202	The server entry point. Touches every subsystem.
storage/remote/queue_manager.go	2,321	The remote write queue manager.
web/api/v1/api.go	2,352	API router + every handler.
tsdb/db.go	2,632	Top-level TSDB; compaction + retention + reload.
tsdb/head.go	2,763	Head data structure + GC.
tsdb/head_append.go	2,400+	V1 append path.
tsdb/head_wal.go	1,800+	WAL replay logic.
model/labels/regexp.go	1,400	Specialised regex matcher; hot.

The longest test files are tsdb/db_test.go (9,700), tsdb/head_test.go (8,300), and tsdb/db_append_v2_test.go (~7,700). Most are scenario-driven; splitting into themed sub-files would help readability without changing coverage.

Dead-code candidates

• web/ui/react-app/ — the legacy 2.x UI is still bundled. It can be removed when the team decides the deprecation window has elapsed (no firm timeline).
• consoles/ (under documentation/) — the legacy console template UI. Already unused by most operators; eventual removal candidate.
• tsdb/ files with only legacy-format readers (e.g. some pre-2.21 tmp dir handling in tsdb/db.go).

The real determinator is git grep -l '<symbol>' over the call graph; many "obviously dead" candidates turn out to have a test or a backwards-compat path.

V1 appender removal

Once storage.Appender (V1) is removed (target Q2 2026), several files become smaller or disappear:

• storage/interface.go::Appender (the V1 type itself).
• tsdb/head_append.go (the V1 head appender).
• The V1 path in scrape/scrape.go.
• storage/teststorage V1 helpers.

Dependencies

The go.mod file is large (~270 lines). Notable areas:

• AWS SDK v2 brings ~20 transitive modules.
• Kubernetes client-go brings ~20 modules.
• The Azure SDK packages (Azure/azure-sdk-for-go/...) are extensive.

Renovate keeps these moving. The 3.10 PR #17736 (build-tag SD removal) was partly motivated by giving operators a way to drop the SDK weight without forking the project.

Documentation parity

• docs/feature_flags.md — periodically drifts from the actual flag set in cmd/prometheus/main.go. A periodic audit ("does every --enable-feature flag have a docs entry?") catches this. The authoritative list of flags is the kingpin parser; a make target could automate parity, similar to make cli-documentation.
• docs/configuration/configuration.md — when a new SD is added, the corresponding <scrape_config> and <alertmanager_config> entries must be hand-edited. There is no generator. A minor PR could turn the existing field structures into a generator.

Test infrastructure refactors

• synctest adoption — the project has started migrating flake-prone tests to Go's synctest (#17768-era). Many time.Sleep-based tests remain. Per-area migration PRs are welcome.
• testify adoption is uneven — older files still use t.Errorf. Not worth migrating in unrelated PRs, but new tests should use require/assert.

Generated code

• prompb/types.pb.go (112 KB) and prompb/remote.pb.go (44 KB) are generated and shipped. They cannot be hand-edited. make proto regenerates them; CI verifies the result.
• promql/parser/generated_parser.y.go (~67 KB) is generated from the goyacc grammar. Same pattern.
• web/ui/mantine-ui/src/promql/functionSignatures.ts and functionDocs.tsx are generated by make generate-promql-functions.

These files inflate repo size but are intentionally tracked so that consumers don't need the generators.

Where not to "clean up"

• The duplicated style files in web/ui/react-app/ and web/ui/mantine-ui/ reflect the deprecation story; do not de-duplicate them.
• The "two go.mod files" pattern (internal/tools/, documentation/examples/remote_storage, web/ui/mantine-ui/src/promql/tools, compliance) is intentional — they isolate tool dependencies from the main module. make update-all-go-deps keeps them in sync.

If you're picking up a cleanup PR, run it past the area maintainer first. The repo's scope-discipline rule applies even more strictly to refactors.