README.md in sidekiq_prometheus-0.8.1 vs README.md in sidekiq_prometheus-0.9.0
- old
+ new
@@ -1,14 +1,18 @@
-# SidekiqPrometheus
+# Sidekiq Prometheus
-Prometheus Instrumentation for Sidekiq.
-* Sidekiq server middleware for reporting job metrics
-* Global metrics reporter using the Sidekiq API for reporting Sidekiq cluster stats (requires Sidekiq::Enterprise)
-* Sidecar Rack server to provide scrape-able endpoint for Prometheus
+[](https://travis-ci.org/fastly/sidekiq-prometheus)
+
+[](http://opensource.org/licenses/MIT)
+Prometheus Instrumentation for Sidekiq. This gem provides:
+* Sidekiq server middleware for reporting job metrics
+* Global metrics reporter that uses the Sidekiq API for reporting Sidekiq cluster stats (*requires Sidekiq::Enterprise*)
+* Sidecar Rack server to provide scrape-able endpoint for Prometheus. This allows for metrics to be reported without having to run a separate prometheus exporter process.
+
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -29,51 +33,59 @@
```
SidekiqPrometheus.setup
```
-This will register metrics, start the global reporter (if available), and start the Rack server for scraping. The default port is 9357 but this is easily configurable.
+This will register metrics, start the global reporter (if available), and start the Rack server for scraping. The default port is 9359 but this is easily configurable.
-If you are running multiple services that will be reporting Sidekiq metrics you will want to take advantage of the `base_labels` configuration option. For example:
+Once Sidekiq server is running you can see your metrics or scrape them with Prometheus:
```
-SidekiqPrometheus.configure do |config|
- config.base_labels = { service: 'image_api' }
- config.metrics_port = 9090
-end
+$curl http://localhost:9359/metrics
-# always call setup after configure.
-SidekiqPrometheus.setup
+# TYPE sidekiq_job_count counter
+# HELP sidekiq_job_count Count of Sidekiq jobs
+# TYPE sidekiq_job_duration histogram
+# HELP sidekiq_job_duration Sidekiq job processing duration
+
+[etc]
```
-The call to `setup` is necessary as that it what registers the metrics and instruments Sidekiq.
-There is also a helper method: `SidekiqPrometheus.configure!` which can be used to configure and setup in one step:
+[Full documentation](https://www.rubydoc.info/gems/sidekiq_prometheus)
-```
-SidekiqPrometheus.configure! do |config|
- config.base_labels = { service: 'dogs_api' }
-end
+## Configuration
-# No need to call SidekiqPrometheus.setup because the bang method did it for us/
+You can configure the gem by calling `configure`:
+
+```ruby
+SidekiqPrometheus.configure do |config|
+ config.base_labels = { service: 'kubernandos_api' }
+end
```
-Once sidekiq server is running you can see your metrics or scrape them with Prometheus:
+`configure` will automatically call setup so
+If you are running multiple services that will be reporting Sidekiq metrics you will want to take advantage of the `base_labels` configuration option. For example:
+
+```ruby
+SidekiqPrometheus.configure do |config|
+ config.base_labels = { service: 'image_api' }
+ config.metrics_port = 9090
+end
```
-curl http://localhost:8675/metrics
-```
#### Configuration options
* `base_labels`: Hash of labels that will be included with every metric when they are registered.
* `gc_metrics_enabled`: Boolean that determines whether to record object allocation metrics per job. The default is `true`. Setting this to `false` if you don't need this metric.
* `global_metrics_enabled`: Boolean that determines whether to report global metrics from the PeriodicMetrics reporter. When `true` this will report on a number of stats from the Sidekiq API for the cluster. This requires Sidekiq::Enterprise as the reporter uses the leader election functionality to ensure that only one worker per cluster is reporting metrics.
-* `periodic_metrics_enabled`: Boolean that determines whether to run the periodic metrics reporter. `PeriodicMetrics` runs a separate thread that reports on global metrics (if enabled) as well worker GC stats (if enabled). It reports metrics on the interval defined by `periodic_reporting_interval`. Defatuls to `true`.
+* `periodic_metrics_enabled`: Boolean that determines whether to run the periodic metrics reporter. `PeriodicMetrics` runs a separate thread that reports on global metrics (if enabled) as well worker GC stats (if enabled). It reports metrics on the interval defined by `periodic_reporting_interval`. Defaults to `true`.
* `periodic_reporting_interval`: interval in seconds for reporting periodic metrics. Default: `30`
-* `metrics_port`: Port on which the rack server will listen. Defaults to `9357`
+* `metrics_port`: Port on which the rack server will listen. Defaults to `9359`
+* `registry`: An instance of `Prometheus::Client::Registry`. If you have a registry with defined metrics you can use this option to pass in your registry.
-```
+```ruby
SidekiqPrometheus.configure do |config|
config.base_labels = { service: 'myapp' }
config.gc_metrics_enabled = false
config.global_metrics_enabled = true
config.periodic_metrics_enabled = true
@@ -82,11 +94,11 @@
end
```
Custom labels may be added by defining the `prometheus_labels` method in the worker class:
-```
+```ruby
class SomeWorker
include Sidekiq::Worker
def prometheus_labels
{ some: 'label' }
@@ -131,11 +143,11 @@
### Periodic Global Metrics
These require `SidekiqPrometheus.global_metrics_enabled? == true` and `SidekiqPrometheus.periodic_metrics_enabled? == true`
-Periodic metric reporting relies onSidekiq Enterprise's leader election functionality ([Ent Leader Election ](https://github.com/mperham/sidekiq/wiki/Ent-Leader-Election))
+Periodic metric reporting relies on Sidekiq Enterprise's leader election functionality ([Ent Leader Election ](https://github.com/mperham/sidekiq/wiki/Ent-Leader-Election))
which ensures that metrics are only reported once per cluster.
| Metric | Type | Description |
|--------|------|-------------|
| sidekiq_workers_size | gauge | Total number of workers processing jobs |
@@ -152,19 +164,91 @@
| sidekiq_redis_keys | gauge | Number of redis keys |
| sidekiq_redis_expires | gauge | Number of redis keys with expiry set |
The global metrics are reported with the only the `base_labels` with the exception of `sidekiq_enqueued` which will add a `queue` label and record a metric per Sidekiq queue.
+## Custom Worker Metrics
+
+There are a few different ways to register custom metrics with SidekiqPrometheus. Each custom metric should be defined as a Hash with the following form:
+
+```ruby
+{
+ name: :metric_name,
+ type: :gauge,
+ docstring: 'description',
+ base_labels: { label_name: 'label_text' },
+}
+```
+
+* `:name` (required) - Unique name of the metric and should be a symbol.
+* `:type` (required) - Prometheus metric type. Supported values are: `:counter`, `:gauge`, `:histogram`, and `:summary`.
+* `:docstring` (required) - Human readable description of the metric.
+* `:base_labels` (optional) - Hash of labels that will be applied to every instance of this metric.
+
+#### Registering custom metrics:
+
+Registering a set of custom metrics is done by defining `custom_metrics` in the `configure` block:
+
+```ruby
+SidekiqPrometheus.configure do |config|
+ config.custom_metrics = [
+ { name: :imported_records, type: :counter, :docstring: 'Count of successfully imported records' },
+ { name: :failed_records, type: counter:, :docstring: 'Count of failed records' },
+ ]
+end
+```
+
+Metrics can also be registered directly. This must done *after* `SidekiqPrometheus.configure` or `setup` has been run.
+
+```ruby
+SidekiqPrometheus::Metrics.register(name: :logged_in_users, type: :gauge, docstring: 'Logged in users')
+```
+
+There is also a method to register more than one metric at a time:
+
+```ruby
+customer_worker_metrics = [
+ {
+ name: :file_count, type: :counter, docstring: 'Number of active files',
+ name: :file_size, type: :gauge, docstring: 'Size of files in bytes',
+ }
+]
+
+SidekiqPrometheus::Metrics.register_metrics(customer_worker_metrics)
+```
+
+#### Using custom metrics:
+
+Once metrics are registered they can be used in your Sidekiq workers.
+
+```ruby
+class ImportWorker
+ include Sidekiq::Worker
+
+ LABELS = {}
+
+ def perform(*args)
+ # worker code
+
+ SidekiqPrometheus[:file_count].increment(LABELS, new_file_count)
+ SidekiqPrometheus[:file_size].set(LABELS, total_file_size)
+ end
+
+end
+```
+
+See the [documentation of the Prometheus::Client library](https://github.com/prometheus/client_ruby) for all of the available options for setting metric values.
+
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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`.
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/fastly/sidekiq_prometheus. 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.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fastly/sidekiq-prometheus. 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.
## Copyright
Copyright 2019 Fastly, Inc.
@@ -172,6 +256,6 @@
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
-Everyone interacting in the SidekiqPrometheus project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sidekiq_prometheus/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the SidekiqPrometheus project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fastly/sidekiq-prometheus/blob/master/CODE_OF_CONDUCT.md).