CHANGELOG.md

CHANGELOG

Unreleased changes

None outstanding

4.2.5 / 2025-07-05

Codename: Surprise dependency

Small improvements

• #324 Do not use benchmark gem in production: Ruby 3.5 is moving Benchmark out of default gems, so we need to explicitly install it from Rubygems in dev. It turned out we were also using it in prod code, so this PR replaced that usage with a small method that makes calls to Process.clock_gettime(Process::CLOCK_MONOTONIC).

4.2.4 / 2025-02-02

Codename: FOSDEM 25th Anniversary Edition

Small improvements

• #316 Use binary search for histogram buckets: This change speeds up observations in histogram metrics by using a binary search rather than a sequential search through the bucket array. This is possible because we enforce that histogram buckets are sorted at initialization.

4.2.3 / 2024-06-28

Codename: Now with 25% fewer test dependencies!

Small improvements

• #308 Declare base64 gem dependency, ready for Ruby 3.4: Ruby 3.4 and above will require an explicit dependency on base64 as it will no longer be included with CRuby. This gets us ready for that change.

4.2.2 / 2023-10-31

Codename: 🎃🦇 Spooky type conversion 🦇🎃

Bug fixes

• #296 Stringify non-string job names in push client: Previously, an error would be raised if you passed a symbol as the job name, which is inconsistent with how we handle label values in the rest of the client. This change converts the job name to a string before trying to use it.
• #297 Stringify grouping key values in push client: Same thing as #296, but for grouping key values.

4.2.1 / 2023-08-04

Codename: If a bug falls in the forest

Bug fixes

• #291 Handle / in job name in Prometheus::Client::Push: Previously, if you included a / in your job name when using the Pushgateway client, you'd get a 400 error back as we didn't encode it properly. We now base64 encode it per the Pushgateway spec.

  It's possible that nobody has hit this bug (/ is fairly unlikely to appear in a job name) or that the error message (a 400 from Pushgateway with a complaint about an odd number of path components) didn't make it look like a bug in the Ruby client. Either way, this hopefully brings us fully in line with the spec!

4.2.0 / 2023-07-25

Codename: Funny number

Small improvements

• #287 Add Gauge#set_to_current_time: Does what you'd expect - sets a gauge to the current unix epoch timestamp (including fractional seconds).

  Other client libraries have this and it's about time we did!

4.1.0 / 2023-03-20

Codename: They finally made a point release

Small improvements

• #264 Add JRuby 9.3 to build matrix: JRuby 9.3 was released, and added as an officially supported version

• #273 Add Ruby 3.2 to build matrix: Ruby 3.2 was released, and added as an officially supported version

• #280 Optimize incrementing values in DirectFileStore adapter: There were some expensive method calls being made multiple times when they didn't need to be for simple increments. This PR introduces a specialised implementation for that case.

• #277 Allow use of instance and job labels: It's now possible to set the instance and job labels on metrics, where previously they had been reserved.

  The reason we'd reserved them is that Prometheus automatically generates values for them when it scrapes a target, and we didn't want to cause a collision. It turns out Prometheus handles that collision just fine.

  By default, Prometheus server will prepend exported_ to them if they're present in the scraped data (i.e. exported_instance and exported_job). Users can set honor_labels in their Prometheus server config if they prefer the labels from the scraped metric data to take precedence over the labels generated by the server.

Bug fixes

• #268 Use lowercase response headers in Rack example: Rack 3.0.0 started requiring this for compatibility with HTTP/2
• #271 Use lowercase for HTTP headers in middleware: Fixes the same issue from above in our middleware
• #270 Small compatibility fixes in Rack example: Apple have taken port 5000 for AirPlay, so we had to move away from it. Go has changed how you install binaries, so we updated those instructions too.

4.0.0 / 2022-03-27

Codename: The "barely a release" release

This version contains a single - sadly breaking - change.

• #251 Remove framework-specific route detection from collector middleware: In 3.0.0 we shipped a feature that attempted to use framework-specific information to determine the path of the request in Prometheus::Middleware::Collector.

  Sadly, we found out after shipping it that it was prone to multiple issues. We spent a decent amount of time looking into them in depth, and came to the conclusion that there wasn't any reasonable way to fix them - the issues are inherent to the feature.

  For a full, detailed write-up of our investigation, see this comment.

  Almost all users will be unaffected by this change, but it is breaking per the definition we've used for previous releases, so we've erred on the side of caution and bumped the major version to communicate that.

  If you use Sinatra or Grape with the Prometheus::Middleware::Collector, you will notice different path labels being generated. If not, this release will change nothing for you.

  If you want the behaviour from 3.0.0 - or any custom path label generation you'd prefer - we've updated our collector middleware documentation.

  This may be a breaking change. Labels may change in existing metrics.

3.0.0 / 2022-02-05

This new major version includes some breaking changes. They should be reasonably easy to adapt to, but please read the details below:

Breaking changes

Please refer to UPGRADING.md for details on upgrading from versions < 3.0.0.

• #206 Include SCRIPT_NAME when determining path in Collector: When determining the path for a request, Rack::Request prefixes the SCRIPT_NAME. This was a problem with our code when using mountable engines, where the engine part of the path gets lost. This patch fixes that to include SCRIPT_NAME as part of the path.

  This may be a breaking change. Labels may change in existing metrics.

• #245 Use framework-specific route info and handle consecutive path segments containing IDs in Collector: When generating the path label, we now use framework-specific information from the request environment to produce better labels for apps written in the Sinatra and Grape frameworks. Rails doesn't provide the information we need to do the same there, but we hope to get such functionality added in a future release.

  Our framework-agnostic fallback (which Rails apps will use) has also been improved. It now supports stripping IDs/UUIDs from consecutive path segments, where previously only alternating segments would be correctly stripped.

  This may be a breaking change. Labels may change in existing metrics.

• #209 Automatically initialize metrics without labels. Following the Prometheus Best Practices, client libraries are expected to automatically export a 0 value when declaring a metric that has no labels. We missed this recommendation in the past, and this wasn't happening. Starting from this version, all metrics without labels will be immediately exported with 0 value, without need for an increment / observation.

  This may be a breaking change. Depending on your particular metrics, this may result in a significant increase to the number of time series being exported. We recommend you test this and make sure it doesn't cause problems.

• #220 and #234 Improvements to Pushgateway client:

  • The job parameter is now mandatory when instantiating Prometheus::Client::Push and will raise ArgumentError if not specified, or if nil or an empty string/object are passed.
  • The Prometheus::Client::Push initializer now takes keyword arguments.
  • You can now pass a set of arbitrary key-value pairs (grouping_key) to uniquely identify a job instance, rather than just an instance label.
  • Fixed URI escaping of spaces in the path when pushing to to Pushgateway. In the past, spaces were being encoded as + instead of %20, which resulted in incorrect label values in the grouping key.
  • We now correctly encode special values in job and grouping_key that can't ordinarily be represented in the URL. This mean you can have a forward slash (/) in a grouping key label value, or set one to the empty string.
  • We validate that labels in your grouping_key don't clash with labels in the metrics being submitted, and raise an error if they do.
  • We raise an error on a non-2xx HTTP response from the Pushgateway.

  This is a breaking change if you use Pushgateway. You will need to update your code to pass keyword arguments to the Prometheus::Client::Push initializer.

• #242 Move HTTP Basic Authentication credentials in Prometheus::Client::Push to separate method call: In earlier versions, these were provided as part of the gateway URL, which had some significant downsides when it came to special characters in usernames/passwords.

  These credentials must now be passed via an explicit call to basic_auth on an instance of Prometheus::Client::Push.

  This is a breaking change if you use Pushgateway with HTTP Basic Authentication. You will need to update your code to call this method instead of including the credentials in the URL.

• #236 Validate label names: Previously, we didn't validate that label names match the character set required by Prometheus ([a-zA-Z_][a-zA-Z0-9_]*). As of this release, we raise an error if a metric is initialized with label names that don't match that regex.

  This is a breaking change. While it's likely that Prometheus server would have been failing to scrape metrics with such labels anyway, declaring them will now cause an error to be raised in your code.

• #237 Drop support for old Ruby versions: Ruby versions below 2.6 are no longer supported upstream, and client_ruby is no longer tested against them.

  This may be a breaking change. We no longer make efforts to ensure that client_ruby works on older versions, and any issues filed specific to them will be considered invalid.

New Features

• #199 Add port filtering option to Exporter middleware. You can now specify a port when adding Prometheus::Middleware::Exporter to your middleware chain, and metrics will only be exported if the /metrics request comes through that port.

• #222 Enable configuring Net::HTTP timeouts for Pushgateway calls. You can now specify open_timeout and read_timeout when instantiating Prometheus::Client::Push, to control these timeouts.

Code improvements and bug fixes

• #201 Make all registry methods thread safe.

• #227 Fix with_labels bug that made it completely non-functional, and occasionally resulted in DirectFileStore file corruption.

2.1.0 / 2020-06-29

New Features

• #177 Added Histogram helpers to generate linear and exponential buckets, as the Client Library Guidelines recommend.
• #172 Added :most_recent aggregation for gauges on DirectFileStore.

Code improvements

• Fixed several warnings that started firing in the latest versions of Ruby.

2.0.0 / 2020-01-28

Breaking changes

• #176 BUGFIX: Values observed at the upper limit of a histogram bucket are now counted in that bucket, not the following one. This is unlikely to break functionality and you probably don't need to make code changes, but it may break tests.

New features

• #156 Added init_label_set method, which allows declaration of time series on app startup, starting at 0.

1.0.0 / 2019-11-04

Breaking changes

• This release saw a number of breaking changes to better comply with latest best practices for naming and client behaviour. Please refer to UPGRADING.md for details if upgrading from <= 0.9.

• The main feature of this release was adding support for multi-process environments such as pre-fork servers (Unicorn, Puma).