Skip to content

v3.0.0 / 2022-02-05
Compare
Choose a tag to compare
@Sinjo Sinjo released this 05 Feb 18:51
v3.0.0
82d41f1
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

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.

Assets 2
Loading