From 3c485a0deae6e5913655f379a04e3a587271ba40 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <vlorentz@softwareheritage.org>
Date: Mon, 9 Jan 2023 09:19:22 +0000
Subject: [PATCH] Document new metrics on outgoing API requests

---
 docs/statsd.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/statsd.rst b/docs/statsd.rst
index 04710881..3fbdd58f 100644
--- a/docs/statsd.rst
+++ b/docs/statsd.rst
@@ -91,6 +91,24 @@ In addition to :ref:`swh_statsd_metrics_rpc`,
 * ``swh_objstorage_in_bytes_total``
 * ``swh_objstorage_out_bytes_total``
 
+.. _swh_statsd_metrics_outgoing:
+
+Outgoing requests
+-----------------
+
+All these metrics are labelled with ``api_type`` and ``api_instance``, which
+should match values used for ``lister_name`` and ``lister_instance`` used elsewhere.
+Currently, it is only ``github`` for both.
+They are also labelled with ``username``, which is either ``anonymous`` or the name of
+the user owning the token used to make the request.
+
+* ``swh_outbound_api_requests_total``: total number of requests
+* ``swh_outbound_api_responses_total``: total number of responses (excluding low-level failures: DNS, TCP, TLS, ...), with ``http_status`` label
+* ``swh_outbound_api_remaining_requests``: gauge of the value of ``X-Ratelimit-Remaining``
+* ``swh_outbound_api_reset_seconds``: gauge of the value of ``X-Ratelimit-Reset``
+* ``swh_outbound_api_rate_limited_responses_total``
+* ``swh_outbound_api_sleep_seconds_total``: number of seconds spent waiting for rate limits to reset
+
 .. _swh_statsd_metrics_provenance:
 
 Provenance
-- 
GitLab