update to latest release-2.17.1-grafana (#41)

* update to latest 2.17.1-grafana

* Update docs/maintaining.md

Co-Authored-By: gotjosh <josue.abreu@gmail.com>

* Update docs/maintaining.md

Co-Authored-By: gotjosh <josue.abreu@gmail.com>

* address PR feedback

* some extra corrections to try to get GitHub to detect a new commit :)

Co-authored-by: gotjosh <josue.abreu@gmail.com>

README.md

@@ -3,10 +3,12 @@
 Grafana Cloud Agent is an observability data collector optimized for sending
 metrics and log data to [Grafana Cloud](https://grafana.com/products/cloud/).
 
-Users of Prometheus cloud storage vendors with a single Prometheus instance can
-struggle sending their data at massive scale (millions of active series):
-Prometheus is sometimes called a single point of failure that generally requires
-a giant machine with a lot of resources allocated to it.
+Users of Prometheus operating at a massive scale (i.e., millions of active 
+series) can struggle to run an unsharded singleton Prometheus instance: it becomes a 
+single point of failure and requires a giant machine with a lot of resources 
+allocated to it. Even with proper sharding across multiple Prometheus instances, 
+using Prometheus to send data to a cloud vendor can seem redundant: why pay for 
+cloud storage if data is already stored locally?
 
 The Grafana Cloud Agent uses the same code as Prometheus, but tackles these issues
 by only using the most relevant parts of Prometheus for interaction with hosted
@@ -17,12 +19,12 @@ metrics:
 3. Write Ahead Log (WAL)
 4. Remote Write
 
-On top of these, the Grafana Cloud Agent allows for an optional host filter
-mechanism, enabling users to easily shard the Agent across their cluster and
-lower the memory requirements per machine.
+On top of these, the Grafana Cloud Agent enables easier sharding mechanisms that 
+enable users to shard Agents across their cluster and lower the memory requirements
+per machine.
 
 A typical deployment of the Grafana Cloud Agent for Prometheus metrics can see
-up to a 40% reduction in memory usage with comparable scrape loads.
+up to a 40% reduction in memory usage with equal scrape loads.
 
 Despite called the "Grafana Cloud Agent," it can be utilized with any Prometheus
 `remote_write` API.
@@ -74,6 +76,20 @@ A docker-compose config is provided in `example/`. It deploys the Agent, Cortex,
 Grafana, and Avalanche for load testing. See the
 [README in `example/`](./example/README.md) for more information.
 
+## Prometheus Vendoring
+
+The Grafana Cloud Agent vendors a downstream Prometheus repository maintained by 
+[Grafana Labs](https://github.com/grafana/prometheus). This is done so experimental
+features Grafana Labs wants to contribute upstream can first be tested and iterated on
+quickly within the Agent. We aim to always base our vendor off of a recent official 
+Prometheus release and to keep the experimental changes not available in the upstream 
+repository to a minimum.
+
+The current vendored Prometheus release is **v2.17.1**.
+
+For more context on our vendoring strategy, read our 
+[repo maintenance guide](./docs/maintaining.md#grafanaprometheus-maintenance).
+
 ## Getting Help
 
 If you have any questions or feedback regarding the Grafana Cloud Agent:

docs/README.md

@@ -18,7 +18,7 @@ main problems faced by users of large deployments of Prometheus:
     1. [Comparison to alternatives](./overview.md#comparison-to-alternatives)
     2. [Roadmap](./overview.md#roadmap)
 2. [Getting Started](./getting-started.md)
-    1. [Docker-Compose Example](./getting-started.md#docker_compose-example)
+    1. [Docker-Compose Example](./getting-started.md#docker-compose-example)
     2. [Installing](./getting-started.md#installing)
     3. [Migrating from Prometheus](./getting-started.md#migrating-from-prometheus)
     4. [Running](./getting-started.md#running)

docs/maintaining.md

@@ -57,7 +57,7 @@ export GPG_TTY=$(tty)
    for updating the release notes.
 6. Merge the changelog PR.
 7. Create a new tag for the release.
-    1. Once this step is done, the CI will be triggered to create release
+    1. After following step 2, the CI will be triggered to create release
        artifacts and publish them to a draft release. The tag will be made
        publicly available immediately.
     2. Run the following to create the tag:
@@ -73,22 +73,145 @@ export GPG_TTY=$(tty)
 
 ## Publishing the Release Draft
 
-Once the steps are completed, you can publish your draft!
+After this final set of steps, you can publish your draft!
 
 1. Go to the [GitHub releases page](https://github.com/grafana/agent/releases)
    and find the drafted release.
 2. Edit the drafted release, copying and pasting *notable changes* from the
    CHANGELOG. Add a link to the CHANGELOG, noting that the full list of changes
    can be found there. Refer to other releases for help with formatting this.
-3. Optionally, have other team members review the release draft so you feel
-   comfortable with it.
+3. Optionally, have other team members review the release draft if you wish 
+   to feel more comfortable with it.
 4. Publish the release!
 
 ## Updating Release Branch
 
 The `release` branch should always point at the SHA of the commit of the latest
-release tag. This is used so that the install instructions can be generic and
+release tag. This is used so that installation instructions can be generic and
 made to always install the latest released version.
 
 Update the release branch by fast-forwarding it to the appropriate SHA (matching
 the latest tag) and pushing it back upstream.
+
+## `grafana/prometheus` Maintenance
+
+Grafana Labs includes the Agent as part of their internal monitoring, running it 
+alongside Prometheus. This gives an opportunity to utilize the Agent to 
+proof-of-concept additions to Prometheus before they get moved upstream. A 
+`grafana/prometheus` repository maintained by Grafana Labs holds non-trivial 
+and experimental changes. Having this repository allows for experimental features to 
+be vendored into the Agent and enables faster development iteration. Ideally, 
+this experimental testing can help serve as evidence towards usefulness and 
+correctness when the feature becomes proposed upstream. 
+
+We are committing ourselves to doing the following:
+
+1. Keep changes mergeable upstream: we want to continue to be good OSS citizens,
+   and we intend that all features we add to our Prometheus repository will
+   become an upstream PR. We will maintain our repository in a way that supports
+   doing this.
+2. Always vendor a branch from `grafana/prometheus` based off of a recent Prometheus
+   stable release; we want the Agent's Prometheus roots to be stable.
+3. Reduce code drift: The code the Agent uses on top of Prometheus will be
+   layered on top of a Prometheus release rather than sandwiched in between.
+4. Keep the number of experimental changes not merged upstream to a minimum. We're 
+   not trying to fork Prometheus.
+
+Maintenance of the `grafana/prometheus` repository revolves around feature
+branches (named `feat-SOME-FEATURE`) and release branches (named
+`release-vX.Y.Z-grafana`). The release branches will always use the same release
+version as the `prometheus/prometheus` release it is based off of.
+
+By adding features to the `grafana/prometheus` repository first, we are
+committing ourselves to extra maintenance of features that have not yet been
+merged upstream. Feature authors will have to babysit their features to
+coordinate with the Prometheus release schedule to always be compatible. Maintenance 
+burden becomes lightened once each feature is upstreamed as breaking changes will
+no longer happen out of sync with upstream changes for the respective upstreamed
+feature.
+
+We are purposefully carrying this extra burden because we intend to ultimately
+make Prometheus better and contribute all of our enhancements upstream. We want
+to strive to benefit the Prometheus ecosystem at large.
+
+### Creating a New Feature
+
+Grafana Labs developers should try to get all features upstreamed *first*. If 
+it's clear the feature is experimental or more unproven than the upstream team
+is comfortable with, developers should then create a downstream 
+`grafana/prometheus` feature branch.
+
+For `grafana/prometheus` maintainers to create a new feature, they will do the
+following:
+
+1. Create a feature branch in `grafana/prometheus` based on the latest release
+   tag that `grafana/prometheus` currently has a release branch for. The feature
+   branch should follow the naming convention `feat-<feature name>`.
+2. Implement the feature and open a PR to merge the feature branch into the
+   associated `grafana/prometheus` release branch.
+3. After updating the release branch, open a PR to update `grafana/agent` to
+   use the latest release branch SHA.
+
+### Updating an Existing Feature
+
+If a feature branch that was already merged to a release branch needs to be
+updated for any reason:
+
+1. Push directly to the feature branch or open a PR to merge changes into that
+   feature branch.
+2. Open a PR to merge the new changes from the feature branch into the
+   associated release branch.
+3. After updating the release branch, open a PR to update `grafana/agent` by 
+   vendoring the changes using the latest release branch SHA.
+
+### Handling New Upstream Release
+
+When a new upstream `prometheus/prometheus` release is available, we must go
+through the following process:
+
+1. Create a new `grafana/prometheus` release branch named
+   `release-X.Y.Z-grafana`.
+2. For all feature branches still not merged upstream, rebase them on top of the
+   newly created branch. Force push them to update the `grafana/prometheus` 
+   feature branch.
+3. Create one or more PRs to introduce the features into the newly created
+   release branch.
+
+Once a new release branch has been created, the previous release branch in 
+`grafana/prometheus` is considered stale and will no longer receive updates.
+
+### Updating the Agent's vendor
+
+The easiest way to do this is the following:
+
+1. Edit `go.mod` and change the replace directive to the release branch name.
+2. Update `README.md` in the Agent to change which version of Prometheus 
+   the Agent is vendoring.
+2. Run `go mod tidy && go mod vendor`.
+3. Commit and open a PR.
+
+### Gotchas
+
+If the `grafana/prometheus` feature is incompatible with the upstream 
+`prometheus/prometheus` master branch, merge conflicts would prevent
+an upstream PR from being merged. There are a few ways this can be handled 
+at the feature author's discretion:
+
+When this happens, downstream feature branch maintainers should wait until 
+a new `prometheus/prometheus` release is available and rebase their feature 
+branch on top of the latest release. This will make the upstream PR compatible 
+with the master branch, though the window of compatibility is unpredictable 
+and may change at any time. 
+
+If it proves unfeasible to get a feature branch merged upstream within the 
+"window of upstream compatibility," feature branch maintainers should create
+a fork of their branch that is based off of master and use that master-compatible 
+branch for the upstream PR. Note that this means any changes made to the feature 
+branch will now have to be mirrored to the master-compatible branch.
+
+### Open Questions
+
+If two feature branches depend on one another, a combined feature branch 
+(like an "epic" branch) should be created where development of interrelated 
+features go. All features within this category go directly to the combined 
+"epic" branch rather than individual branches.

go.mod

@@ -43,5 +43,4 @@ replace (
 	k8s.io/client-go => k8s.io/client-go v0.0.0-20190620085101-78d2af792bab
 )
 
-// Temporarily use a fork for memory improvements (see #5)
-replace github.com/prometheus/prometheus => github.com/grafana/prometheus v1.8.2-0.20200330171229-fc3d977ea463
+replace github.com/prometheus/prometheus => github.com/grafana/prometheus v1.8.2-0.20200403162459-09b8b1048e6c

go.sum

@@ -371,8 +371,8 @@ github.com/gorilla/websocket v0.0.0-20170926233335-4201258b820c h1:Lh2aW+HnU2Nbe
 github.com/gorilla/websocket v0.0.0-20170926233335-4201258b820c/go.mod h1:E7qHFY5m1UJ88s3WnNqhKjPHQ0heANvMoAMk2YaljkQ=
 github.com/gorilla/websocket v1.4.0 h1:WDFjx/TMzVgy9VdMMQi2K2Emtwi2QcUQsztZ/zLaH/Q=
 github.com/gorilla/websocket v1.4.0/go.mod h1:E7qHFY5m1UJ88s3WnNqhKjPHQ0heANvMoAMk2YaljkQ=
-github.com/grafana/prometheus v1.8.2-0.20200330171229-fc3d977ea463 h1:TsJr/QSx5bz/nvv4o9+EJwYqozqxrrEICjjTs0K9EmM=
-github.com/grafana/prometheus v1.8.2-0.20200330171229-fc3d977ea463/go.mod h1:ZnfuiMn3LNsry2q7ECmRe4WcscxmJSd2dIFpOi4w3lM=
+github.com/grafana/prometheus v1.8.2-0.20200403162459-09b8b1048e6c h1:5b4jlWiX7jqAWdUpq9WwNMxUFkFrovk0AsLHmQseNi4=
+github.com/grafana/prometheus v1.8.2-0.20200403162459-09b8b1048e6c/go.mod h1:ZnfuiMn3LNsry2q7ECmRe4WcscxmJSd2dIFpOi4w3lM=
 github.com/gregjones/httpcache v0.0.0-20170728041850-787624de3eb7/go.mod h1:FecbI9+v66THATjSRHfNgh1IVFe/9kFxbXtjV0ctIMA=
 github.com/grpc-ecosystem/go-grpc-middleware v1.0.1-0.20190118093823-f849b5445de4 h1:z53tR0945TRRQO/fLEVPI6SMv7ZflF0TEaTAoU7tOzg=
 github.com/grpc-ecosystem/go-grpc-middleware v1.0.1-0.20190118093823-f849b5445de4/go.mod h1:FiyG127CGDf3tlThmgyCl78X/SZQqEOJBCDaAfeWzPs=

vendor/modules.txt

@@ -258,7 +258,7 @@ github.com/prometheus/common/version
 github.com/prometheus/procfs
 github.com/prometheus/procfs/internal/fs
 github.com/prometheus/procfs/internal/util
-# github.com/prometheus/prometheus v1.8.2-0.20200213233353-b90be6f32a33 => github.com/grafana/prometheus v1.8.2-0.20200330171229-fc3d977ea463
+# github.com/prometheus/prometheus v1.8.2-0.20200213233353-b90be6f32a33 => github.com/grafana/prometheus v1.8.2-0.20200403162459-09b8b1048e6c
 github.com/prometheus/prometheus/config
 github.com/prometheus/prometheus/discovery
 github.com/prometheus/prometheus/discovery/azure