mudhorn/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2024-11-09 23:24:05 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Add 2.0 stability guarantees (#3484)

Browse source 
As discussed generally consider SDs as unstable, as realistically they
are never going to be. Drop the words "experimental/beta" from most
places in the docs, as users are getting the wrong impression from this.
This commit is contained in:
Brian Brazil 2017-12-14 12:54:32 +00:00 committed by GitHub
parent aa25dff1ea
commit 9083d41d3a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 43 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
docs/configuration/configuration.md
View file

@ -82,11 +82,11 @@ alerting:
alertmanagers:
[ - <alertmanager_config> ... ]
# Settings related to the experimental remote write feature.
# Settings related to the remote write feature.
remote_write:
[ - <remote_write> ... ]
# Settings related to the experimental remote read feature.
# Settings related to the remote read feature.
remote_read:
[ - <remote_read> ... ]
```
@ -253,9 +253,6 @@ A `tls_config` allows configuring TLS connections.
### `<azure_sd_config>`
CAUTION: Azure SD is in beta: breaking changes to configuration are still
likely in future releases.
Azure SD configurations allow retrieving scrape targets from Azure VMs.
The following meta labels are available on targets during relabeling:
@ -412,18 +409,8 @@ region: <string>
### `<openstack_sd_config>`
CAUTION: OpenStack SD is in beta: breaking changes to configuration are still
likely in future releases.
OpenStack SD configurations allow retrieving scrape targets from the OpenStack
Nova API.
One of the following `role` types can be configured to discover targets:
#### `hypervisor`
The `hypervisor` role discovers one target per Nova hypervisor node. The target
address defaults to the `host_ip` attribute of the hypervisor.
OpenStack SD configurations allow retrieving scrape targets from OpenStack Nova
instances.
The following meta labels are available on targets during [relabeling](#relabel_config):
@ -546,9 +533,6 @@ may contain a single `*` that matches any character sequence, e.g. `my/path/tg_*
### `<gce_sd_config>`
CAUTION: GCE SD is in beta: breaking changes to configuration are still
likely in future releases.
[GCE](https://cloud.google.com/compute/) SD configurations allow retrieving scrape targets from GCP GCE instances.
The private IP address is used by default, but may be changed to the public IP
address with relabeling.
@ -607,9 +591,6 @@ service account and place the credential file in one of the expected locations.
### `<kubernetes_sd_config>`
CAUTION: Kubernetes SD is in beta: breaking changes to configuration are still
likely in future releases.
Kubernetes SD configurations allow retrieving scrape targets from
[Kubernetes'](http://kubernetes.io/) REST API and always staying synchronized with
the cluster state.
@ -755,9 +736,6 @@ which automates the Prometheus setup on top of Kubernetes.
### `<marathon_sd_config>`
CAUTION: Marathon SD is in beta: breaking changes to configuration are still
likely in future releases.
Marathon SD configurations allow retrieving scrape targets using the
[Marathon](https://mesosphere.github.io/marathon/) REST API. Prometheus
will periodically check the REST endpoint for currently running tasks and
@ -854,9 +832,6 @@ Serverset data must be in the JSON format, the Thrift format is not currently su
### `<triton_sd_config>`
CAUTION: Triton SD is in beta: breaking changes to configuration are still
likely in future releases.
[Triton](https://github.com/joyent/triton) SD configurations allow retrieving
scrape targets from [Container Monitor](https://github.com/joyent/rfd/blob/master/rfd/0027/README.md)
discovery endpoints.
@ -1103,9 +1078,6 @@ relabel_configs:
### `<remote_write>`
CAUTION: Remote write is experimental: breaking changes to configuration are
likely in future releases.
`write_relabel_configs` is relabeling applied to samples before sending them
to the remote endpoint. Write relabeling is applied after external labels. This
could be used to limit which samples are sent.
@ -1152,9 +1124,6 @@ with this feature.
### `<remote_read>`
CAUTION: Remote read is experimental: breaking changes to configuration are
likely in future releases.
```yaml
# The URL of the endpoint to query from.
url: <string>

38
docs/stability.md Normal file
View file

@ -0,0 +1,38 @@
---
title: API Stability
sort_rank: 8
---
# API Stability Guarantees
Prometheus promises API stability within a major version, and strives to avoid
breaking changes for key features. Some features, which are cosmetic, still
under development, or depend on 3rd party services, are not covered by this.
Things considered stable for 2.x:
* The query language and data model
* Alerting and recording rules
* The ingestion exposition format
* v1 HTTP API (used by dashboards and UIs)
* Configuration file format (minus the service discovery remote read/write, see below)
* Rule/alert file format
* Console template syntax and semantics
Things considered unstable for 2.x:
* Any feature listed as experimental or subject to change, including:
* The [`holt_winters` PromQL function](https://github.com/prometheus/prometheus/issues/2458)
* Remote read, remote write and the remote read endpoint
* v2 HTTP and GRPC APIs
* Service discovery integrations, with the exception of `static_configs` and `file_sd_configs`
* Go APIs of packages that are part of the server
* HTML generated by the web UI
* The metrics in the /metrics endpoint of Prometheus itself
* Exact on-disk format. Potential changes however, will be forward compatible and transparently handled by Prometheus
As long as you are not using any features marked as experimental/unstable, an
upgrade within a major version can usually be performed without any operational
adjustments and very little risk that anything will break. Any breaking changes
will be marked as `CHANGE` in release notes.

2
docs/storage.md
View file

@ -75,7 +75,7 @@ Prometheus integrates with remote storage systems in two ways:
![Remote read and write architecture](images/remote_integrations.png)
The read and write protocols both use a snappy-compressed protocol buffer encoding over HTTP. The protocols are still marked experimental and may change to use gRPC over HTTP/2 in the future, when all hops between Prometheus and the long-term storage can safely be assumed to support HTTP/2.
The read and write protocols both use a snappy-compressed protocol buffer encoding over HTTP. The protocols are not considered as stable APIs yet and may change to use gRPC over HTTP/2 in the future, when all hops between Prometheus and the long-term storage can safely be assumed to support HTTP/2.
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.