prometheus-client 1.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edc489cbe60b73d291c523b070bd74d361cf28e7c57193865bc8d8d88f8780ef
-  data.tar.gz: ec17c3fb9999a4ed475bfbfe3da3f931f0e66f319c9733ee787ddc40229e9059
+  metadata.gz: 47fef80d530cba8aed214132cb1eb512c7094f9e0daa89db9d5db3f2f0393980
+  data.tar.gz: 98cfad337c9ff3907ba519fbd355e81697108af3251ec574fbb2c14bdd35af2c
 SHA512:
-  metadata.gz: d1df07ee9b21d8596bfd191f0d4203cc5dddbcab8ea13ba0d7cf04e7a8708ed622488eb3fb70713abeea0555eecebe3380d1b14b2199b2b056f8cdea1d93ddac
-  data.tar.gz: 4d219fd0b8a5bec670597b3650c4a1be45bb635f83d8a03f6b659ef5ab44e85dcd19a9a977ac6839fbd922dba813a8653a542db9dbaf13c110ec4beedb33a129
+  metadata.gz: 844a860cf2090a1833a0f3a24d0c7629a761391f69aac8ebea5550463a2219947144438caae36662038cdf242747eea0afe42f3fbe2e86e2e4177f75ee1e50bf
+  data.tar.gz: 3429071dd55ee6f0493790b8860639e653e0e0bb4ddfdc1dffc30c051a66df598272ea2056e9ef87e0c67eb964606cfeba29c9faf05408f2e40e48ab09e31fbc

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -5,11 +5,17 @@ through a HTTP interface. Intended to be used together with a
 [Prometheus server][1].
 
 [![Gem Version][4]](http://badge.fury.io/rb/prometheus-client)
-[![Build Status][3]](http://travis-ci.org/prometheus/client_ruby)
-[![Coverage Status][7]](https://coveralls.io/r/prometheus/client_ruby)
+[![Build Status][3]](https://circleci.com/gh/prometheus/client_ruby/tree/main.svg?style=svg)
 
 ## Usage
 
+### Installation
+
+For a global installation run `gem install prometheus-client`.
+
+If you're using [Bundler](https://bundler.io/) add `gem "prometheus-client"` to your `Gemfile`.
+Make sure to run `bundle install` afterwards.
+
 ### Overview
 
 ```ruby
@@ -50,11 +56,11 @@ use Rack::Deflater
 use Prometheus::Middleware::Collector
 use Prometheus::Middleware::Exporter
 
-run ->(_) { [200, {'Content-Type' => 'text/html'}, ['OK']] }
+run ->(_) { [200, {'content-type' => 'text/html'}, ['OK']] }
 ```
 
 Start the server and have a look at the metrics endpoint:
-[http://localhost:5000/metrics](http://localhost:5000/metrics).
+[http://localhost:5123/metrics](http://localhost:5123/metrics).
 
 For further instructions and other scripts to get started, have a look at the
 integrated [example application](examples/rack/README.md).
@@ -64,7 +70,7 @@ integrated [example application](examples/rack/README.md).
 The Ruby client can also be used to push its collected metrics to a
 [Pushgateway][8]. This comes in handy with batch jobs or in other scenarios
 where it's not possible or feasible to let a Prometheus server scrape a Ruby
-process. TLS and basic access authentication are supported.
+process. TLS and HTTP basic authentication are supported.
 
 ```ruby
 require 'prometheus/client'
@@ -74,18 +80,59 @@ registry = Prometheus::Client.registry
 # ... register some metrics, set/increment/observe/etc. their values
 
 # push the registry state to the default gateway
-Prometheus::Client::Push.new('my-batch-job').add(registry)
+Prometheus::Client::Push.new(job: 'my-batch-job').add(registry)
+
+# optional: specify a grouping key that uniquely identifies a job instance, and gateway.
+#
+# Note: the labels you use in the grouping key must not conflict with labels set on the
+# metrics being pushed. If they do, an error will be raised.
+Prometheus::Client::Push.new(
+  job: 'my-batch-job',
+  gateway: 'https://example.domain:1234',
+  grouping_key: { instance: 'some-instance', extra_key: 'foobar' }
+).add(registry)
+
+# If you want to replace any previously pushed metrics for a given grouping key,
+# use the #replace method.
+#
+# Unlike #add, this will completely replace the metrics under the specified grouping key
+# (i.e. anything currently present in the pushgateway for the specified grouping key, but
+# not present in the registry for that grouping key will be removed).
+#
+# See https://github.com/prometheus/pushgateway#put-method for a full explanation.
+Prometheus::Client::Push.new(job: 'my-batch-job').replace(registry)
+
+# If you want to delete all previously pushed metrics for a given grouping key,
+# use the #delete method.
+Prometheus::Client::Push.new(job: 'my-batch-job').delete
+```
 
-# optional: specify the instance name (instead of IP) and gateway.
-Prometheus::Client::Push.new('my-batch-job', 'foobar', 'https://example.domain:1234').add(registry)
+#### Basic authentication
 
-# If you want to replace any previously pushed metrics for a given instance,
-# use the #replace method.
-Prometheus::Client::Push.new('my-batch-job').replace(registry)
+By design, `Prometheus::Client::Push` doesn't read credentials for HTTP basic
+authentication when they are passed in via the gateway URL using the
+`http://user:password@example.com:9091` syntax, and will in fact raise an error if they're
+supplied that way.
 
-# If you want to delete all previously pushed metrics for a given instance,
-# use the #delete method.
-Prometheus::Client::Push.new('my-batch-job').delete
+The reason for this is that when using that syntax, the username and password
+have to follow the usual rules for URL encoding of characters [per RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1).
+
+Rather than place the burden of correctly performing that encoding on users of this gem,
+we decided to have a separate method for supplying HTTP basic authentication credentials,
+with no requirement to URL encode the characters in them.
+
+Instead of passing credentials like this:
+
+```ruby
+push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://user:password@localhost:9091")
+```
+
+please pass them like this:
+
+```ruby
+push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://localhost:9091")
+push.basic_auth("user", "password")
 ```
 
 ## Metrics
@@ -151,6 +198,11 @@ histogram.get(labels: { service: 'users' })
 # => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }
 ```
 
+Histograms provide default buckets of `[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]`
+
+You can specify your own buckets, either explicitly, or using the `Histogram.linear_buckets`
+or `Histogram.exponential_buckets` methods to define regularly spaced buckets.
+
 ### Summary
 
 Summary, similar to histograms, is an accumulator for samples. It captures
@@ -175,17 +227,17 @@ summary_value['count'] # => 100
 All metrics can have labels, allowing grouping of related time series.
 
 Labels are an extremely powerful feature, but one that must be used with care.
-Refer to the best practices on [naming](https://prometheus.io/docs/practices/naming/) and 
+Refer to the best practices on [naming](https://prometheus.io/docs/practices/naming/) and
 [labels](https://prometheus.io/docs/practices/instrumentation/#use-labels).
 
-Most importantly, avoid labels that can have a large number of possible values (high 
+Most importantly, avoid labels that can have a large number of possible values (high
 cardinality). For example, an HTTP Status Code is a good label. A User ID is **not**.
 
 Labels are specified optionally when updating metrics, as a hash of `label_name => value`.
-Refer to [the Prometheus documentation](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) 
+Refer to [the Prometheus documentation](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)
 as to what's a valid `label_name`.
 
-In order for a metric to accept labels, their names must be specified when first initializing 
+In order for a metric to accept labels, their names must be specified when first initializing
 the metric. Then, when the metric is updated, all the specified labels must be present.
 
 Example:
@@ -203,8 +255,8 @@ You can also "pre-set" some of these label values, if they'll always be the same
 need to specify them every time:
 
 ```ruby
-https_requests_total = Counter.new(:http_requests_total, 
-                                   docstring: '...', 
+https_requests_total = Counter.new(:http_requests_total,
+                                   docstring: '...',
                                    labels: [:service, :status_code],
                                    preset_labels: { service: "my_service" })
 
@@ -219,7 +271,7 @@ with a subset (or full set) of labels set, so that you can increment / observe t
 without having to specify the labels for every call.
 
 Moreover, if all the labels the metric can take have been pre-set, validation of the labels
-is done on the call to `with_labels`, and then skipped for each observation, which can 
+is done on the call to `with_labels`, and then skipped for each observation, which can
 lead to performance improvements. If you are incrementing a counter in a fast loop, you
 definitely want to be doing this.
 
@@ -230,8 +282,8 @@ Examples:
 
 ```ruby
 # in the metric definition:
-records_processed_total = registry.counter.new(:records_processed_total, 
-                                               docstring: '...', 
+records_processed_total = registry.counter.new(:records_processed_total,
+                                               docstring: '...',
                                                labels: [:service, :component],
                                                preset_labels: { service: "my_service" })
 
@@ -244,16 +296,22 @@ class MyComponent
   def metric
     @metric ||= records_processed_total.with_labels(component: "my_component")
   end
-  
+
   def process
     records.each do |record|
       # process the record
-      metric.increment 
+      metric.increment
     end
   end
 end
 ```
 
+### `init_label_set`
+
+The time series of a metric are not initialized until something happens. For counters, for example, this means that the time series do not exist until the counter is incremented for the first time.
+
+To get around this problem the client provides the `init_label_set` method that can be used to initialise the time series of a metric for a given label set.
+
 ### Reserved labels
 
 The following labels are reserved by the client library, and attempting to use them in a
@@ -266,7 +324,7 @@ metric definition will result in a
 
 ## Data Stores
 
-The data for all the metrics (the internal counters associated with each labelset) 
+The data for all the metrics (the internal counters associated with each labelset)
 is stored in a global Data Store object, rather than in the metric objects themselves.
 (This "storage" is ephemeral, generally in-memory, it's not "long-term storage")
 
@@ -276,12 +334,12 @@ example), require a shared store between all the processes, to be able to report
 numbers. At the same time, other applications may not have this requirement but be very
 sensitive to performance, and would prefer instead a simpler, faster store.
 
-By having a standardized and simple interface that metrics use to access this store, 
+By having a standardized and simple interface that metrics use to access this store,
 we abstract away the details of storing the data from the specific needs of each metric.
-This allows us to then simply swap around the stores based on the needs of different 
-applications, with no changes to the rest of the client. 
+This allows us to then simply swap around the stores based on the needs of different
+applications, with no changes to the rest of the client.
 
-The client provides 3 built-in stores, but if neither of these is ideal for your 
+The client provides 3 built-in stores, but if neither of these is ideal for your
 requirements, you can easily make your own store and use that instead. More on this below.
 
 ### Configuring which store to use.
@@ -299,7 +357,7 @@ NOTE: You **must** make sure to set the `data_store` before initializing any met
 If using Rails, you probably want to set up your Data Store on `config/application.rb`,
 or `config/environments/*`, both of which run before `config/initializers/*`
 
-Also note that `config.data_store` is set to an *instance* of a `DataStore`, not to the 
+Also note that `config.data_store` is set to an *instance* of a `DataStore`, not to the
 class. This is so that the stores can receive parameters. Most of the built-in stores
 don't require any, but `DirectFileStore` does, for example.
 
@@ -307,9 +365,9 @@ When instantiating metrics, there is an optional `store_settings` attribute. Thi
 to set up store-specific settings for each metric. For most stores, this is not used, but
 for multi-process stores, this is used to specify how to aggregate the values of each
 metric across multiple processes. For the most part, this is used for Gauges, to specify
-whether you want to report the `SUM`, `MAX` or `MIN` value observed across all processes.
-For almost all other cases, you'd leave the default (`SUM`). More on this on the 
-*Aggregation* section below.
+whether you want to report the `SUM`, `MAX`, `MIN`, or `MOST_RECENT` value observed across
+all processes. For almost all other cases, you'd leave the default (`SUM`). More on this
+on the *Aggregation* section below.
 
 Custom stores may also accept extra parameters besides `:aggregation`. See the
 documentation of each store for more details.
@@ -318,52 +376,79 @@ documentation of each store for more details.
 
 There are 3 built-in stores, with different trade-offs:
 
-- **Synchronized**: Default store. Thread safe, but not suitable for multi-process 
+- **Synchronized**: Default store. Thread safe, but not suitable for multi-process
   scenarios (e.g. pre-fork servers, like Unicorn). Stores data in Hashes, with all accesses
-  protected by Mutexes. 
+  protected by Mutexes.
 - **SingleThreaded**: Fastest store, but only suitable for single-threaded scenarios.
-  This store does not make any effort to synchronize access to its internal hashes, so 
+  This store does not make any effort to synchronize access to its internal hashes, so
   it's absolutely not thread safe.
 - **DirectFileStore**: Stores data in binary files, one file per process and per metric.
-  This is generally the recommended store to use with pre-fork servers and other 
+  This is generally the recommended store to use with pre-fork servers and other
   "multi-process" scenarios. There are some important caveats to using this store, so
   please read on the section below.
 
 ### `DirectFileStore` caveats and things to keep in mind
 
 Each metric gets a file for each process, and manages its contents by storing keys and
-binary floats next to them, and updating the offsets of those Floats directly. When 
-exporting metrics, it will find all the files that apply to each metric, read them, 
+binary floats next to them, and updating the offsets of those Floats directly. When
+exporting metrics, it will find all the files that apply to each metric, read them,
 and aggregate them.
 
 **Aggregation of metrics**: Since there will be several files per metrics (one per process),
 these need to be aggregated to present a coherent view to Prometheus. Depending on your
-use case, you may need to control how this works. When using this store, 
+use case, you may need to control how this works. When using this store,
 each Metric allows you to specify an `:aggregation` setting, defining how
 to aggregate the multiple possible values we can get for each labelset. By default,
 Counters, Histograms and Summaries are `SUM`med, and Gauges report all their values (one
-for each process), tagged with a `pid` label. You can also select `SUM`, `MAX` or `MIN`
-for your gauges, depending on your use case.
+for each process), tagged with a `pid` label. You can also select `SUM`, `MAX`, `MIN`, or
+`MOST_RECENT` for your gauges, depending on your use case.
+
+Please note that the `MOST_RECENT` aggregation only works for gauges, and it does not
+allow the use of `increment` / `decrement`, you can only use `set`.
 
 **Memory Usage**: When scraped by Prometheus, this store will read all these files, get all
 the values and aggregate them. We have notice this can have a noticeable effect on memory
 usage for your app. We recommend you test this in a realistic usage scenario to make sure
 you won't hit any memory limits your app may have.
 
-**Resetting your metrics on each run**: You should also make sure that the directory where 
-you store your metric files (specified when initializing the `DirectFileStore`) is emptied 
-when your app starts. Otherwise, each app run will continue exporting the metrics from the 
-previous run.  
+**Resetting your metrics on each run**: You should also make sure that the directory where
+you store your metric files (specified when initializing the `DirectFileStore`) is emptied
+when your app starts. Otherwise, each app run will continue exporting the metrics from the
+previous run.
+
+If you have this issue, one way to do this is to run code similar to this as part of you
+initialization:
+
+```ruby
+Dir["#{app_path}/tmp/prometheus/*.bin"].each do |file_path|
+  File.unlink(file_path)
+end
+```
+
+If you are running in pre-fork servers (such as Unicorn or Puma with multiple processes),
+make sure you do this **before** the server forks. Otherwise, each child process may delete
+files created by other processes on *this* run, instead of deleting old files.
+
+**Declare metrics before fork**: As well as deleting files before your process forks, you
+should make sure to declare your metrics before forking too. Because the metric registry
+is held in memory, any metrics declared after forking will only be present in child
+processes where the code declaring them ran, and as a result may not be consistently
+exported when scraped (i.e. they will only appear when a child process that declared them
+is scraped).
+
+If you're absolutely sure that every child process will run the metric declaration code,
+then you won't run into this issue, but the simplest approach is to declare the metrics
+before forking.
 
-**Large numbers of files**: Because there is an individual file per metric and per process 
-(which is done to optimize for observation performance), you may end up with a large number 
+**Large numbers of files**: Because there is an individual file per metric and per process
+(which is done to optimize for observation performance), you may end up with a large number
 of files. We don't currently have a solution for this problem, but we're working on it.
 
-**Performance**: Even though this store saves data on disk, it's still much faster than 
-would probably be expected, because the files are never actually `fsync`ed, so the store 
-never blocks while waiting for disk. The kernel's page cache is incredibly efficient in 
-this regard. If in doubt, check the benchmark scripts described in the documentation for 
-creating your own stores and run them in your particular runtime environment to make sure 
+**Performance**: Even though this store saves data on disk, it's still much faster than
+would probably be expected, because the files are never actually `fsync`ed, so the store
+never blocks while waiting for disk. The kernel's page cache is incredibly efficient in
+this regard. If in doubt, check the benchmark scripts described in the documentation for
+creating your own stores and run them in your particular runtime environment to make sure
 this provides adequate performance.
 
 
@@ -372,7 +457,7 @@ this provides adequate performance.
 If none of these stores is suitable for your requirements, you can easily make your own.
 
 The interface and requirements of Stores are specified in detail in the `README.md`
-in the `client/data_stores` directory. This thoroughly documents how to make your own 
+in the `client/data_stores` directory. This thoroughly documents how to make your own
 store.
 
 There are also links there to non-built-in stores created by others that may be useful,
@@ -384,16 +469,16 @@ If you are in a multi-process environment (such as pre-fork servers like Unicorn
 process will probably keep their own counters, which need to be aggregated when receiving
 a Prometheus scrape, to report coherent total numbers.
 
-For Counters, Histograms and quantile-less Summaries this is simply a matter of 
+For Counters, Histograms and quantile-less Summaries this is simply a matter of
 summing the values of each process.
 
-For Gauges, however, this may not be the right thing to do, depending on what they're 
+For Gauges, however, this may not be the right thing to do, depending on what they're
 measuring. You might want to take the maximum or minimum value observed in any process,
 rather than the sum of all of them. By default, we export each process's individual
 value, with a `pid` label identifying each one.
 
-If these defaults don't work for your use case, you should use the `store_settings` 
-parameter when registering the metric, to specify an `:aggregation` setting. 
+If these defaults don't work for your use case, you should use the `store_settings`
+parameter when registering the metric, to specify an `:aggregation` setting.
 
 ```ruby
 free_disk_space = registry.gauge(:free_disk_space_bytes,
@@ -404,8 +489,8 @@ free_disk_space = registry.gauge(:free_disk_space_bytes,
 NOTE: This will only work if the store you're using supports the `:aggregation` setting.
 Of the built-in stores, only `DirectFileStore` does.
 
-Also note that the `:aggregation` setting works for all metric types, not just for gauges. 
-It would be unusual to use it for anything other than gauges, but if your use-case 
+Also note that the `:aggregation` setting works for all metric types, not just for gauges.
+It would be unusual to use it for anything other than gauges, but if your use-case
 requires it, the store will respect your aggregation wishes.
 
 ## Tests
@@ -419,9 +504,8 @@ rake
 
 [1]: https://github.com/prometheus/prometheus
 [2]: http://rack.github.io/
-[3]: https://secure.travis-ci.org/prometheus/client_ruby.svg?branch=master
+[3]: https://circleci.com/gh/prometheus/client_ruby/tree/main.svg?style=svg
 [4]: https://badge.fury.io/rb/prometheus-client.svg
-[7]: https://coveralls.io/repos/prometheus/client_ruby/badge.svg?branch=master
 [8]: https://github.com/prometheus/pushgateway
 [9]: lib/prometheus/middleware/exporter.rb
 [10]: lib/prometheus/middleware/collector.rb

data/lib/prometheus/client/data_stores/README.md

@@ -187,7 +187,7 @@ has created a good amount of research, benchmarks, and experimental stores, whic
 weren't useful to include in this repo, but may be a useful resource or starting point 
 if you are building your own store.
 
-Check out the [GoCardless Data Stores Experiments](gocardless/prometheus-client-ruby-data-stores-experiments) 
+Check out the [GoCardless Data Stores Experiments](https://github.com/gocardless/prometheus-client-ruby-data-stores-experiments) 
 repository for these.
 
 ## Sample, imaginary multi-process Data Store