core: add API to measure event loop idle time

The API addition `uv_metrics_idle_time()` is a thread safe call that
allows the user to retrieve the amount of time the event loop has spent
in the kernel's event provider (i.e. poll). It was done this way to
allow retrieving this value without needing to interrupt the execution
of the event loop. This option can be enabled by passing
`UV_METRICS_IDLE_TIME` to `uv_loop_configure()`.

One important aspect of this change is, when enabled, to always first
call the event provider with a `timeout == 0`. This allows libuv to know
whether any events were waiting in the event queue when the event
provider was called. The importance of this is because libuv is tracking
the amount of "idle time", not "poll time". Thus the provider entry time
is not recorded when `timeout == 0` (the event provider never idles in
this case).

While this does add a small amount of overhead, when enabled, but the
overhead decreases when the event loop has a heavier load. This is
because poll events will be waiting when the event provider is called.
Thus never actually recording the provider entry time.

Checking if `uv_loop_t` is configured with `UV_METRICS_IDLE_TIME` always
happens in `uv__metrics_set_provider_entry_time()` and
`uv__metrics_update_idle_time()`. Making the conditional logic wrapping
each call simpler and allows for instrumentation to always hook into
those two function calls.

Rather than placing the fields directly on `uv__loop_internal_fields_t`
add the struct `uv__loop_metrics_t` as a location for future metrics API
additions.

Tests and additional documentation has been included.

PR-URL: https://github.com/libuv/libuv/pull/2725
Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com>
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
Reviewed-By: Jameson Nash <vtjnash@gmail.com>

3 files changed, 31 insertions, 0 deletions

diff --git a/docs/src/api.rst b/docs/src/api.rst
index 22f0640f..c8e837dd 100644
--- a/docs/src/api.rst
+++ b/docs/src/api.rst
@@ -32,4 +32,5 @@ API documentation
    dll
    threading
    misc
+   metrics
 
diff --git a/docs/src/loop.rst b/docs/src/loop.rst
index d642ac1d..fc747c27 100644
--- a/docs/src/loop.rst
+++ b/docs/src/loop.rst
@@ -68,6 +68,11 @@ API
       to suppress unnecessary wakeups when using a sampling profiler.
       Requesting other signals will fail with UV_EINVAL.
 
+    - UV_METRICS_IDLE_TIME: Accumulate the amount of idle time the event loop
+      spends in the event provider.
+
+      This option is necessary to use :c:func:`uv_metrics_idle_time`.
+
 .. c:function:: int uv_loop_close(uv_loop_t* loop)
 
     Releases all internal loop resources. Call this function only when the loop
diff --git a/docs/src/metrics.rst b/docs/src/metrics.rst
new file mode 100644
index 00000000..223f7feb
--- /dev/null
+++ b/docs/src/metrics.rst
@@ -0,0 +1,25 @@
+
+.. _metrics:
+
+Metrics operations
+======================
+
+libuv provides a metrics API to track the amount of time the event loop has
+spent idle in the kernel's event provider.
+
+API
+---
+
+.. c:function:: uint64_t uv_metrics_idle_time(uv_loop_t* loop)
+
+    Retrieve the amount of time the event loop has been idle in the kernel's
+    event provider (e.g. ``epoll_wait``). The call is thread safe.
+
+    The return value is the accumulated time spent idle in the kernel's event
+    provider starting from when the :c:type:`uv_loop_t` was configured to
+    collect the idle time.
+
+    .. note::
+        The event loop will not begin accumulating the event provider's idle
+        time until calling :c:type:`uv_loop_configure` with
+        :c:type:`UV_METRICS_IDLE_TIME`.