From f39e4b71132e7a7d4101ba135818d1a7744fde18 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Wed, 17 Feb 2021 09:44:46 -0500 Subject: [PATCH 1/3] s/master/main in docs --- CHANGELOG.md | 4 +- docs/maintaining.md | 79 +++++++++++-------- docs/operation-guide.md | 6 +- packaging/deb/grafana-agent.service | 2 +- packaging/grafana-agent.yaml | 2 +- packaging/rpm/grafana-agent.service | 2 +- .../v1/lib/integrations.libsonnet | 2 +- .../tanka/grafana-agent/v1/lib/loki.libsonnet | 2 +- .../grafana-agent/v1/lib/prometheus.libsonnet | 10 +-- .../grafana-agent/v1/lib/tempo.libsonnet | 28 +++---- 10 files changed, 74 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52d159ef361c..9ef921761daf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ NOTE: FreeBSD builds have not been available since v0.6.0 due to a cross-compilation issue. The issue for tracking adding support back can be found at [#317](https://github.com/grafana/agent/issues/317). -# Master (unreleased) +# Main (unreleased) - [ENHANCEMENT] Support other architectures in installation script. (@rfratto) @@ -329,7 +329,7 @@ files to the new format. # v0.5.0 (2020-08-12) -- [FEATURE] A [scrape targets API](https://github.com/grafana/agent/blob/master/docs/api.md#list-current-scrape-targets) +- [FEATURE] A [scrape targets API](https://github.com/grafana/agent/blob/main/docs/api.md#list-current-scrape-targets) has been added to show every target the Agent is currently scraping, when it was last scraped, how long it took to scrape, and errors from the last scrape, if any. (@rfratto) diff --git a/docs/maintaining.md b/docs/maintaining.md index c8e5cc722cf6..80cf6b1899a4 100644 --- a/docs/maintaining.md +++ b/docs/maintaining.md @@ -3,6 +3,17 @@ This document provides relevant instructions for maintainers of the Grafana Cloud Agent. +## Master Branch Rename + +The `master` branch was renamed to `main` on 17 Feb 2021. If you have already +checked out the repository, you will need to update your local environment: + +``` +git branch -m master main +git fetch origin +git branch -u origin/main main +``` + ## Releasing ### Prerequisites @@ -10,14 +21,14 @@ Cloud Agent. Each maintainer performing a release should perform the following steps once before releasing the Grafana Cloud Agent. -#### Prerelease testing +#### Prerelease testing For testing a release, run the [K3d example](../example/k3d/README.md) locally. Let it run for about 90 minutes, keeping an occasional eye on the Agent Operational dashboard (noting that metrics from the scraping service will take time to show up). After 90 minutes, if nothing has crashed and you see metrics for both the scraping service and the non-scraping service, the Agent is ready -for release. +for release. #### Add Existing GPG Key to GitHub @@ -58,7 +69,7 @@ export GPG_TTY=$(tty) 1. Create a new branch to update `CHANGELOG.md` and references to version numbers across the entire repository (e.g. README.md in the project root). 2. Modify `CHANGELOG.md` with the new version number and its release date. -3. Add a new section in `CHANGELOG.md` for `Master (unreleased)`. +3. Add a new section in `CHANGELOG.md` for `Main (unreleased)`. 4. Go through the entire repository and find references to the previous release version, updating them to reference the new version. 5. Run `make example-kubernetes` and `make example-dashboards` to update @@ -74,7 +85,7 @@ export GPG_TTY=$(tty) ```bash RELEASE=v1.2.3 # UPDATE ME to reference new release - git checkout master # If not already on master + git checkout main # If not already on main git pull git tag -s $RELEASE -m "release $RELEASE" git push origin $RELEASE @@ -90,7 +101,7 @@ After this final set of steps, you can publish your draft! 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 if you wish +3. Optionally, have other team members review the release draft if you wish to feel more comfortable with it. 4. Publish the release! @@ -107,14 +118,14 @@ 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. +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: @@ -126,7 +137,7 @@ We are committing ourselves to doing the following: 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 +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 @@ -137,7 +148,7 @@ 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 +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. @@ -148,9 +159,9 @@ 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 +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 +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 @@ -173,7 +184,7 @@ updated for any reason: 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 +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 @@ -184,12 +195,12 @@ 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` + 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 +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 @@ -197,33 +208,33 @@ Once a new release branch has been created, the previous release branch in 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 +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 +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 +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. +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 +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 +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 +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. diff --git a/docs/operation-guide.md b/docs/operation-guide.md index 4d4324a0bde5..b2b0037c32ba 100644 --- a/docs/operation-guide.md +++ b/docs/operation-guide.md @@ -1,11 +1,11 @@ # Operation Guide -## Host Filtering +## Host Filtering Host Filtering implements a form of "dumb sharding," where operators may deploy one Grafana Cloud Agent instance per machine in a cluster, all using the same configuration, and the Grafana Cloud Agents will only scrape targets that are -running on the same node as the Agent. +running on the same node as the Agent. Running with `host_filter: true` means that if you have a target whose host machine is not also running a Grafana Cloud Agent process, _that target will not @@ -51,7 +51,7 @@ logic; only `host_filter_relabel_configs` will work. If the determined hostname matches any of the meta labels, the discovered target is allowed. Otherwise, the target is ignored, and will not show up in the [targets -API](https://github.com/grafana/agent/blob/master/docs/api.md#list-current-scrape-targets). +API](https://github.com/grafana/agent/blob/main/docs/api.md#list-current-scrape-targets). ## Prometheus "Instances" diff --git a/packaging/deb/grafana-agent.service b/packaging/deb/grafana-agent.service index 2b262de32206..e2ef863c8ef4 100644 --- a/packaging/deb/grafana-agent.service +++ b/packaging/deb/grafana-agent.service @@ -1,6 +1,6 @@ [Unit] Description=Monitoring system and forwarder -Documentation=https://github.com/grafana/agent/blob/master/docs/README.md +Documentation=https://github.com/grafana/agent/blob/main/docs/README.md Wants=network-online.target After=network-online.target diff --git a/packaging/grafana-agent.yaml b/packaging/grafana-agent.yaml index 4846aec2373c..db7411ab46e9 100644 --- a/packaging/grafana-agent.yaml +++ b/packaging/grafana-agent.yaml @@ -1,5 +1,5 @@ # Sample config for Grafana Agent -# For a full configuration reference, see: https://github.com/grafana/agent/blob/master/docs/configuration-reference.md. +# For a full configuration reference, see: https://github.com/grafana/agent/blob/main/docs/configuration-reference.md. server: http_listen_address: '127.0.0.1' http_listen_port: 9090 diff --git a/packaging/rpm/grafana-agent.service b/packaging/rpm/grafana-agent.service index 53298b9af7ae..3fc7b199da4d 100644 --- a/packaging/rpm/grafana-agent.service +++ b/packaging/rpm/grafana-agent.service @@ -1,6 +1,6 @@ [Unit] Description=Monitoring system and forwarder -Documentation=https://github.com/grafana/agent/blob/master/docs/README.md +Documentation=https://github.com/grafana/agent/blob/main/docs/README.md Wants=network-online.target After=network-online.target diff --git a/production/tanka/grafana-agent/v1/lib/integrations.libsonnet b/production/tanka/grafana-agent/v1/lib/integrations.libsonnet index ea649004fc24..0a6620922896 100644 --- a/production/tanka/grafana-agent/v1/lib/integrations.libsonnet +++ b/production/tanka/grafana-agent/v1/lib/integrations.libsonnet @@ -6,7 +6,7 @@ local container = k.core.v1.container; // withIntegrations controls the integrations component of the Agent. // // For the full list of options, refer to the configuration reference: - // https://github.com/grafana/agent/blob/master/docs/configuration-reference.md#integrations_config + // https://github.com/grafana/agent/blob/main/docs/configuration-reference.md#integrations_config withIntegrations(integrations):: { assert std.objectHasAll(self, '_mode') : ||| withLokiConfig must be merged with the result of calling new. diff --git a/production/tanka/grafana-agent/v1/lib/loki.libsonnet b/production/tanka/grafana-agent/v1/lib/loki.libsonnet index 09d4c65b9d4a..a6b03648f2c0 100644 --- a/production/tanka/grafana-agent/v1/lib/loki.libsonnet +++ b/production/tanka/grafana-agent/v1/lib/loki.libsonnet @@ -7,7 +7,7 @@ local container = k.core.v1.container; // withLokiConfig adds a Loki config to collect logs. // // For the full list of options, refer to the configuration reference: - // https://github.com/grafana/agent/blob/master/docs/configuration-reference.md#loki_config + // https://github.com/grafana/agent/blob/main/docs/configuration-reference.md#loki_config withLokiConfig(config):: { assert std.objectHasAll(self, '_mode') : ||| withLokiConfig must be merged with the result of calling new. diff --git a/production/tanka/grafana-agent/v1/lib/prometheus.libsonnet b/production/tanka/grafana-agent/v1/lib/prometheus.libsonnet index d21f397d0a8c..3418878d912e 100644 --- a/production/tanka/grafana-agent/v1/lib/prometheus.libsonnet +++ b/production/tanka/grafana-agent/v1/lib/prometheus.libsonnet @@ -51,7 +51,7 @@ local scrape_k8s = import '../internal/kubernetes_instance.libsonnet'; // values for scrape configs and remote_write. For detailed information on // instance config settings, consult the Agent documentation: // - // https://github.com/grafana/agent/blob/master/docs/configuration-reference.md#prometheus_instance_config + // https://github.com/grafana/agent/blob/main/docs/configuration-reference.md#prometheus_instance_config // // host_filter does not need to be applied here; the library will apply it // automatically based on how the Agent is being deployed. @@ -81,7 +81,7 @@ local scrape_k8s = import '../internal/kubernetes_instance.libsonnet'; if !std.objectHas(inst, 'remote_write') || !std.isArray(inst.remote_write) then [] else inst.remote_write, - }, list) + }, list), }, // withRemoteWrite overwrites all the remote_write configs provided in @@ -90,13 +90,13 @@ local scrape_k8s = import '../internal/kubernetes_instance.libsonnet'; // to remote_write to the same place. // // Refer to the remote_write specification for all available fields: - // https://github.com/grafana/agent/blob/master/docs/configuration-reference.md#remote_write + // https://github.com/grafana/agent/blob/main/docs/configuration-reference.md#remote_write withRemoteWrite(remote_writes):: { assert std.objectHasAll(self, '_mode') : ||| withPrometheusInstances must be merged with the result of calling new, newDeployment, or newScrapingService. |||, - assert std.objectHasAll(self, '_prometheus_instances'): ||| + assert std.objectHasAll(self, '_prometheus_instances') : ||| withRemoteWrite must be merged with the result of calling withPrometheusInstances. |||, @@ -105,7 +105,7 @@ local scrape_k8s = import '../internal/kubernetes_instance.libsonnet'; _prometheus_instances:: std.map(function(inst) inst { remote_write: list, - }, super._prometheus_instances) + }, super._prometheus_instances), }, // scrapeInstanceKubernetes defines an instance config Grafana Labs uses to diff --git a/production/tanka/grafana-agent/v1/lib/tempo.libsonnet b/production/tanka/grafana-agent/v1/lib/tempo.libsonnet index 2bf7a1b28171..aff00caeab77 100644 --- a/production/tanka/grafana-agent/v1/lib/tempo.libsonnet +++ b/production/tanka/grafana-agent/v1/lib/tempo.libsonnet @@ -1,6 +1,6 @@ { - // withTempoConfig adds a Tempo config to collect traces. - // + // withTempoConfig adds a Tempo config to collect traces. + // // For the full list of options, refer to the configuration reference: // withTempoConfig(config):: { @@ -10,10 +10,10 @@ _tempo_config:: config, }, - // withTempoPushConfig configures a location to write traces to. - // + // withTempoPushConfig configures a location to write traces to. + // // Availabile options can be found in the configuration reference: - // https://github.com/grafana/agent/blob/master/docs/configuration-reference.md#tempo_config + // https://github.com/grafana/agent/blob/main/docs/configuration-reference.md#tempo_config withTempoPushConfig(push_config):: { assert std.objectHasAll(self, '_tempo_config') : ||| withTempoPushConfig must be merged with the result of calling @@ -22,8 +22,8 @@ _tempo_config+:: { push_config: push_config }, }, - // withTempoSamplingStrategies accepts an object for trace sampling strategies. - // + // withTempoSamplingStrategies accepts an object for trace sampling strategies. + // // Refer to Jaeger's documentation for available fields: // https://www.jaegertracing.io/docs/1.17/sampling/#collector-sampling-configuration // @@ -35,14 +35,14 @@ withTempoConfig. |||, - assert - std.objectHasAll(self._tempo_config, 'receivers') && - std.objectHasAll(self._tempo_config.receivers, 'jaeger') : ||| - withStrategies can only be used if the tempo config is configured for + assert + std.objectHasAll(self._tempo_config, 'receivers') && + std.objectHasAll(self._tempo_config.receivers, 'jaeger') : ||| + withStrategies can only be used if the tempo config is configured for receiving Jaeger spans and traces. |||, - // The main library should detect the presence of _tempo_sampling_strategies + // The main library should detect the presence of _tempo_sampling_strategies // and create a ConfigMap bound to /etc/agent/strategies.json. _tempo_sampling_strategies:: strategies, _tempo_config+:: { @@ -57,7 +57,7 @@ }, }, - // Configures scrape_configs for discovering meta labels that will be attached + // Configures scrape_configs for discovering meta labels that will be attached // to incoming metrics and spans whose IP matches the __address__ of the // target. withTempoScrapeConfigs(scrape_configs):: { @@ -97,5 +97,5 @@ insecure_skip_verify: false, }, }, - ] + ], } From 0338db082d9f620946e65501095f82a8a2d587d8 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Wed, 17 Feb 2021 10:07:15 -0500 Subject: [PATCH 2/3] add branch name change message to CHANGELOG --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ef921761daf..902ad9c22e74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ can be found at [#317](https://github.com/grafana/agent/issues/317). # Main (unreleased) +The primary branch name has changed from `master` to `main`. You may have to +update your local checkouts of the repository to point at the new branch name. + - [ENHANCEMENT] Support other architectures in installation script. (@rfratto) - [BUGFIX] Not providing an `-addr` flag for `agentctl config-sync` will no From c48ef988bf6e9020affff3e46f5a6b5f3da55d01 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Wed, 17 Feb 2021 10:19:59 -0500 Subject: [PATCH 3/3] update CI --- .github/workflows/containerize.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/containerize.yml b/.github/workflows/containerize.yml index 9ed6ce180b83..4eb693c4832e 100644 --- a/.github/workflows/containerize.yml +++ b/.github/workflows/containerize.yml @@ -2,7 +2,7 @@ name: Containerize on: push: branches: - - master + - main jobs: test: name: Test