prometheus
Enhance writing_exporters.md: Add actionable examples, checklists, and improved structure
Description
Proposal:
I would like to significantly improve the writing_exporters.md documentation by adding concrete code examples, clarifying best practices, and introducing a more actionable structure for new and experienced exporter authors.
Motivation
The current writing_exporters.md is comprehensive but can be dense for newcomers and lacks practical, ready-to-use examples in several key sections. Given that this document is a primary reference for anyone building Prometheus exporters, improving its clarity and usability will have a high impact on the community and ecosystem.
Proposed Improvements
- Add concrete code examples for:
- Types & Labels (clarifying exporter vs. application labels)
- Help strings (with troubleshooting context)
- Scheduling (why exporters should not scrape on their own timers)
- Exporter landing pages (minimal HTML example)
- Introduce a quick-start checklist at the end for new exporter authors.
- Clarify and expand best practices with before/after code snippets.
- Improve document structure for easier navigation (e.g., section summaries, cross-links to related docs).
- Add a troubleshooting section for common mistakes and anti-patterns.
Implementation Plan
- Refactor the document to group related concepts and add section summaries.
- Add new and improved code examples in Go (and/or pseudo-code where appropriate).
- Insert a quick-start checklist and a “common mistakes” section.
- Cross-link to related documentation (e.g., instrumentation.md, naming.md).
- Solicit feedback from exporter maintainers and users for further improvements.
Refrences
[current_structure] https://prometheus.io/docs/instrumenting/writing_exporters/ [expected} https://prometheus.io/docs/prometheus/latest/getting_started/ [expected (even better)] https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/
Request for Feedback
- [ ] - Would maintainers and the community be open to a PR with these improvements?
- [ ] - Are there any specific pain points, requests, or recent exporter patterns you would like to see addressed in this update?
If approved, I will submit the changes as a single, well-structured PR with clear commit history and before/after documentation diffs.
