From 8fdfa52976ebb0c0594962fe4dac7605373fa638 Mon Sep 17 00:00:00 2001 From: beorn7 Date: Wed, 5 Jan 2022 15:26:24 +0100 Subject: [PATCH] API: Promote remote-write-receiver to stable Since `/api/v1/write` is a mutating endpoint, we should still activate the remote-write-receiver explicitly. But we should do it in the same way as the other mutating endpoints, i.e. via a flag `--web.enable-remote-write-receiver`. This commit marks the feature flag as deprecated, i.e. it still works but logs a warning on startup. This enables users to seamlessly migrate. With the next minor release, we can start ignoring the feature flag (but still warn a user that is trying to use it). Signed-off-by: beorn7 --- cmd/prometheus/main.go | 9 ++++++--- docs/feature_flags.md | 2 ++ docs/querying/api.md | 14 ++++++++++++++ docs/storage.md | 2 +- web/web.go | 4 ++-- 5 files changed, 25 insertions(+), 6 deletions(-) diff --git a/cmd/prometheus/main.go b/cmd/prometheus/main.go index 14c738d67..eaa97fe32 100644 --- a/cmd/prometheus/main.go +++ b/cmd/prometheus/main.go @@ -173,8 +173,8 @@ func (c *flagConfig) setFeatureListOptions(logger log.Logger) error { c.enablePromQLNegativeOffset = true level.Info(logger).Log("msg", "Experimental promql-negative-offset enabled") case "remote-write-receiver": - c.web.RemoteWriteReceiver = true - level.Info(logger).Log("msg", "Experimental remote-write-receiver enabled") + c.web.EnableRemoteWriteReceiver = true + level.Warn(logger).Log("msg", "Remote write receiver enabled via feature flag remote-write-receiver. This is DEPRECATED. Use --web.enable-remote-write-receiver.") case "expand-external-labels": c.enableExpandExternalLabels = true level.Info(logger).Log("msg", "Experimental expand-external-labels enabled") @@ -263,6 +263,9 @@ func main() { a.Flag("web.enable-admin-api", "Enable API endpoints for admin control actions."). Default("false").BoolVar(&cfg.web.EnableAdminAPI) + a.Flag("web.enable-remote-write-receiver", "Enable API endpoint accepting remote write requests."). + Default("false").BoolVar(&cfg.web.EnableRemoteWriteReceiver) + a.Flag("web.console.templates", "Path to the console template directory, available at /consoles."). Default("consoles").StringVar(&cfg.web.ConsoleTemplatesPath) @@ -381,7 +384,7 @@ func main() { serverOnlyFlag(a, "query.max-samples", "Maximum number of samples a single query can load into memory. Note that queries will fail if they try to load more samples than this into memory, so this also limits the number of samples a query can return."). Default("50000000").IntVar(&cfg.queryMaxSamples) - a.Flag("enable-feature", "Comma separated feature names to enable. Valid options: agent, exemplar-storage, expand-external-labels, memory-snapshot-on-shutdown, promql-at-modifier, promql-negative-offset, remote-write-receiver, extra-scrape-metrics, new-service-discovery-manager. See https://prometheus.io/docs/prometheus/latest/feature_flags/ for more details."). + a.Flag("enable-feature", "Comma separated feature names to enable. Valid options: agent, exemplar-storage, expand-external-labels, memory-snapshot-on-shutdown, promql-at-modifier, promql-negative-offset, remote-write-receiver (DEPRECATED), extra-scrape-metrics, new-service-discovery-manager. See https://prometheus.io/docs/prometheus/latest/feature_flags/ for more details."). Default("").StringsVar(&cfg.featureList) promlogflag.AddFlags(a, &cfg.promlogConfig) diff --git a/docs/feature_flags.md b/docs/feature_flags.md index c175e6198..fd09c4088 100644 --- a/docs/feature_flags.md +++ b/docs/feature_flags.md @@ -46,6 +46,8 @@ More details can be found [here](querying/basics.md#offset-modifier). The remote write receiver allows Prometheus to accept remote write requests from other Prometheus servers. More details can be found [here](storage.md#overview). +Activating the remote write receiver via a feature flag is deprecated. Use `--web.enable-remote-write-receiver` instead. This feature flag will be ignored in future versions of Prometheus. + ## Exemplars storage `--enable-feature=exemplar-storage` diff --git a/docs/querying/api.md b/docs/querying/api.md index 6fa21cc7d..84d8c8f96 100644 --- a/docs/querying/api.md +++ b/docs/querying/api.md @@ -1145,3 +1145,17 @@ $ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones ``` *New in v2.1 and supports PUT from v2.9* + +## Remote Write Receiver + +Prometheus can be configured as a receiver for the Prometheus remote write +protocol. This is not considered an efficient way of ingesting samples. Use it +with caution for specific low-volume use cases. It is not suitable for +replacing the ingestion via scraping and turning Prometheus into a push-based +metrics collection system. + +Enable the remote write receiver by setting +`--web.enable-remote-write-receiver`. When enabled, the remote write receiver +endpoint is `/api/v1/write`. Find more details [here](../storage.md#overview). + +*New in v2.33* diff --git a/docs/storage.md b/docs/storage.md index a6ad5e798..c4526518a 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -129,7 +129,7 @@ The read and write protocols both use a snappy-compressed protocol buffer encodi For details on configuring remote storage integrations in Prometheus, see the [remote write](configuration/configuration.md#remote_write) and [remote read](configuration/configuration.md#remote_read) sections of the Prometheus configuration documentation. -The built-in remote write receiver can be enabled by setting the `--enable-feature=remote-write-receiver` command line flag. When enabled, the remote write receiver endpoint is `/api/v1/write`. +The built-in remote write receiver can be enabled by setting the `--web.enable-remote-write-receiver` command line flag. When enabled, the remote write receiver endpoint is `/api/v1/write`. For details on the request and response messages, see the [remote storage protocol buffer definitions](https://github.com/prometheus/prometheus/blob/main/prompb/remote.proto). diff --git a/web/web.go b/web/web.go index 5aba8896d..93531f4c3 100644 --- a/web/web.go +++ b/web/web.go @@ -257,7 +257,7 @@ type Options struct { RemoteReadSampleLimit int RemoteReadConcurrencyLimit int RemoteReadBytesInFrame int - RemoteWriteReceiver bool + EnableRemoteWriteReceiver bool IsAgent bool Gatherer prometheus.Gatherer @@ -314,7 +314,7 @@ func New(logger log.Logger, o *Options) *Handler { FactoryRr := func(_ context.Context) api_v1.RulesRetriever { return h.ruleManager } var app storage.Appendable - if o.RemoteWriteReceiver { + if o.EnableRemoteWriteReceiver { app = h.storage }