prometheus_exporter 0.5.3 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a284b77cbd17e80457e94520d18976dc3dd6fb8c238d8a90cda6513e291f01ad
-  data.tar.gz: 4464419fc9c67d387edd9d6d5bdfac1411d0864d29c0cd3a6f10d2f02b3d7e24
+  metadata.gz: 47861f365c3db51e840d0c62e30120518dfc64fe208cc639ae6653903d14c578
+  data.tar.gz: 8e67b542b68012b0bd2cb64122eb2ba987a18eed1397449cab4363eea009ba44
 SHA512:
-  metadata.gz: 84c2e2af95a8839cd9deecca9fbc26bacff590ae5cb3677862f1eb1d476401114406130cc78d2248cec0380e70c1b74b306e1265b3343bbac9c09d8400e692a3
-  data.tar.gz: 41898546588ef7eafa772252ef5ed1a8c222e4009e64ccec35d463217336597a94f1c844f3e2174e030c19a7c1b90d1028e5729cc393cf797654362f5d66b7f2
+  metadata.gz: 1f4ff589012b8f28f81ee3b63f7535c1eb138c232826da36f1b621dc6381398e7fa515aca6b6413423e965630d23b47ad9b505801d418e3c9a625c7d7a0c7030
+  data.tar.gz: d457d6d2c60c11960b6b241d5f2e0864994f11f808624845b9f28a42968dc3b9da07214321631d9f1644b2fdcad4b5ad443c843c53416ad6326afae68bd4d879

data/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: Test Exporter
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '0 0 * * 0' # weekly
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby: ["3.0","2.7", "2.6"]
+    steps:
+      - uses: actions/checkout@master
+        with:
+          fetch-depth: 1
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - uses: actions/cache@v2
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-${{ matrix.ruby }}-gems-v2-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ matrix.ruby }}-gems-v2-
+      - name: Setup gems
+        run: |
+          gem install bundler
+          # for Ruby <= 2.6 , details https://github.com/rubygems/rubygems/issues/3284
+          gem update --system 3.0.8 && gem update --system
+          bundle config path vendor/bundle
+          bundle install --jobs 4
+          bundle exec appraisal install
+      - name: Rubocop
+        run: bundle exec rubocop
+      - name: install gems
+        run: bundle exec appraisal bundle
+      - name: Run tests
+        run: bundle exec appraisal rake

data/.gitignore

@@ -7,5 +7,7 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
+/gemfiles/*.gemfile.lock
+
 
 .rubocop-https---raw-githubusercontent-com-discourse-discourse-master--rubocop-yml

data/.rubocop.yml

@@ -1,2 +1,7 @@
 inherit_gem:
   rubocop-discourse: default.yml
+
+AllCops:
+  Exclude:
+    - 'gemfiles/**/*'
+    - 'vendor/**/*'

data/Appraisals

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+appraise "ar-60" do
+  # we are using this version as default in gemspec
+  # gem "activerecord", "~> 6.0.0"
+end
+
+appraise "ar-61" do
+  gem "activerecord", "~> 6.1.1"
+end

data/CHANGELOG

@@ -1,3 +1,31 @@
+0.8.1 - 04-08-2021
+
+- FEATURE: swap from hardcoded STDERR to logger pattern (see README for details)
+
+0.8.0 - 05-07-2021
+
+- FIX: handle ThreadError more gracefully in cases where process shuts down
+- FEATURE: add job_name and queue_name labels to delayed job metrics
+- FEATURE: always scope puma metrics on hostname in collector
+- FEATURE: add customizable labels option to puma collector
+- FEATURE: support for Resque
+- DEV: Remove support for EOL ruby 2.5
+- FIX: Add source location to MethodProfiler patches
+- FEATURE: Improve Active Record instrumentation
+- FEATURE: Support HTTP_X_AMZN_TRACE_ID when supplied
+
+0.7.0 - 29-12-2020
+
+- Dev: Removed support from EOL rubies, only 2.5, 2.6, 2.7 and 3.0 are supported now.
+- Dev: Better support for Ruby 3.0, explicitly depending on webrick
+- Dev: Rails 6.1 instrumentation support
+- FEATURE: clean pattern for overriding middleware labels was introduced (in README)
+- Fix: Better support for forking
+
+0.6.0 - 17-11-2020
+
+- FEATURE: add support for basic-auth in the prometheus_exporter web server
+
 0.5.3 - 29-07-2020
 
 - FEATURE: added #remove to all metric types so users can remove specific labels if needed

data/README.md

@@ -19,6 +19,7 @@ To learn more see [Instrumenting Rails with Prometheus](https://samsaffron.com/a
     * [Hutch metrics](#hutch-message-processing-tracer)
   * [Puma metrics](#puma-metrics)
   * [Unicorn metrics](#unicorn-process-metrics)
+  * [Resque metrics](#resque-metrics)
   * [Custom type collectors](#custom-type-collectors)
   * [Multi process mode with custom collector](#multi-process-mode-with-custom-collector)
   * [GraphQL support](#graphql-support)
@@ -27,13 +28,14 @@ To learn more see [Instrumenting Rails with Prometheus](https://samsaffron.com/a
   * [Client default host](#client-default-host)
 * [Transport concerns](#transport-concerns)
 * [JSON generation and parsing](#json-generation-and-parsing)
+* [Logging](#logging)
 * [Contributing](#contributing)
 * [License](#license)
 * [Code of Conduct](#code-of-conduct)
 
 ## Requirements
 
-Minimum Ruby of version 2.3.0 is required, Ruby 2.2.0 is EOL as of 2018-03-31
+Minimum Ruby of version 2.5.0 is required, Ruby 2.4.0 is EOL as of 2020-04-05
 
 ## Installation
 
@@ -200,12 +202,53 @@ $ bundle exec prometheus_exporter
 | Summary | `http_sql_duration_seconds`²    | Time spent in HTTP reqs in SQL in seconds                   |
 | Summary | `http_queue_duration_seconds`³  | Time spent queueing the request in load balancer in seconds |
 
-All metrics have a `controller` and an `action` label.  
-`http_requests_total` additionally has a (HTTP response) `status` label.  
+All metrics have a `controller` and an `action` label.
+`http_requests_total` additionally has a (HTTP response) `status` label.
 
-¹) Only available when Redis is used.  
-²) Only available when Mysql or PostgreSQL are used.  
-³) Only available when [Instrumenting Request Queueing Time](#instrumenting-request-queueing-time) is set up.  
+To add your own labels to the default metrics, create a subclass of `PrometheusExporter::Middleware`, override `custom_labels`, and use it in your initializer.
+```ruby
+class MyMiddleware < PrometheusExporter::Middleware
+  def custom_labels(env)
+    labels = {}
+
+    if env['HTTP_X_PLATFORM']
+      labels['platform'] = env['HTTP_X_PLATFORM']
+    end
+
+    labels
+  end
+end
+```
+
+If you're not using Rails like framework, you can extend `PrometheusExporter::Middleware#default_labels` in a way to add more relevant labels.
+For example you can mimic [prometheus-client](https://github.com/prometheus/client_ruby) labels with code like this:
+```ruby
+class MyMiddleware < PrometheusExporter::Middleware
+  def default_labels(env, result)
+    status = (result && result[0]) || -1
+    path = [env["SCRIPT_NAME"], env["PATH_INFO"]].join
+    {
+      path: strip_ids_from_path(path),
+      method: env["REQUEST_METHOD"],
+      status: status
+    }
+  end
+
+  def strip_ids_from_path(path)
+    path
+      .gsub(%r{/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(/|$)}, '/:uuid\\1')
+      .gsub(%r{/\d+(/|$)}, '/:id\\1')
+  end
+end
+```
+That way you won't have all metrics labeled with `controller=other` and `action=other`, but have labels such as
+```
+ruby_http_duration_seconds{path="/api/v1/teams/:id",method="GET",status="200",quantile="0.99"} 0.009880661998977303
+```
+
+¹) Only available when Redis is used.
+²) Only available when Mysql or PostgreSQL are used.
+³) Only available when [Instrumenting Request Queueing Time](#instrumenting-request-queueing-time) is set up.
 
 #### Activerecord Connection Pool Metrics
 
@@ -365,19 +408,19 @@ Sometimes the Sidekiq server shuts down before it can send metrics, that were ge
 **PrometheusExporter::Instrumentation::Sidekiq**
 | Type    | Name                           | Description                                                                  |
 | ---     | ---                            | ---                                                                          |
-| Counter | `sidekiq_job_duration_seconds` | Total time spent in sidekiq jobs                                             |
+| Summary | `sidekiq_job_duration_seconds` | Time spent in sidekiq jobs                                                   |
 | Counter | `sidekiq_jobs_total`           | Total number of sidekiq jobs executed                                        |
 | Counter | `sidekiq_restarted_jobs_total` | Total number of sidekiq jobs that we restarted because of a sidekiq shutdown |
 | Counter | `sidekiq_failed_jobs_total`    | Total number of failed sidekiq jobs                                          |
 
-All metrics have a `job_name` label.
+All metrics have a `job_name` label and a `queue` label.
 
 **PrometheusExporter::Instrumentation::Sidekiq.death_handler**
 | Type    | Name                      | Description                       |
 | ---     | ---                       | ---                               |
 | Counter | `sidekiq_dead_jobs_total` | Total number of dead sidekiq jobs |
 
-This metric also has a `job_name` label.
+This metric has a `job_name` label and a `queue` label.
 
 **PrometheusExporter::Instrumentation::SidekiqQueue**
 | Type  | Name                            | Description                  |
@@ -387,7 +430,7 @@ This metric also has a `job_name` label.
 
 Both metrics will have a `queue` label with the name of the queue.
 
-_See [Metrics collected by Process Instrumentation](#metrics-collected-by-process-instrumentation) for a list of metrics the Process instrumentation will produce._  
+_See [Metrics collected by Process Instrumentation](#metrics-collected-by-process-instrumentation) for a list of metrics the Process instrumentation will produce._
 
 #### Shoryuken metrics
 
@@ -411,7 +454,7 @@ end
 | Counter | `shoryuken_restarted_jobs_total` | Total number of shoryuken jobs that we restarted because of a shoryuken shutdown |
 | Counter | `shoryuken_failed_jobs_total`    | Total number of failed shoryuken jobs                                            |
 
-All metrics have labels for `job_name` and `queue_name`.  
+All metrics have labels for `job_name` and `queue_name`.
 
 #### Delayed Job plugin
 
@@ -437,6 +480,8 @@ end
 | Summary | `delayed_job_duration_seconds_summary`    | Summary of the time it takes jobs to execute                       | `status`   |
 | Summary | `delayed_job_attempts_summary`            | Summary of the amount of attempts it takes delayed jobs to succeed | -          |
 
+All metrics have labels for `job_name` and `queue_name`.
+
 #### Hutch Message Processing Tracer
 
 Capture [Hutch](https://github.com/gocardless/hutch) metrics (how many jobs ran? how many failed? how long did they take?)
@@ -456,7 +501,7 @@ end
 | Counter | `hutch_jobs_total`           | Total number of hutch jobs executed     |
 | Counter | `hutch_failed_jobs_total`    | Total number failed hutch jobs executed |
 
-All metrics have a `job_name` label. 
+All metrics have a `job_name` label.
 
 #### Instrumenting Request Queueing Time
 
@@ -464,7 +509,7 @@ Request Queueing is defined as the time it takes for a request to reach your app
 
 As this metric starts before `prometheus_exporter` can handle the request, you must add a specific HTTP header as early in your infrastructure as possible (we recommend your load balancer or reverse proxy).
 
-Configure your HTTP server / load balancer to add a header `X-Request-Start: t=<MSEC>` when passing the request upstream. For more information, please consult your software manual.
+The Amazon Application Load Balancer [request tracing header](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-request-tracing.html) is natively supported. If you are using another upstream entrypoint, you may configure your HTTP server / load balancer to add a header `X-Request-Start: t=<MSEC>` when passing the request upstream. For more information, please consult your software manual.
 
 Hint: we aim to be API-compatible with the big APM solutions, so if you've got requests queueing time configured for them, it should be expected to also work with `prometheus_exporter`.
 
@@ -494,7 +539,29 @@ end
 | Gauge | `puma_thread_pool_capacity_total` | Number of puma threads available at current scale           |
 | Gauge | `puma_max_threads_total`          | Number of puma threads at available at max scale            |
 
-All metrics may have a `phase` label.   
+All metrics may have a `phase` label and all custom labels provided with the `labels` option.
+
+### Resque metrics
+
+The resque metrics are using the `Resque.info` method, which queries Redis internally. To start monitoring your resque
+installation, you'll need to start the instrumentation:
+
+```ruby
+# e.g. config/initializers/resque.rb
+require 'prometheus_exporter/instrumentation'
+PrometheusExporter::Instrumentation::Resque.start
+```
+
+#### Metrics collected by Resque Instrumentation
+
+| Type  | Name                   | Description                            |
+| ---   | ---                    | ---                                    |
+| Gauge | `processed_jobs_total` | Total number of processed Resque jobs  |
+| Gauge | `failed_jobs_total`    | Total number of failed Resque jobs     |
+| Gauge | `pending_jobs_total`   | Total number of pending Resque jobs    |
+| Gauge | `queues_total`         | Total number of Resque queues          |
+| Gauge | `workers_total`        | Total number of Resque workers running |
+| Gauge | `working_total`        | Total number of Resque workers working |
 
 ### Unicorn process metrics
 
@@ -577,8 +644,8 @@ Then you can collect the metrics you need on demand:
 
 ```ruby
 def metrics
-  user_count_gague = PrometheusExporter::Metric::Gauge.new('user_count', 'number of users in the app')
-  user_count_gague.observe User.count
+  user_count_gauge = PrometheusExporter::Metric::Gauge.new('user_count', 'number of users in the app')
+  user_count_gauge.observe User.count
   [user_count_gauge]
 end
 ```
@@ -692,6 +759,25 @@ ruby_web_requests{hostname="app-server-01"} 1
 When running the process for `prometheus_exporter` using `bin/prometheus_exporter`, there are several configurations that
 can be passed in:
 
+```
+Usage: prometheus_exporter [options]
+    -p, --port INTEGER               Port exporter should listen on (default: 9394)
+    -b, --bind STRING                IP address exporter should listen on (default: localhost)
+    -t, --timeout INTEGER            Timeout in seconds for metrics endpoint (default: 2)
+        --prefix METRIC_PREFIX       Prefix to apply to all metrics (default: ruby_)
+        --label METRIC_LABEL         Label to apply to all metrics (default: {})
+    -c, --collector FILE             (optional) Custom collector to run
+    -a, --type-collector FILE        (optional) Custom type collectors to run in main collector
+    -v, --verbose
+        --auth FILE                  (optional) enable basic authentication using a htpasswd FILE
+        --realm REALM                (optional) Use REALM for basic authentication (default: "Prometheus Exporter")
+        --unicorn-listen-address ADDRESS
+                                     (optional) Address where unicorn listens on (unix or TCP address)
+        --unicorn-master PID_FILE    (optional) PID file of unicorn master process to monitor unicorn
+```
+
+#### Example
+
 The following will run the process at
 - Port `8080` (default `9394`)
 - Bind to `0.0.0.0` (default `localhost`)
@@ -707,6 +793,29 @@ prometheus_exporter -p 8080 \
                     --prefix 'foo_'
 ```
 
+#### Enabling Basic Authentication
+
+If you desire authentication on your `/metrics` route, you can enable basic authentication with the `--auth` option.
+
+```
+$ prometheus_exporter --auth my-htpasswd-file
+```
+
+Additionally, the `--realm` option may be used to provide a customized realm for the challenge request.
+
+Notes:
+
+* You will need to create a `htpasswd` formatted file before hand which contains one or more user:password entries
+* Only the basic `crypt` encryption is currently supported
+
+A simple `htpasswd` file can be created with the Apache `htpasswd` utility; e.g:
+
+```
+$ htpasswd -cdb my-htpasswd-file my-user my-unencrypted-password
+```
+
+This will create a file named `my-htpasswd-file` which is suitable for use the `--auth` option.
+
 ### Client default labels
 
 You can specify a default label for instrumentation metrics sent by a specific client. For example:
@@ -742,6 +851,19 @@ The `PrometheusExporter::Client` class has the method `#send-json`. This method,
 
 When `PrometheusExporter::Server::Collector` parses your JSON, by default it will use the faster Oj deserializer if available. This happens cause it only expects a simple Hash out of the box. You can opt in for the default JSON deserializer with `json_serializer: :json`.
 
+## Logging
+
+`PrometheusExporter::Client.default` will export to `STDERR`. To change this, you can pass your own logger:
+```ruby
+PrometheusExporter::Client.new(logger: Rails.logger)
+PrometheusExporter::Client.new(logger: Logger.new(STDOUT))
+```
+
+You can also pass a log level (default is [`Logger::WARN`](https://ruby-doc.org/stdlib-3.0.1/libdoc/logger/rdoc/Logger.html)):
+```ruby
+PrometheusExporter::Client.new(log_level: Logger::DEBUG)
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/discourse/prometheus_exporter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/bin/prometheus_exporter

@@ -3,12 +3,15 @@
 
 require 'optparse'
 require 'json'
+require 'logger'
 
 require_relative "./../lib/prometheus_exporter"
 require_relative "./../lib/prometheus_exporter/server"
 
 def run
-  options = {}
+  options = {
+    logger_path: STDERR
+  }
   custom_collector_filename = nil
   custom_type_collectors_filenames = []
 
@@ -47,6 +50,12 @@ def run
     opt.on('-v', '--verbose') do |o|
       options[:verbose] = true
     end
+    opt.on('--auth FILE', String, "(optional) enable basic authentication using a htpasswd FILE") do |o|
+      options[:auth] = o
+    end
+    opt.on('--realm REALM', String, "(optional) Use REALM for basic authentication (default: \"#{PrometheusExporter::DEFAULT_REALM}\")") do |o|
+      options[:realm] = o
+    end
 
     opt.on('--unicorn-listen-address ADDRESS', String, '(optional) Address where unicorn listens on (unix or TCP address)') do |o|
       options[:unicorn_listen_address] = o
@@ -55,8 +64,26 @@ def run
     opt.on('--unicorn-master PID_FILE', String, '(optional) PID file of unicorn master process to monitor unicorn') do |o|
       options[:unicorn_pid_file] = o
     end
+
+    opt.on('--logger-path PATH', String, '(optional) Path to file for logger output. Defaults to STDERR') do |o|
+      options[:logger_path] = o
+    end
   end.parse!
 
+  logger = Logger.new(options[:logger_path])
+  logger.level = Logger::WARN
+
+  if options.has_key?(:realm) && !options.has_key?(:auth)
+    logger.warn "Providing REALM without AUTH has no effect"
+  end
+
+  if options.has_key?(:auth)
+    unless File.exist?(options[:auth]) && File.readable?(options[:auth])
+      logger.fatal "The AUTH file either doesn't exist or we don't have access to it"
+      exit 1
+    end
+  end
+
   if custom_collector_filename
     eval File.read(custom_collector_filename), nil, File.expand_path(custom_collector_filename)
     found = false
@@ -71,7 +98,7 @@ def run
     end
 
     if !found
-      STDERR.puts "[Error] Can not find a class inheriting off PrometheusExporter::Server::CollectorBase"
+      logger.fatal "Can not find a class inheriting off PrometheusExporter::Server::CollectorBase"
       exit 1
     end
   end

data/gemfiles/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_RETRY: "1"