prometheus-client-mmap 1.2.4-x86_64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75f6095dd72062a0a926e19cf78bf292be57b468931ce5a2002d73e86aaa88b6
+  data.tar.gz: 531fbe088df28cd8dec9e8dff57617cb19d8fc653c56f1deff40c4256a5ce0ab
+SHA512:
+  metadata.gz: 6ff8cd19704e28db4aa11b60df2f46c4ac587a14e6c339ab7b2ce6521c52e65335d53ba742ac925a033dd94fb52e114b9a641b79c3e2db8b4360561ae1230e76
+  data.tar.gz: 3f1d481ed405405ab221d13736f5a72456e84a27617eb6a03f277830aa7ff174d49c269248429f4227f8ada1db7677649bdc1e680ccb35f081f23060f33f9fd7

data/.tool-versions

@@ -0,0 +1 @@
+rust 1.73.0

data/README.md

@@ -0,0 +1,281 @@
+# Prometheus Ruby Mmap Client
+
+This Prometheus library is fork of [Prometheus Ruby Client](https://github.com/prometheus/client_ruby)
+that uses mmap'ed files to share metrics from multiple processes.
+This allows efficient metrics processing for Ruby web apps running in multiprocess setups like Unicorn.
+
+A suite of instrumentation metric primitives for Ruby that can be exposed
+through a HTTP interface. Intended to be used together with a
+[Prometheus server][1].
+
+[![Gem Version][4]](http://badge.fury.io/rb/prometheus-client-mmap)
+[![Build Status][3]](https://gitlab.com/gitlab-org/prometheus-client-mmap/commits/master)
+
+## Installation
+
+prometheus-client-mmap ships with [precompiled native gems](https://rubygems.org/gems/prometheus-client-mmap).
+Install the gem via:
+
+```shell
+gem install prometheus-client-mmap
+```
+
+### Requirements for building from source
+
+Building from source requires a number of dependencies:
+
+* Rust v1.65+
+* clang 5.0 or higher for [bindgen](https://rust-lang.github.io/rust-bindgen/requirements.html)
+* `make`
+* A C compiler (for legacy extension, which will be removed soon)
+
+## Usage
+
+### Overview
+
+```ruby
+require 'prometheus/client'
+
+# returns a default registry
+prometheus = Prometheus::Client.registry
+
+# create a new counter metric
+http_requests = Prometheus::Client::Counter.new(:http_requests, 'A counter of HTTP requests made')
+# register the metric
+prometheus.register(http_requests)
+
+# equivalent helper function
+http_requests = prometheus.counter(:http_requests, 'A counter of HTTP requests made')
+
+# start using the counter
+http_requests.increment
+```
+
+## Rust extension
+
+This gem now uses a rewritten Rust extension instead of C.
+implementation that reads the metric files and outputs the multiprocess
+metrics to text. This implementation is significantly faster than the C extension.
+
+### Rack middleware
+
+There are two [Rack][2] middlewares available, one to expose a metrics HTTP
+endpoint to be scraped by a prometheus server ([Exporter][9]) and one to trace all HTTP
+requests ([Collector][10]).
+
+It's highly recommended to enable gzip compression for the metrics endpoint,
+for example by including the `Rack::Deflater` middleware.
+
+```ruby
+# config.ru
+
+require 'rack'
+require 'prometheus/client/rack/collector'
+require 'prometheus/client/rack/exporter'
+
+use Rack::Deflater, if: ->(env, status, headers, body) { body.any? && body[0].length > 512 }
+use Prometheus::Client::Rack::Collector
+use Prometheus::Client::Rack::Exporter
+
+run ->(env) { [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).
+
+For further instructions and other scripts to get started, have a look at the
+integrated [example application](examples/rack/README.md).
+
+### Pushgateway
+
+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 HTTP basic authentication are supported.
+
+```ruby
+require 'prometheus/client'
+require 'prometheus/client/push'
+
+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(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
+```
+
+## Metrics
+
+The following metric types are currently supported.
+
+### Counter
+
+Counter is a metric that exposes merely a sum or tally of things.
+
+```ruby
+counter = Prometheus::Client::Counter.new(:service_requests_total, '...')
+
+# increment the counter for a given label set
+counter.increment({ service: 'foo' })
+
+# increment by a given value
+counter.increment({ service: 'bar' }, 5)
+
+# get current value for a given label set
+counter.get({ service: 'bar' })
+# => 5
+```
+
+### Gauge
+
+Gauge is a metric that exposes merely an instantaneous value or some snapshot
+thereof.
+
+```ruby
+gauge = Prometheus::Client::Gauge.new(:room_temperature_celsius, '...')
+
+# set a value
+gauge.set({ room: 'kitchen' }, 21.534)
+
+# retrieve the current value for a given label set
+gauge.get({ room: 'kitchen' })
+# => 21.534
+```
+
+### Histogram
+
+A histogram samples observations (usually things like request durations or
+response sizes) and counts them in configurable buckets. It also provides a sum
+of all observed values.
+
+```ruby
+histogram = Prometheus::Client::Histogram.new(:service_latency_seconds, '...')
+
+# record a value
+histogram.observe({ service: 'users' }, Benchmark.realtime { service.call(arg) })
+
+# retrieve the current bucket values
+histogram.get({ service: 'users' })
+# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }
+```
+
+### Summary
+
+Summary, similar to histograms, is an accumulator for samples. It captures
+Numeric data and provides an efficient percentile calculation mechanism.
+
+```ruby
+summary = Prometheus::Client::Summary.new(:service_latency_seconds, '...')
+
+# record a value
+summary.observe({ service: 'database' }, Benchmark.realtime { service.call() })
+
+# retrieve the current quantile values
+summary.get({ service: 'database' })
+# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }
+```
+
+## Configuration
+
+### Memory mapped files storage location
+
+Set `prometheus_multiproc_dir` environment variable to the path where you want metric files to be stored. Example:
+
+```
+prometheus_multiproc_dir=/tmp
+```
+
+## Pitfalls
+
+### PID cardinality
+
+In multiprocess setup e.g. running under Unicorn or Puma, having worker process restart often
+can lead to performance problems when proccesing metric files. By default each process using
+Prometheus metrics will create a set of files based on that process PID. With high worker
+churn this will lead to creation of thousands of files and in turn will cause very noticable
+slowdown when displaying metrics
+
+To reduce this problem, a surrogate process id can be used. Set of all such IDs needs
+have low cardinality, and each process id must be unique among all running process.
+
+For Unicorn and Puma a worker id/number can be used to greatly speedup the metrics rendering.
+
+If you are using Unicorn, add this line to your `configure` block:
+
+```ruby
+  config.pid_provider = Prometheus::Client::Support::Unicorn.method(:worker_pid_provider)
+```
+
+If you are using Puma, add this line to your `configure` block:
+
+```ruby
+  config.pid_provider = Prometheus::Client::Support::Puma.method(:worker_pid_provider)
+```
+
+## Tools
+
+### `bin/parse`
+
+This command can be used to parse metric files located on the filesystem just like a metric exporter would.
+It outputs either `json` formatted raw data or digested data in prometheus `text` format.
+
+#### Usage:
+
+```bash
+$ ./bin/parse -h
+Usage: parse [options] files...
+    -t, --to-prometheus-text         format output using Prometheus text formatter
+    -p, --profile                    enable profiling
+    -h, --help                       Show this message
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Releasing a new version
+
+To release a new version:
+
+1. Update `lib/prometheus/client/version.rb` with the version number.
+1. Update `CHANGELOG.md` with the changes in the release.
+1. Create a merge request and merge it to `master`.
+1. Push a new tag to the repository.
+
+The new version with precompiled, native gems will automatically be
+published to [RubyGems](https://rubygems.org/gems/prometheus-client-mmap) when the
+pipeline for the tag completes.
+
+[1]: https://github.com/prometheus/prometheus
+[2]: http://rack.github.io/
+[3]: https://gitlab.com/gitlab-org/prometheus-client-mmap/badges/master/pipeline.svg
+[4]: https://badge.fury.io/rb/prometheus-client.svg
+[8]: https://github.com/prometheus/pushgateway
+[9]: lib/prometheus/client/rack/exporter.rb
+[10]: lib/prometheus/client/rack/collector.rb

data/ext/fast_mmaped_file_rs/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "fast_mmaped_file_rs"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+hashbrown = "0.14"
+libc = "0.2"
+magnus = { version = "0.7", features = ["rb-sys"] }
+memmap2 = "0.9"
+# v0.26 cannot be built on CentOS 7 https://github.com/nix-rust/nix/issues/1972
+nix = { version = "0.25", features = ["mman"] } # mman used for MsFlags
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = { version = "1.0", features = ["raw_value"] }
+smallvec = { version = "1.13", features = ["serde"] }
+thiserror = "2.0"
+
+[dev-dependencies]
+bstr = "1.11"
+indoc = "2.0"
+# We need the `embed` feature to run tests, but this triggers failures when building as a Gem.
+magnus = { version = "0.7", features = ["rb-sys","embed"] }
+rand = "0.8"
+sha2 = "0.10"
+tempfile = "3.14"
+
+[build-dependencies]
+rb-sys-env = { git = "https://github.com/oxidize-rb/rb-sys.git", rev = "5d1999ba70d301581524b8252c8ff3b8a825afa2" }
+
+[lib]
+# Integration tests won't work if crate is only `cdylib`.
+crate-type = ["cdylib","lib"]

data/ext/fast_mmaped_file_rs/README.md

@@ -0,0 +1,52 @@
+# Testing
+
+## Running Tests
+
+Use [cargo nextest](https://nexte.st/) to execute the Rust unit tests.
+
+```sh
+$ cargo nextest run
+```
+
+## Why not use 'cargo test'?
+
+We need to embed Ruby into the test binary to access Ruby types. This requires
+us to run `magnus::embed::init()` no more than once before calling Ruby.
+See [the magnus docs](https://docs.rs/magnus/latest/magnus/embed/fn.init.html)
+for more details.
+
+If we try to create separate `#[test]` functions that call `init()` these will
+conflict, as Cargo runs tests in parallel using a single process with separate
+threads. Running `cargo test` will result in errors like:
+
+```
+---- file_info::test::with_ruby stdout ----
+thread 'file_info::test::with_ruby' panicked at 'Ruby already initialized'
+```
+
+The simplest workaround for this is to avoid using `cargo test` to run unit
+tests. [nextest](https://nexte.st/) is an alternate test harness that runs each
+test as its own process, enabling each test to intitialize Ruby without
+conflict.
+
+## 'symbol not found' errors when running tests
+
+If you see errors like the following when running tests:
+
+```
+Caused by:
+  for `fast_mmaped_file_rs`, command `/Users/myuser/prometheus-client-mmap/ext/fast_mmaped_file_rs/target/debug/deps/fast_mmaped_file_rs-c81ccc96a6484e04 --list --format terse` exited with signal 6 (SIGABRT)
+--- stdout:
+
+--- stderr:
+dyld[17861]: symbol not found in flat namespace '_rb_cArray'
+```
+
+Clearing the build cache will resolve the problem.
+
+```sh
+$ cargo clean
+```
+
+This is probably due to separate features being used with `magnus` in
+development builds.

data/ext/fast_mmaped_file_rs/build.rs

@@ -0,0 +1,5 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let _ = rb_sys_env::activate()?;
+
+    Ok(())
+}

data/ext/fast_mmaped_file_rs/extconf.rb

@@ -0,0 +1,28 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+if find_executable('rustc')
+  create_rust_makefile("fast_mmaped_file_rs") do |r|
+    r.auto_install_rust_toolchain = false
+
+    if enable_config('fail-on-warning')
+      r.extra_rustflags = ["-Dwarnings"]
+    end
+
+    if enable_config('debug')
+      r.profile = :dev
+    end
+
+    if enable_config('address-sanitizer')
+      r.extra_rustflags = ["-Zsanitizer=address"]
+    end
+
+    # `rb_sys/mkmf` passes all arguments after `--` directly to `cargo rustc`.
+    # We use this awful hack to keep compatibility with existing flags used by
+    # the C implementation.
+    trimmed_argv = ARGV.take_while { |arg| arg != "--" }
+    ARGV = trimmed_argv
+  end
+else
+  raise 'rustc not found. prometheus-client-mmap now requires Rust.'
+end

data/ext/fast_mmaped_file_rs/src/error.rs

@@ -0,0 +1,174 @@
+use magnus::{exception, Ruby};
+use std::any;
+use std::fmt::Display;
+use std::io;
+use std::path::Path;
+use thiserror::Error;
+
+use crate::util;
+use crate::PROM_EPARSING_ERROR;
+
+/// A lightweight representation of Ruby ExceptionClasses.
+#[derive(PartialEq, Eq, Clone, Copy, Debug)]
+pub enum RubyError {
+    Arg,
+    Encoding,
+    Frozen,
+    Index,
+    Io,
+    NoMem,
+    PromParsing,
+    Runtime,
+    Type,
+}
+
+impl From<RubyError> for magnus::ExceptionClass {
+    fn from(err: RubyError) -> magnus::ExceptionClass {
+        match err {
+            RubyError::Arg => exception::arg_error(),
+            RubyError::Encoding => exception::encoding_error(),
+            RubyError::Frozen => exception::frozen_error(),
+            RubyError::Index => exception::index_error(),
+            RubyError::Io => exception::io_error(),
+            RubyError::NoMem => exception::no_mem_error(),
+            RubyError::Runtime => exception::runtime_error(),
+            RubyError::PromParsing => {
+                // UNWRAP: this will panic if called outside of a Ruby thread.
+                let ruby = Ruby::get().unwrap();
+                ruby.get_inner(&PROM_EPARSING_ERROR)
+            }
+            RubyError::Type => exception::type_error(),
+        }
+    }
+}
+
+/// Errors returned internally within the crate. Methods called directly by Ruby return
+/// `magnus::error::Error` as do functions that interact heavily with Ruby. This can be
+/// converted into a `magnus::error::Error` at the boundary between Rust and Ruby.
+#[derive(PartialEq, Eq, Error, Debug)]
+pub enum MmapError {
+    /// A read or write was made while another thread had mutable access to the mmap.
+    #[error("read/write operation attempted while mmap was being written to")]
+    ConcurrentAccess,
+    /// An error message used to exactly match the messages returned by the C
+    /// implementation.
+    #[error("{0}")]
+    Legacy(String, RubyError),
+    /// A String had invalid UTF-8 sequences.
+    #[error("{0}")]
+    Encoding(String),
+    /// A failed attempt to cast an integer from one type to another.
+    #[error("failed to cast {object_name} {value} from {from} to {to}")]
+    FailedCast {
+        from: &'static str,
+        to: &'static str,
+        value: String,
+        object_name: String,
+    },
+    /// The mmap was frozen when a mutable operation was attempted.
+    #[error("mmap")]
+    Frozen,
+    /// An io operation failed.
+    #[error("failed to {operation} path '{path}': {err}")]
+    Io {
+        operation: String,
+        path: String,
+        err: String,
+    },
+    #[error("string length gt {}", i32::MAX)]
+    KeyLength,
+    /// Failed to allocate memory.
+    #[error("Couldn't allocate for {0} memory")]
+    OutOfMemory(usize),
+    /// A memory operation fell outside of the containers bounds.
+    #[error("offset {index} out of bounds of len {len}")]
+    OutOfBounds { index: String, len: String },
+    /// A numeric operation overflowed.
+    #[error("overflow when {op} {value} and {added} of type {ty}")]
+    Overflow {
+        value: String,
+        added: String,
+        op: String,
+        ty: &'static str,
+    },
+    /// A miscellaneous error.
+    #[error("{0}")]
+    Other(String),
+    /// A failure when parsing a `.db` file containing Prometheus metrics.
+    #[error("{0}")]
+    PromParsing(String),
+    /// No mmap open.
+    #[error("unmapped file")]
+    UnmappedFile,
+    /// A custom error message with `strerror(3)` appended.
+    #[error("{0}")]
+    WithErrno(String),
+}
+
+impl MmapError {
+    pub fn legacy<T: Into<String>>(msg: T, ruby_err: RubyError) -> Self {
+        MmapError::Legacy(msg.into(), ruby_err)
+    }
+
+    pub fn failed_cast<T: Display, U>(value: T, object_name: &str) -> Self {
+        MmapError::FailedCast {
+            from: any::type_name::<T>(),
+            to: any::type_name::<U>(),
+            value: value.to_string(),
+            object_name: object_name.to_string(),
+        }
+    }
+    pub fn io(operation: &str, path: &Path, err: io::Error) -> Self {
+        MmapError::Io {
+            operation: operation.to_string(),
+            path: path.display().to_string(),
+            err: err.to_string(),
+        }
+    }
+
+    pub fn overflowed<T: Display>(value: T, added: T, op: &str) -> Self {
+        MmapError::Overflow {
+            value: value.to_string(),
+            added: added.to_string(),
+            op: op.to_string(),
+            ty: any::type_name::<T>(),
+        }
+    }
+
+    pub fn out_of_bounds<T: Display>(index: T, len: T) -> Self {
+        MmapError::OutOfBounds {
+            index: index.to_string(),
+            len: len.to_string(),
+        }
+    }
+
+    pub fn with_errno<T: Into<String>>(msg: T) -> Self {
+        let strerror = util::strerror(util::errno());
+        MmapError::WithErrno(format!("{}: ({strerror})", msg.into()))
+    }
+
+    pub fn ruby_err(&self) -> RubyError {
+        match self {
+            MmapError::ConcurrentAccess => RubyError::Arg,
+            MmapError::Legacy(_, e) => *e,
+            MmapError::Encoding(_) => RubyError::Encoding,
+            MmapError::Io { .. } => RubyError::Io,
+            MmapError::FailedCast { .. } => RubyError::Arg,
+            MmapError::Frozen => RubyError::Frozen,
+            MmapError::KeyLength => RubyError::Arg,
+            MmapError::Overflow { .. } => RubyError::Arg,
+            MmapError::OutOfBounds { .. } => RubyError::Index,
+            MmapError::OutOfMemory { .. } => RubyError::NoMem,
+            MmapError::Other(_) => RubyError::Arg,
+            MmapError::PromParsing(_) => RubyError::PromParsing,
+            MmapError::UnmappedFile => RubyError::Io,
+            MmapError::WithErrno(_) => RubyError::Io,
+        }
+    }
+}
+
+impl From<MmapError> for magnus::error::Error {
+    fn from(err: MmapError) -> magnus::error::Error {
+        magnus::error::Error::new(err.ruby_err().into(), err.to_string())
+    }
+}