Merge pull request #67 from mmatloka/feature/prometheus

Prometheus backend

3 files changed, 34 insertions, 2 deletions

diff --git a/docs/backends/prometheus.rst b/docs/backends/prometheus.rst
new file mode 100644
index 0000000..9de7886
--- /dev/null
+++ b/docs/backends/prometheus.rst
@@ -0,0 +1,30 @@
+.. _prometheus_backend:
+
+Prometheus backend
+=============
+
+To use, add the following dependency to your project::
+
+  "com.softwaremill.sttp" %% "prometheus-backend" % "1.1.6"
+
+This backend depends on `Prometheus JVM Client <https://github.com/prometheus/client_java>`_. Keep in mind this backend registers histograms and gathers request times, but you have to expose those metrics to `Prometheus <https://prometheus.io/>`_ e.g. using  `prometheus-akka-http <https://github.com/lonelyplanet/prometheus-akka-http>`_.
+
+The Prometheus backend wraps any other backend, for example::
+
+  implicit val sttpBackend = PrometheusBackend(AkkaHttpBackend())
+
+It gathers request execution times in ``Histogram``. It uses by default ``sttp_request_latency`` name, defined in ``PrometheusBackend.DefaultHistogramName``. It is possible to define custom histograms name by passing function mapping request to histogram name::
+
+  implicit val sttpBackend = PrometheusBackend(AkkaHttpBackend(), request => Some(request.uri.host))
+
+You can disable request histograms by passing ``None`` returning function::
+
+  implicit val sttpBackend = PrometheusBackend(AkkaHttpBackend(), _ => None)
+
+This backend also offers ``Gauge`` with currently in-progress requests number. It uses by default ``sttp_requests_in_progress`` name, defined in ``PrometheusBackend.DefaultRequestsInProgressGaugeName``. It is possible to define custom gauge name by passing function mapping request to gauge name::
+
+   implicit val sttpBackend = PrometheusBackend(AkkaHttpBackend(), requestToInProgressGaugeNameMapper = request => Some(request.uri.host))
+
+You can disable request in-progress gauges by passing ``None`` returning function::
+
+  implicit val sttpBackend = PrometheusBackend(AkkaHttpBackend(), requestToInProgressGaugeNameMapper = _ => None)
\ No newline at end of file
diff --git a/docs/backends/summary.rst b/docs/backends/summary.rst
index 9fb9dec..11e9b55 100644
--- a/docs/backends/summary.rst
+++ b/docs/backends/summary.rst
@@ -17,7 +17,7 @@ Below is a summary of all the backends. See the sections on individual backend i
 ================================ ============================ ================================================
 Class                            Response wrapper             Supported stream type
 ================================ ============================ ================================================
-``HttpURLConnectionBackend``     None (``Id``)                n/a 
+``HttpURLConnectionBackend``     None (``Id``)                n/a
 ``TryHttpURLConnectionBackend``  ``scala.util.Try``           n/a
 ``AkkaHttpBackend``              ``scala.concurrent.Future``  ``akka.stream.scaladsl.Source[ByteString, Any]``
 ``AsyncHttpClientFutureBackend`` ``scala.concurrent.Future``  n/a
@@ -33,4 +33,5 @@ Class                            Response wrapper             Supported stream t
 There are also backends which wrap other backends to provide additional functionality. These include:
 
 * ``TryBackend``, which safely wraps any exceptions thrwon by a synchronous backend in ``scala.util.Try``
-* ``BraveBackend``, for Zipkin-compatible distributed tracing. See the :ref:`dedicated section <brave_backend>`.
\ No newline at end of file
+* ``BraveBackend``, for Zipkin-compatible distributed tracing. See the :ref:`dedicated section <brave_backend>`.
+* ``PrometheusBackend``, for gathering Prometheus-format metrics. See the :ref:`dedicated section <prometheus_backend>`.
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 1f97373..0ea1cda 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -68,6 +68,7 @@ For more examples, see the :ref:`usage examples <usage_examples>` section. Or ex
    backends/asynchttpclient
    backends/okhttp
    backends/brave
+   backends/prometheus
    backends/custom
 
 .. toctree::