diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a91e4a..d41560a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.1.0] + +Out of beta testing, reading for usage. Following is a recap from Alpha & Beta releases. + +### Added +- new metric: `sockets.backlog` (disabled by default), pulls information from Puma + sockets about the state of their backlogs. This together with `queue.backlog` + allows for full insights into total number of requests waiting to be processed +- `config.sockets_telemetry!` option to enable sockets telemetry +- `config.socket_parser` option to allow custom parser implementation as needed +- Datadog widgets examples under `docs/examples.md` + ## [1.1.0 Beta] ### Added diff --git a/Gemfile.lock b/Gemfile.lock index 9c94278..c1c9bf1 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ PATH remote: . specs: - puma-plugin-telemetry (1.1.0.beta) + puma-plugin-telemetry (1.1.0) puma (>= 5.0) GEM diff --git a/docs/example-datadog_backlog_size.png b/docs/example-datadog_backlog_size.png new file mode 100644 index 0000000..0572607 Binary files /dev/null and b/docs/example-datadog_backlog_size.png differ diff --git a/docs/example-datadog_queue_time.png b/docs/example-datadog_queue_time.png new file mode 100644 index 0000000..c80d888 Binary files /dev/null and b/docs/example-datadog_queue_time.png differ diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..9f03bef --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,163 @@ +## Keeping track of waiting requests + +There are requests waiting in 2 places: +- socket +- queue + +Their sum is a total number of accepted requests waiting. + +Puma configuration + +```ruby +plugin :telemetry + +Puma::Plugin::Telemetry.configure do |config| + config.enabled = true + config.initial_delay = 10 + + config.puma_telemetry = %w[queue.backlog] + + config.socket_telemetry! + + config.add_target :dogstatsd, client: Datadog::Statsd.new(tags: %w[your tags], namespace: "ruby.puma") +end +``` + +Example Datadog widget and it's configuration. Depending on what you prefer to see, you might replace `rollup(max)` with `rollup(sum)` whenever you want to see maximum value or sum across the aggregated time frame. + +| :point_up: | Remember to update tags after initial setup! | +|---------------|:---------------------------------------------| + +![Datadog Widget, barchart showcasing sockets & queue backlog sizes stacked up](example-datadog_backlog_size.png "Datadog Widget") + +```json +{ + "viz": "timeseries", + "requests": [ + { + "style": { + "palette": "dog_classic", + "type": "solid", + "width": "normal" + }, + "type": "bars", + "formulas": [ + { + "alias": "queue", + "formula": "query1" + }, + { + "alias": "socket", + "formula": "query2" + } + ], + "response_format": "timeseries", + "on_right_yaxis": false, + "queries": [ + { + "query": "max:ruby.puma.queue.backlog{}.rollup(max)", + "data_source": "metrics", + "name": "query1" + }, + { + "query": "max:ruby.puma.sockets.backlog{}.rollup(max)", + "data_source": "metrics", + "name": "query2" + } + ] + } + ], + "yaxis": { + "include_zero": true, + "max": "auto", + "scale": "linear", + "min": "auto", + "label": "" + }, + "markers": [] +} +``` + +## Keeping track of request queue time + +The time request spent waiting to be processed, between it's accepted by Load Balancer till it starts going through Rack Middleware in your application. Holy grail of autoscaling. + +Example configuration of middleware, i.e. in case of Rails it could be placed under `config/initializers/request_queue_time.rb` + +```ruby +Rails.application.config.middleware.insert_after( + 0, + RequestQueueTimeMiddleware, + statsd: Datadog::Statsd.new(namespace: "ruby.puma", tags: %w[your tags]) +) +``` + +If you are utilizing tags in your logs, you might also want to add this measurement as follows: + +```ruby +Rails.application.config.log_tags ||= {} +Rails.application.config.log_tags[:queue_time] = ->(req) { req.env[::RequestQueueTimeMiddleware::ENV_KEY] } +``` + +Example Datadog widget with configuration. + +| :point_up: | Remember to update tags after initial setup! | +|---------------|:---------------------------------------------| + +![Datadog Widget, barchart showcasing sockets & queue backlog sizes stacked up](example-datadog_queue_time.png "Datadog Widget") + +```json +{ + "viz": "timeseries", + "requests": [ + { + "style": { + "palette": "dog_classic", + "type": "solid", + "width": "normal" + }, + "type": "line", + "response_format": "timeseries", + "queries": [ + { + "query": "max:ruby.puma.queue.time.max{}", + "data_source": "metrics", + "name": "query1" + }, + { + "query": "max:ruby.puma.queue.time.95percentile{}", + "data_source": "metrics", + "name": "query2" + }, + { + "query": "max:ruby.puma.queue.time.median{}", + "data_source": "metrics", + "name": "query3" + } + ], + "formulas": [ + { + "alias": "max", + "formula": "query1" + }, + { + "alias": "p95", + "formula": "query2" + }, + { + "alias": "median", + "formula": "query3" + } + ] + } + ], + "yaxis": { + "include_zero": true, + "max": "auto", + "scale": "linear", + "min": "auto", + "label": "" + }, + "markers": [] +} +``` diff --git a/lib/puma/plugin/telemetry/version.rb b/lib/puma/plugin/telemetry/version.rb index 0d0ccf0..b1a614d 100644 --- a/lib/puma/plugin/telemetry/version.rb +++ b/lib/puma/plugin/telemetry/version.rb @@ -3,7 +3,7 @@ module Puma class Plugin module Telemetry - VERSION = "1.1.0.beta" + VERSION = "1.1.0" end end end