Skip to content

Commit cf70f80

Browse files
author
Chris Sinjakli
committed
Add some tweaks to UPGRADING.md
Signed-off-by: Chris Sinjakli <chris@gocardless.com>
1 parent bfbc280 commit cf70f80

File tree

1 file changed

+59
-20
lines changed

1 file changed

+59
-20
lines changed

UPGRADING.md

Lines changed: 59 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,69 @@
1-
# Upgrade from 0.9 to 1.x
1+
# Upgrading from 0.9 to 0.10.x
22

33
## Objectives
44

5-
This major upgrade achieves the following objectives:
5+
0.10.0 represents a big step forward for the Prometheus Ruby client, which comes with some
6+
breaking changes. The objectives behind those changes are:
67

7-
1. Follow [client conventions and best practices](https://prometheus.io/docs/instrumenting/writing_clientlibs/)
8-
2. Add the notion of Pluggable backends. Client should be configurable with different backends: thread-safe (default), thread-unsafe (lock-free for performance on single-threaded cases), multiprocess, etc.
9-
Consumers should be able to build and plug their own backends based on their use cases.
8+
1. Bringing the Ruby client in line with [Prometheus conventions and best
9+
practices](https://prometheus.io/docs/instrumenting/writing_clientlibs/)
10+
2. Adding support for multi-process web servers like Unicorn. This was done by introducing
11+
the notion of pluggable storage backends.
12+
13+
The client can now be configured with different storage backends, and we provide 3 with
14+
the gem: thread-safe (default), thread-unsafe (best performance in single-threaded use
15+
cases), and a multi-process backend that can be used in forking web servers like
16+
Unicorn.
17+
18+
Users of the library can build their own storage backend to support different
19+
use cases provided they conform to the same interface.
1020

1121
## Ruby
1222

13-
The minimum supported Ruby version is 2.0.0.
23+
The minimum supported Ruby version is now 2.3. This will change over time according to our
24+
[compatibility policy](COMPATIBILITY.md).
1425

1526
## Data Stores
1627

17-
You can specify the data store implementation depending on your needs.
28+
The single biggest feature in this release is support for multi-process web servers.
1829

19-
For example, if you are running a pre-fork application using Unicorn you will need a way to aggregate the metrics from each of your workers before Prometheus scrapes them.
30+
The way this was achieved was by introducing a standard interface for metric storage
31+
backends and providing implementations for the most common use-cases.
2032

21-
This can be achieved with DirectFileStore.
33+
If you're using a multi-process web server, you'll want `DirectFileStore`, which
34+
aggregates metrics across the processes.
2235

2336
```ruby
2437
Prometheus::Client.config.data_store = Prometheus::Client::DataStores::DirectFileStore.new(dir: '/tmp/direct_file_store')
2538
```
2639

27-
## kwargs
40+
The default store is the `Synchronized` store, which provides a threadsafe implementation,
41+
but one which doesn't work in multi-process scenarios.
42+
43+
If you're absolutely sure that you won't use multiple threads or processes, you can use the
44+
`SingleThreaded` data store and avoid the locking overhead. Note that in almost all use
45+
cases the performance overhead won't matter, which is why we use the `Synchronized` store
46+
by default.
2847

29-
Certain parameters are now keyword arguments.
48+
## Keyword arguments (kwargs)
49+
50+
Many multi-parameter methods have had their arguments changed to keyword arguments for
51+
improved clarity at the callsite.
3052

3153
### 0.9
3254
```ruby
3355
counter = Prometheus::Client::Counter.new(:service_requests_total, '...')
3456
```
3557

36-
### 1.x
58+
### 0.10
3759
```ruby
3860
counter = Prometheus::Client::Counter.new(:service_requests_total, docstring: '...')
3961
```
4062

4163
### Labels
4264

43-
Labels are set when the metric is defined as opposed to when it is first used.
65+
Labels must now be declared at metric initialization. Observing a value with a label that
66+
wasn't passed in at initialization will raise an error.
4467

4568
### 0.9
4669

@@ -49,7 +72,7 @@ counter = Prometheus::Client::Counter.new(:service_requests_total, '...')
4972
counter.increment({ service: 'foo' })
5073
```
5174

52-
### 1.x
75+
### 0.10
5376

5477
```ruby
5578
counter = Prometheus::Client::Counter.new(:service_requests_total, docstring: '...', labels: [:service])
@@ -58,7 +81,7 @@ counter.increment(labels: { service: 'foo' })
5881

5982
## Histograms
6083

61-
Keys from the get method are now strings.
84+
Keys in the hash returned from the get method are now strings.
6285

6386
Histograms now include a "+Inf" bucket as well as the sum of all observations.
6487

@@ -76,7 +99,7 @@ histogram.observe({ service: 'users' }, 1.5)
7699
histogram.get({ service: 'users' })
77100
# => {0.1=>1.0, 0.3=>2.0, 1.2=>4.0}
78101
```
79-
### 1.x
102+
### 0.10
80103

81104
```ruby
82105
histogram = Prometheus::Client::Histogram.new(:service_latency_seconds, docstring: '...', labels: [:service], buckets: [0.1, 0.3, 1.2])
@@ -93,8 +116,6 @@ histogram.get(labels: { service: 'users' })
93116

94117
## Summaries
95118

96-
Keys from the get method are now strings.
97-
98119
Summaries no longer include quantiles. They include the sum and the count instead.
99120

100121
### 0.9
@@ -111,7 +132,7 @@ summary.observe({ service: 'users' }, 1.5)
111132
summary.get({ service: 'users' })
112133
# => {0.1=>1.0, 0.3=>2.0, 1.2=>4.0}
113134
```
114-
### 1.x
135+
### 0.10
115136

116137
```ruby
117138
summary = Prometheus::Client::Summary.new(:service_latency_seconds, docstring: '...', labels: [:service])
@@ -124,4 +145,22 @@ summary.observe(1.5, labels: { service: 'users' })
124145

125146
summary.get(labels: { service: 'users' })
126147
# => {"count"=>5.0, "sum"=>3.5}
127-
```
148+
```
149+
150+
## Rack middleware
151+
152+
Because metric labels must be declared up front, we've removed support for customising the
153+
labels set in the default Rack middleware we provide.
154+
155+
We did make an attempt to preserve that ability, but decided that the interface was too
156+
confusing and removed it in #121. We might revisit this and have another try at a better
157+
interface in the future.
158+
159+
## Extra reserved label: `pid`
160+
161+
When adding support for multi-process web servers, we realised that aggregating gauges
162+
reported by individual processes (e.g. by summing them) is almost never what you want to
163+
do.
164+
165+
We decided to expose each process's value individually, with a `pid` label set to
166+
differentiate between the proesses. Because of that, `pid` is now a reserved label.

0 commit comments

Comments
 (0)