prometheus_exporter 0.8.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 562647915cd81e672056a83fc79a031d2a0ebb2b4a7a5e32f5786ae5c7d480a7
-  data.tar.gz: 525e28d0cbe4e853c91bb463970fd231b134dba6b5a190c61a2ff7710074fb7b
+  metadata.gz: f5e708b8c63be6ecff9750deebf18cad149d9b4fa7350a4523af2f145caffec5
+  data.tar.gz: 1204a53af367dc60e24ded2e1630e2b447ef79d3caff32165ac5c40b62955ded
 SHA512:
-  metadata.gz: 324b3b0acd1c97e8b5535dff8f57500b4dc3f2433456372c609accbc78d1baf839d82a1e38eabb543f043bbc9fefb401ab1460ba252ee8b9330fe0a91acffc1d
-  data.tar.gz: b2a0082d4e2431cc1f24f11a6af86d6965e2db7c93df1021ed58b38ff8651c84d1e8939b42a13b1b7cac60c9237435ff838a24918ed0ee18d13c3df2aece76d4
+  metadata.gz: 5dee50712e73be92702e2948a0a69aa8b8007df59de35f10c5980d9d5a2653092a4247e7ad207713460df80f59bb0691835a3aa2b04fa751d28cc5b9c3f66f48
+  data.tar.gz: 0af7415fd207b1eb5f7f62639f8d48bc7735df9397537524c536631d24150b9b7daa87d17652f070a79f8134d50e780c9143ddeedcfc2d44eaa27586ffe64b19

data/.github/workflows/ci.yml

@@ -1,42 +1,53 @@
-name: Test Exporter
+name: CI
 
 on:
   push:
+    branches:
+      - main
   pull_request:
   schedule:
-    - cron: '0 0 * * 0' # weekly
+    - cron: "0 0 * * 0" # weekly
 
 jobs:
   build:
     runs-on: ubuntu-latest
-    name: Ruby ${{ matrix.ruby }}
+    name: Ruby ${{ matrix.ruby }} AR ${{ matrix.activerecord }}
+    timeout-minutes: 10
+
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/ar_${{ matrix.activerecord }}.gemfile
+
     strategy:
+      fail-fast: false
       matrix:
-        ruby: ["2.7", "2.6", "2.5"]
+        ruby: ['2.6', '2.7', '3.0', '3.1']
+        activerecord: [60, 61]
+
     steps:
-      - uses: actions/checkout@master
-        with:
-          fetch-depth: 1
-      - uses: actions/setup-ruby@v1
+      - uses: actions/checkout@v2
+
+      - uses: ruby/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
+          bundler-cache: true
+
       - name: Rubocop
         run: bundle exec rubocop
-      - name: install gems
-        run: bundle exec appraisal bundle
+
       - name: Run tests
-        run: bundle exec appraisal rake
+        run: bundle exec rake
+
+  publish:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Release gem
+        uses: discourse/publish-rubygems-action@v2
+        env:
+          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+          GIT_EMAIL: team@discourse.org
+          GIT_NAME: discoursebot

data/CHANGELOG

@@ -1,16 +1,41 @@
-0.8.0 - 05-07-2021
+2.0.0 - 2022-02-18
+
+- FEATURE: Add per worker custom labels 
+- FEATURE: support custom histogram buckets
+- FIX: all metrics are exposing status label, and not only `http_requests_total`
+- BREAKING: rename all `http_duration` metrics to `http_request_duration` to match prometheus official naming conventions (See https://prometheus.io/docs/practices/naming/#metric-names).
+
+1.0.1 - 2021-12-22
+
+- FEATURE: add labels to preflight requests
+- FEATURE: SidekiqStats metrics
+- FIX: mintor refactors to Sidekiq metrics
+
+1.0.0 - 2021-11-23
+
+- BREAKING: rename metrics to match prometheus official naming conventions (See https://prometheus.io/docs/practices/naming/#metric-names)
+- FEATURE: Sidekiq process metrics
+- FEATURE: Allow collecting web metrics as histograms
+- FIX: logger improved for web server
+- FIX: Remove job labels from DelayedJob queues
+
+0.8.1 - 2021-08-04
+
+- FEATURE: swap from hardcoded STDERR to logger pattern (see README for details)
+
+0.8.0 - 2021-07-05
 
 - 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 Rescue
+- 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
+0.7.0 - 2020-12-29
 
 - 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
@@ -18,111 +43,111 @@
 - FEATURE: clean pattern for overriding middleware labels was introduced (in README)
 - Fix: Better support for forking
 
-0.6.0 - 17-11-2020
+0.6.0 - 2020-11-17
 
 - FEATURE: add support for basic-auth in the prometheus_exporter web server
 
-0.5.3 - 29-07-2020
+0.5.3 - 2020-07-29
 
 - FEATURE: added #remove to all metric types so users can remove specific labels if needed
 
-0.5.2 - 01-07-2020
+0.5.2 - 2020-07-01
 
 - FEATURE: expanded instrumentation for sidekiq
 - FEATURE: configurable default labels
 
-0.5.1 - 25-02-2020
+0.5.1 - 2020-02-25
 
 - FEATURE: Allow configuring the default client's host and port via environment variables
 
-0.5.0 - 14-02-2020
+0.5.0 - 2020-02-14
 
 - Breaking change: listen only to localhost by default to prevent unintended insecure configuration
 - FIX: Avoid calling `hostname` aggressively, instead cache it on the exporter instance
 
-0.4.17 - 13-01-2020
+0.4.17 - 2020-01-13
 
 - FEATURE: add support for `to_h` on all metrics which can be used to query existing key/values
 
-0.4.16 - 04-11-2019
+0.4.16 - 2019-11-04
 
 - FEATURE: Support #reset! on all metric types to reset a metric to default
 
-0.4.15 - 04-11-2019
+0.4.15 - 2019-11-04
 
 - FEATURE: Improve delayed job collector, add pending counts
 - FEATURE: New ActiveRecord collector (documented in readme)
 - FEATURE: Allow passing in histogram and summary options
 - FEATURE: Allow custom labels for unicorn collector
 
-0.4.14 - 10-09-2019
+0.4.14 - 2019-09-10
 
 - FEATURE: allow finding metrics by name RemoteMetric #find_registered_metric
 - FIX: guard socket closing
 
-0.4.13 - 09-07-2019
+0.4.13 - 2019-07-09
 
 - Fix: Memory leak in unicorn and puma collectors
 
-0.4.12 - 30-05-2019
+0.4.12 - 2019-05-30
 
 - Fix: unicorn collector reporting incorrect number of unicorn workers
 
-0.4.11 - 15-05-2019
+0.4.11 - 2019-05-15
 
 - Fix: Handle stopping nil worker_threads in Client
 - Dev: add frozen string literals
 
-0.4.10 - 29-04-2019
+0.4.10 - 2019-04-29
 
 - Fix: Custom label support for puma collector
 - Fix: Raindrops socket collector not working correctly
 
-0.4.9 - 11-04-2019
+0.4.9 - 2019-04-11
 
 - Fix: Gem was not working correctly in Ruby 2.4 and below due to a syntax error
 
-0.4.8 - 10-04-2019
+0.4.8 - 2019-04-10
 
 - Feature: added helpers for instrumenting unicorn using raindrops
 
-0.4.7 - 08-04-2019
+0.4.7 - 2019-04-08
 
 - Fix: collector was not escaping " \ and \n correctly. This could lead
   to a corrupt payload in some cases.
 
-0.4.6 - 02-04-2019
+0.4.6 - 2019-04-02
 
 - Feature: Allow resetting a counter
 - Feature: Add sidekiq metrics: restarted, dead jobs counters
 - Fix: Client shutting down before sending metrics to collector
 
-0.4.5 - 14-02-2019
+0.4.5 - 2019-02-14
 
 - Feature: Allow process collector to ship custom labels for all process metrics
 - Fix: Always scope process metrics on hostname in collector
 
-0.4.4 - 13-02-2019
+0.4.4 - 2019-02-13
 
 - Feature: add support for local metric collection without using HTTP
 
-0.4.3 - 11-02-2019
+0.4.3 - 2019-02-11
 
 - Feature: Add alias for Gauge #observe called #set, this makes it a bit easier to migrate from prom
 - Feature: Add increment and decrement to Counter
 
-0.4.2 - 30-11-2018
+0.4.2 - 2018-11-30
 
 - Fix/Feature: setting a Gauge to nil will remove Gauge (setting to non numeric will raise)
 
-0.4.0 - 23-10-2018
+0.4.0 - 2018-10-23
 
 - Feature: histogram support
 - Feature: custom quantile support for summary
 - Feature: Puma metrics
 - Fix: delayed job metrics
 
-0.3.4 - 02-10-2018
+0.3.4 - 2018-10-02
 
 - Fix: custom collector via CLI was not working correctly
 

data/README.md

@@ -5,6 +5,7 @@ Prometheus Exporter allows you to aggregate custom metrics from multiple process
 To learn more see [Instrumenting Rails with Prometheus](https://samsaffron.com/archive/2018/02/02/instrumenting-rails-with-prometheus) (it has pretty pictures!)
 
 * [Requirements](#requirements)
+* [Migrating from v0.x](#migrating-from-v0.x)
 * [Installation](#installation)
 * [Usage](#usage)
   * [Single process mode](#single-process-mode)
@@ -26,15 +27,24 @@ To learn more see [Instrumenting Rails with Prometheus](https://samsaffron.com/a
   * [Metrics default prefix / labels](#metrics-default-prefix--labels)
   * [Client default labels](#client-default-labels)
   * [Client default host](#client-default-host)
+  * [Histogram mode](#histogram-mode)
+  * [Histogram - custom buckets](#histogram-custom-buckets)
 * [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.5.0 is required, Ruby 2.4.0 is EOL as of 2020-04-05
+Minimum Ruby of version 2.6.0 is required, Ruby 2.5.0 is EOL as of March 31st 2021.
+
+## Migrating from v0.x
+
+There are some major changes in v1.x from v0.x.
+
+- Some of metrics are renamed to match [prometheus official guide for metric names](https://prometheus.io/docs/practices/naming/#metric-names). (#184)
 
 ## Installation
 
@@ -193,13 +203,13 @@ $ bundle exec prometheus_exporter
 
 #### Metrics collected by Rails integration middleware
 
-| Type    | Name                            | Description                                                 |
-| ---     | ---                             | ---                                                         |
-| Counter | `http_requests_total`           | Total HTTP requests from web app                            |
-| Summary | `http_duration_seconds`         | Time spent in HTTP reqs in seconds                          |
-| Summary | `http_redis_duration_seconds`¹  | Time spent in HTTP reqs in Redis, in seconds                |
-| 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 |
+| Type    | Name                                   | Description                                                 |
+| ---     | ---                                    | ---                                                         |
+| Counter | `http_requests_total`                  | Total HTTP requests from web app                            |
+| Summary | `http_request_duration_seconds`        | Time spent in HTTP reqs in seconds                          |
+| Summary | `http_request_redis_duration_seconds`¹ | Time spent in HTTP reqs in Redis, in seconds                |
+| Summary | `http_request_sql_duration_seconds`²   | Time spent in HTTP reqs in SQL in seconds                   |
+| Summary | `http_request_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.
@@ -242,7 +252,7 @@ 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
+ruby_http_request_duration_seconds{path="/api/v1/teams/:id",method="GET",status="200",quantile="0.99"} 0.009880661998977303
 ```
 
 ¹) Only available when Redis is used.
@@ -358,40 +368,49 @@ Metrics collected by Process instrumentation include labels `type` (as given wit
 
 #### Sidekiq metrics
 
-Including Sidekiq metrics (how many jobs ran? how many failed? how long did they take? how many are dead? how many were restarted?)
-
-```ruby
-Sidekiq.configure_server do |config|
-   config.server_middleware do |chain|
-      require 'prometheus_exporter/instrumentation'
-      chain.add PrometheusExporter::Instrumentation::Sidekiq
-   end
-   config.death_handlers << PrometheusExporter::Instrumentation::Sidekiq.death_handler
-end
-```
-
-To monitor Queue size and latency:
+There are different kinds of Sidekiq metrics that can be collected. A recommended setup looks like this:
 
 ```ruby
 Sidekiq.configure_server do |config|
+  require 'prometheus_exporter/instrumentation'
+  config.server_middleware do |chain|
+    chain.add PrometheusExporter::Instrumentation::Sidekiq
+  end
+  config.death_handlers << PrometheusExporter::Instrumentation::Sidekiq.death_handler
   config.on :startup do
-    require 'prometheus_exporter/instrumentation'
+    PrometheusExporter::Instrumentation::Process.start type: 'sidekiq'
+    PrometheusExporter::Instrumentation::SidekiqProcess.start
     PrometheusExporter::Instrumentation::SidekiqQueue.start
+    PrometheusExporter::Instrumentation::SidekiqStats.start
   end
 end
 ```
 
-To monitor Sidekiq process info:
+* The middleware and death handler will generate job specific metrics (how many jobs ran? how many failed? how long did they take? how many are dead? how many were restarted?).
+* The [`Process`](#per-process-stats) metrics provide basic ruby metrics.
+* The `SidekiqProcess` metrics provide the concurrency and busy metrics for this process.
+* The `SidekiqQueue` metrics provides size and latency for the queues run by this process.
+* The `SidekiqStats` metrics provide general, global Sidekiq stats (size of Scheduled, Retries, Dead queues, total number of jobs, etc).
+
+For `SidekiqQueue`, if you run more than one process for the same queues, note that the same metrics will be exposed by all the processes, just like the `SidekiqStats` will if you run more than one process of any kind. You might want use `avg` or `max` when consuming their metrics.
+
+An alternative would be to expose these metrics in lone, long-lived process. Using a rake task, for example:
 
 ```ruby
-Sidekiq.configure_server do |config|
-  config.on :startup do
-    require 'prometheus_exporter/instrumentation'
-    PrometheusExporter::Instrumentation::Process.start type: 'sidekiq'
-  end
+task :sidekiq_metrics do
+  server = PrometheusExporter::Server::WebServer.new
+  server.start
+
+  PrometheusExporter::Client.default = PrometheusExporter::LocalClient.new(collector: server.collector)
+
+  PrometheusExporter::Instrumentation::SidekiqQueue.start(all_queues: true)
+  PrometheusExporter::Instrumentation::SidekiqStats.start
+  sleep
 end
 ```
 
+The `all_queues` parameter for `SidekiqQueue` will expose metrics for all queues.
+
 Sometimes the Sidekiq server shuts down before it can send metrics, that were generated right before the shutdown, to the collector. Especially if you care about the `sidekiq_restarted_jobs_total` metric, it is a good idea to explicitly stop the client:
 
 ```ruby
@@ -402,6 +421,18 @@ Sometimes the Sidekiq server shuts down before it can send metrics, that were ge
   end
 ```
 
+Custom labels can be added for individual jobs by defining a class method on the job class. These labels will be added to all Sidekiq metrics written by the job:
+
+```ruby
+  class WorkerWithCustomLabels
+    def self.custom_labels
+      { my_label: 'value-here', other_label: 'second-val' }
+    end
+
+    def perform; end
+  end
+```
+
 ##### Metrics collected by Sidekiq Instrumentation
 
 **PrometheusExporter::Instrumentation::Sidekiq**
@@ -424,11 +455,33 @@ This metric has a `job_name` label and a `queue` label.
 **PrometheusExporter::Instrumentation::SidekiqQueue**
 | Type  | Name                            | Description                  |
 | ---   | ---                             | ---                          |
-| Gauge | `sidekiq_queue_backlog_total`   | Size of the sidekiq queue    |
+| Gauge | `sidekiq_queue_backlog`         | Size of the sidekiq queue    |
 | Gauge | `sidekiq_queue_latency_seconds` | Latency of the sidekiq queue |
 
 Both metrics will have a `queue` label with the name of the queue.
 
+**PrometheusExporter::Instrumentation::SidekiqProcess**
+| Type  | Name                          | Description                             |
+| ---   | ---                           | ---                                     |
+| Gauge | `sidekiq_process_busy`        | Number of busy workers for this process |
+| Gauge | `sidekiq_process_concurrency` | Concurrency for this process            |
+
+Both metrics will include the labels `labels`, `queues`, `quiet`, `tag`, `hostname` and `identity`, as returned by the [Sidekiq Processes API](https://github.com/mperham/sidekiq/wiki/API#processes).
+
+**PrometheusExporter::Instrumentation::SidekiqStats**
+| Type  | Name                            | Description                             |
+| ---   | ---                             | ---                                     |
+| Gauge | `sidekiq_stats_dead_size`       | Size of the dead queue                  |
+| Gauge | `sidekiq_stats_enqueued`        | Number of enqueued jobs                 |
+| Gauge | `sidekiq_stats_failed`          | Number of failed jobs                   |
+| Gauge | `sidekiq_stats_processed`       | Total number of processed jobs          |
+| Gauge | `sidekiq_stats_processes_size`  | Number of processes                     |
+| Gauge | `sidekiq_stats_retry_size`      | Size of the retries queue               |
+| Gauge | `sidekiq_stats_scheduled_size`  | Size of the scheduled queue             |
+| Gauge | `sidekiq_stats_workers_size`    | Number of jobs actively being processed |
+
+Based on the [Sidekiq Stats API](https://github.com/mperham/sidekiq/wiki/API#stats).
+
 _See [Metrics collected by Process Instrumentation](#metrics-collected-by-process-instrumentation) for a list of metrics the Process instrumentation will produce._
 
 #### Shoryuken metrics
@@ -528,15 +581,15 @@ end
 
 #### Metrics collected by Puma Instrumentation
 
-| Type  | Name                              | Description                                                 |
-| ---   | ---                               | ---                                                         |
-| Gauge | `puma_workers_total`              | Number of puma workers                                      |
-| Gauge | `puma_booted_workers_total`       | Number of puma workers booted                               |
-| Gauge | `puma_old_workers_total`          | Number of old puma workers                                  |
-| Gauge | `puma_running_threads_total`      | Number of puma threads currently running                    |
-| Gauge | `puma_request_backlog_total`      | Number of requests waiting to be processed by a puma thread |
-| 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            |
+| Type  | Name                        | Description                                                 |
+| ---   | ---                         | ---                                                         |
+| Gauge | `puma_workers`              | Number of puma workers                                      |
+| Gauge | `puma_booted_workers`       | Number of puma workers booted                               |
+| Gauge | `puma_old_workers`          | Number of old puma workers                                  |
+| Gauge | `puma_running_threads`      | Number of puma threads currently running                    |
+| Gauge | `puma_request_backlog`      | Number of requests waiting to be processed by a puma thread |
+| Gauge | `puma_thread_pool_capacity` | Number of puma threads available at current scale           |
+| Gauge | `puma_max_threads`          | Number of puma threads at available at max scale            |
 
 All metrics may have a `phase` label and all custom labels provided with the `labels` option.
 
@@ -553,14 +606,14 @@ 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 |
+| Type  | Name                    | Description                            |
+| ---   | ---                     | ---                                    |
+| Gauge | `resque_processed_jobs` | Total number of processed Resque jobs  |
+| Gauge | `resque_failed_jobs`    | Total number of failed Resque jobs     |
+| Gauge | `resque_pending_jobs`   | Total number of pending Resque jobs    |
+| Gauge | `resque_queues`         | Total number of Resque queues          |
+| Gauge | `resque_workers`        | Total number of Resque workers running |
+| Gauge | `resque_working`        | Total number of Resque workers working |
 
 ### Unicorn process metrics
 
@@ -579,11 +632,11 @@ Note: You must install the `raindrops` gem in your `Gemfile` or locally.
 
 #### Metrics collected by Unicorn Instrumentation
 
-| Type  | Name                            | Description                                                    |
-| ---   | ---                             | ---                                                            |
-| Gauge | `unicorn_workers_total`         | Number of unicorn workers                                      |
-| Gauge | `unicorn_active_workers_total`  | Number of active unicorn workers                               |
-| Gauge | `unicorn_request_backlog_total` | Number of requests waiting to be processed by a unicorn worker |
+| Type  | Name                      | Description                                                    |
+| ---   | ---                       | ---                                                            |
+| Gauge | `unicorn_workers`         | Number of unicorn workers                                      |
+| Gauge | `unicorn_active_workers`  | Number of active unicorn workers                               |
+| Gauge | `unicorn_request_backlog` | Number of requests waiting to be processed by a unicorn worker |
 
 ### Custom type collectors
 
@@ -768,6 +821,7 @@ Usage: prometheus_exporter [options]
     -c, --collector FILE             (optional) Custom collector to run
     -a, --type-collector FILE        (optional) Custom type collectors to run in main collector
     -v, --verbose
+    -g, --histogram                  Use histogram instead of summary for aggregations
         --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
@@ -838,6 +892,38 @@ http_requests_total{service="app-server-01",app_name="app-01"} 1
 
 By default, `PrometheusExporter::Client.default` connects to `localhost:9394`. If your setup requires this (e.g. when using `docker-compose`), you can change the default host and port by setting the environment variables `PROMETHEUS_EXPORTER_HOST` and `PROMETHEUS_EXPORTER_PORT`.
 
+### Histogram mode
+
+By default, the built-in collectors will report aggregations as summaries. If you need to aggregate metrics across labels, you can switch from summaries to histograms:
+
+```
+$ prometheus_exporter --histogram
+```
+
+In histogram mode, the same metrics will be collected but will be reported as histograms rather than summaries. This sacrifices some precision but allows aggregating metrics across actions and nodes using [`histogram_quantile`].
+
+[`histogram_quantile`]: https://prometheus.io/docs/prometheus/latest/querying/functions/#histogram_quantile
+
+### Histogram - custom buckets
+
+By default these buckets will be used:
+```
+[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5.0, 10.0].freeze
+```
+if this is not enough you can specify `default_buckets` like this:
+```
+Histogram.default_buckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 2.5, 3, 4, 5.0, 10.0, 12, 14, 15, 20, 25].freeze
+```
+
+Specfied buckets on the instance  takes precedence over default:
+
+```
+Histogram.default_buckets = [0.005, 0.01, 0,5].freeze
+buckets = [0.1, 0.2, 0.3]
+histogram = Histogram.new('test_bucktets', 'I have specified buckets', buckets: buckets)
+histogram.buckets => [0.1, 0.2, 0.3]
+```
+
 ## Transport concerns
 
 Prometheus Exporter handles transport using a simple HTTP protocol. In multi process mode we avoid needing a large number of HTTP request by using chunked encoding to send metrics. This means that a single HTTP channel can deliver 100s or even 1000s of metrics over a single HTTP session to the `/send-metrics` endpoint. All calls to `send` and `send_json` on the `PrometheusExporter::Client` class are **non-blocking** and batched.
@@ -850,6 +936,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,9 @@ def run
     opt.on('-v', '--verbose') do |o|
       options[:verbose] = true
     end
+    opt.on('-g', '--histogram', "Use histogram instead of summary for aggregations") do |o|
+      options[:histogram] = true
+    end
     opt.on('--auth FILE', String, "(optional) enable basic authentication using a htpasswd FILE") do |o|
       options[:auth] = o
     end
@@ -61,21 +67,28 @@ 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)
-    STDERR.puts "[Warn] Providing REALM without AUTH has no effect"
+    logger.warn "Providing REALM without AUTH has no effect"
   end
 
   if options.has_key?(:auth)
     unless File.exist?(options[:auth]) && File.readable?(options[:auth])
-      STDERR.puts "[Error] The AUTH file either doesn't exist or we don't have access to it"
+      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)
+    require File.expand_path(custom_collector_filename)
     found = false
 
     base_klass = PrometheusExporter::Server::CollectorBase
@@ -88,14 +101,14 @@ 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
 
   if custom_type_collectors_filenames.length > 0
     custom_type_collectors_filenames.each do |t|
-      eval File.read(t), nil, File.expand_path(t)
+      require File.expand_path(t)
     end
 
     ObjectSpace.each_object(Class) do |klass|