This repository was archived by the owner on Jul 28, 2026. It is now read-only.
RFC: Design in the open #1055
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,21 +1,10 @@ | ||
| # Grafana Agent Documentation | ||
|
|
||
| This directory contains documentation for Grafana Agent. It is split into two | ||
| parts: | ||
|
|
||
| * `user/`: Documentation for users. This directory is hosted on | ||
| [grafana.com/docs/agent](https://grafana.com/docs/agent/latest/) and we | ||
| recommend interacting with it there instead of viewing the markdown on | ||
| Github. | ||
| * `rfcs/`: RFCs for proposals relating to Grafana Agent. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Title | ||
|
|
||
| * Date: YYYY-MM-DD | ||
| * Author: Full Name (@github_username) | ||
| * PR: [grafana/agent#XXXX](https://github.com/grafana/agent/pull/XXXX) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,141 @@ | ||||||
| # Designing in the Open | ||||||
|
|
||||||
| * Date: 2021-11-02 | ||||||
| * Author: Robert Fratto (@rfratto) | ||||||
| * PR: [grafana/agent#1055](https://github.com/grafana/agent/pull/1055) | ||||||
|
|
||||||
| ## Summary | ||||||
|
|
||||||
| Many open source projects start behind closed doors, where it's designed, | ||||||
| prototyped, and tested before being released publicly. This can be true | ||||||
| regardless of why the project is being made; even personal side projects likely | ||||||
| start by someone designing alone. | ||||||
|
|
||||||
| Meanwhile, many open source projects might want to create a community of | ||||||
| developers. Much of the beauty of succesful open source projects originates | ||||||
| from the varied backgrounds of its contributors: different people with | ||||||
| different use cases combining together to make a widely useful piece of | ||||||
| software. | ||||||
|
|
||||||
| However, even with an intent to foster a community of developers, it's natural | ||||||
| to accidentally build a habit from the closed-door design process. Even when | ||||||
| once-private proposals are made public, potential external contributors can | ||||||
| find themselves simply as spectators: | ||||||
|
|
||||||
| * Initial design is gated to core maintainers, in particular if they all work | ||||||
| for the same company. This leaves less room for new people to help out. | ||||||
| * New concerns are less impactful if the proposal already receieved core | ||||||
| maintainer consensus. | ||||||
| * Historical proposals with context and discussions become hard to find. | ||||||
|
|
||||||
| I believe it takes a deliberate inversion of process to foster community | ||||||
| participation. This document proposes how Grafana Agent will utilize public | ||||||
| spaces for its primary home for future design proposals. | ||||||
|
|
||||||
| ## Goals | ||||||
|
rfratto marked this conversation as resolved.
|
||||||
|
|
||||||
| * Outline options for proposing changes to Grafana Agent | ||||||
| * Lower the barrier to entry for interested parties to become maintainers | ||||||
|
|
||||||
| ## Non-Goals | ||||||
|
|
||||||
| * Enforce that every change originates from a fully public proposal or | ||||||
| discussion. While all maintainers and contributors will be encouraged to | ||||||
| design openly, there may be legal, security, privacy, or business reasons | ||||||
| that prevent some or all context from being made public. | ||||||
|
|
||||||
| * Be overly prescriptive: too many rules can hinder adoption of a process. This | ||||||
| document outlines intention, not hard policy. | ||||||
|
|
||||||
| ## Proposal | ||||||
|
|
||||||
| Public proposals may take one of two forms: | ||||||
|
|
||||||
| * Issue proposals | ||||||
| * RFC PR proposals (e.g., this document) | ||||||
|
|
||||||
| ### Issues | ||||||
|
|
||||||
| Issues are the quickest path towards proposing a change. Issue proposals must | ||||||
| be opened at the [grafana/agent issues page](https://github.com/grafana/agent/issues). | ||||||
|
|
||||||
| There are no strict set of rules for issue-based proposals, but authors are | ||||||
| recommended to prefix the issue title with `Proposal:` so it may be found more | ||||||
| easily. | ||||||
|
|
||||||
| ### RFC PRs | ||||||
|
|
||||||
| RFC PR proposals must at least: | ||||||
|
|
||||||
| * Be placed in the `docs/rfcs` folder of the `grafana/agent` repository | ||||||
| * Have a lowercase filename in hyphen-case with an `.md` extension | ||||||
| * Prefix the filename with the RFC ID | ||||||
| * ID `xxxx` may be initially used until the final ID is known | ||||||
| * Contain valid markdown | ||||||
| * Start with the title of the proposal | ||||||
| * Contain a bullet point list of metadata of: | ||||||
| * The date the proposal was written | ||||||
| * The list of authors, with their names and GitHub usernames | ||||||
| * The PR where the proposal was posted | ||||||
|
|
||||||
| `0000-template.md` contains a template to use for writing proposals that | ||||||
| conforms to these rules. | ||||||
|
|
||||||
| The remainder of the proposal may be formatted however the author wishes. Some | ||||||
| example sections in the RFC may be: | ||||||
|
|
||||||
| * Summary: What is the background that lead to this proposal? | ||||||
| * Goals: What are the main goals of the proposal? | ||||||
| * Non-Goals: What _aren't_ the main goals of the proposal? | ||||||
| * Proposal: What is the proposal? | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
Contributor
Author
There was a problem hiding this comment. I'm not sure what's being suggested here. Why |
||||||
| * Pros/Cons: | ||||||
| * Pros: What are the upsides to this proposal? | ||||||
| * Cons: What are the downsides to this proposal? | ||||||
| * Considered Alternatives: Why is this proposal the best path forward? What | ||||||
| were the alternatives? | ||||||
| * Open Questions: What questions still need to be answered? | ||||||
| * Prior Art: What was this proposal based on, if anything? | ||||||
|
|
||||||
| #### RFC Review | ||||||
|
|
||||||
| RFCs should be opened as a PR to grafana/agent, ideally prefixed in the PR | ||||||
| title with `RFC:` to easily identify it amongst other PRs. | ||||||
|
|
||||||
| ### Google Docs Proposals | ||||||
|
|
||||||
| Google Docs may be useful for early feedback rounds during a proposal. However, | ||||||
| it is not recommended for the permanent home of a proposal: | ||||||
|
|
||||||
| * Change and comment history may not be available to all viewers. | ||||||
|
|
||||||
| * The file owner may delete the proposal, leading to a gap in historical | ||||||
| context. | ||||||
|
|
||||||
| Google Docs proposals will be permitted if linked to from an issue proposal. | ||||||
| Google Doc proposals must be converted into an RFC proposal prior to formally | ||||||
| accepting the proposal. Enforcing this ensures that historical context is | ||||||
| recorded, though it is still not ideal as it discards comment history. | ||||||
|
|
||||||
| ## Accepting Proposals | ||||||
|
|
||||||
| All readers are encouraged to engage in reviewing proposals. However, whether a | ||||||
| proposal is accepted is determined by [rough consensus][] of the Grafana Agent | ||||||
| governance team. External contributors may eventually be invited to [join the | ||||||
| governance team][governance] if they have a history of making ongoing | ||||||
| contributions to the project or community. | ||||||
|
|
||||||
| ## Considered alternatives | ||||||
|
|
||||||
| A few existing public proposal processes have been examined for inspiration: | ||||||
|
|
||||||
| * [IETF's RFCs](https://www.ietf.org/standards/rfcs/) | ||||||
| * [Rust's RFCs](https://github.com/rust-lang/rfcs) | ||||||
| * [Joyent's Requests for Discussions](https://github.com/joyent/rfd) | ||||||
| * [OpenTelemetry's OTEPs](https://github.com/open-telemetry/oteps) | ||||||
|
rfratto marked this conversation as resolved.
|
||||||
| * [Kubernetes Enhancement Proposals (KEPs)](https://github.com/kubernetes/enhancements) | ||||||
|
|
||||||
| All of these processes are similar, but in the end, the current objective is to | ||||||
| start collecting proposals publicly rather than to be prescriptive yet. | ||||||
|
|
||||||
| [rough consensus]: https://github.com/grafana/agent/blob/main/GOVERNANCE.md#technical-decisions | ||||||
| [governance]: https://github.com/grafana/agent/blob/main/GOVERNANCE.md#team-members | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| +++ | ||
| draft = "True" | ||
| +++ | ||
|
|
||
| <p align="center"><img src="assets/logo_and_name.png" alt="Grafana Agent logo"></p> | ||
|
|
||
| Grafana Agent is an telemetry collector for sending metrics, logs, | ||
| and trace data to the opinionated Grafana observability stack. It works best | ||
| with: | ||
|
|
||
| * [Grafana Cloud](https://grafana.com/products/cloud/) | ||
| * [Grafana Enterprise Stack](https://grafana.com/products/enterprise/) | ||
| * OSS deployments of [Grafana Loki](https://grafana.com/oss/loki/), [Prometheus](https://prometheus.io/), [Cortex](https://cortexmetrics.io/), and [Grafana Tempo](https://grafana.com/oss/tempo/) | ||
|
|
||
|
|
||
| - Grafana Agent uses less memory on average than Prometheus – by doing less | ||
| (only focusing on `remote_write`-related functionality). | ||
| - Grafana Agent allows for deploying multiple instances of the Agent in a | ||
| cluster and only scraping metrics from targets that are running on the same host. | ||
| This allows for distributing memory requirements across the cluster | ||
| rather than pressurizing a single node. |
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My gut is to just have
rfcsin the normal user docs. https://prometheus.io/docs/introduction/design-doc/ has not led to major confusion, either.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it'd be nice to host them, but I'm concerned that they might be subject to extra scrutiny if they're hosted on grafana.com. Keeping them separate seems the most expedient for now.