Telemetry adapter for Hackney metrics.
This module is a metrics handler for the Hackney HTTP client. It receives calls from Hackney to update metrics and generates Telemetry events.
Hackney supports storing metrics in Folsom or Exometer. Unfortunately, these libraries do not export data in a way that is useful for Telemetry, so we need to transform the metrics data before reporting it.
The following metrics are exported by this library to telemetry.
Metric | Tags | Meaning |
---|---|---|
hackney.nb_requests |
- | Current number of requests |
hackney.finished_requests |
- | Total number of finished requests |
hackney.total_requests |
- | Total number of requests |
hackney_pool.free_count |
pool | Number of free sockets in a connection pool |
hackney_pool.in_use_count |
pool | Number of busy sockets in a connection pool |
hackney_pool.no_socket |
pool | Count of new connections |
hackney_pool.queue_count |
pool | Number of requests waiting for a connection in a pool |
hackney_pool.take_rate |
pool | Rate at which a connection is retrieved from the pool |
This module implements all the callbacks required by hackney_metrics
but it does
not support host metrics.
To use it, configure Hackney mod_metrics
to use this module and make sure
that the hackney_telemetry
application starts before your application.
Hackney calls the module specified by mod_metrics
to report instrumentation
metrics. This module receives the data from Hackney and passes it to a
hackney_telemetry_worker
which keeps the current state of the metric and
generates Telemetry events.
A worker process has two jobs:
-
Calculate metric values
Hackney does not keep the state of its metrics, but instead emits events to the metrics engine, like "increase this counter by 1", "set this gauge to X", "add Y to this histogram". The job of a metric worker is to process these events and keep up-to-date state representing the value of the tracked metric. State updates run in constant time (O(1)), important since a single request generates about nine metric updates.
-
Send metric values to Telemetry
If we send the metric value to Telemetry after every update, then telemetry processing may not be able to keep up, and Telemetry will apply backpressure.
Since the worker maintains the most up-to-date value, we can send the current value periodically. Gauge metrics may be less accurate, but it avoids overload.
Install it from Hex or Github.
Configure set Hackney to send metrics to this module:
Erlang
{hackney, [{mod_metrics, hackney_telemetry}]}
Elixir
config :hackney, mod_metrics: :hackney_telemetry
By default, workers will report data to telemetry every 1000 milliseconds. If set to 0, events are generated after every update.
You can change that by setting the report_interval
option:
Erlang
{hackney_telemetry, [{report_interval, 2000}]}
Elixir
config :hackney_telemetry, report_interval: 2_000
After installing the module, your application will receive Telemetry events. You can handle them in your application, or install a reporting module such as Telemetry.Metrics or prom_ex.
defmodule YourApplcation.Telemetry do
import Telemetry.Metrics
def metrics do
[
# other metrics
last_value("hackney.nb_requests"),
last_value("hackney.finished_requests"),
last_value("hackney.total_requests"),
last_value("hackney_pool.free_count", tags: [:pool]),
last_value("hackney_pool.in_use_count", tags: [:pool]),
last_value("hackney_pool.no_socket", tags: [:pool]),
last_value("hackney_pool.queue_count", tags: [:pool]),
last_value("hackney_pool.take_rate", tags: [:pool])
]
end
end
To build the source code locally you'll need rebar3:
rebar3 compile
rebar3 ct
rebar3 ex_doc
rebar3 steamroll
This project Contributor Covenant version 2.1. Check CODE_OF_CONDUCT.md file for more information.
hackney_telemetry
source code is released under Apache License 2.0.