Prometheus instrumentation library for Ruby applications
Codename: 🎃🦇 Spooky type conversion 🦇🎃
Codename: If a bug falls in the forest
#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!
Codename: Funny number
#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!
Codename: They finally made a point release
#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.
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.
This new major version includes some breaking changes. They should be reasonably easy to adapt to, but please read the details below:
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:
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.Prometheus::Client::Push
initializer now takes keyword arguments.grouping_key
) to uniquely
identify a job instance, rather than just an instance
label.+
instead of %20
, which resulted in
incorrect label values in the grouping key.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.grouping_key
don't clash with labels in the
metrics being submitted, and raise an error if they do.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.
#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.
init_label_set
method,
which allows declaration of time series on app startup, starting at 0.General availability of the Ruby Client. Includes support for pre-fork servers, better validation for labels, performance improvements, and a number of other updated. This version has been running in production at GoCardless for almost a year, and it's proven to be stable and work well.
If you are upgrading from v0.9, please notice this is a backwards-incompatible change. Please check out our Upgrading Document for more details.
If you will be using this in a pre-fork server environment, please read the Data Stores section in our README, especially the DirectFileStore caveats
section.