docs for worker.stats()

- generate most of it from source
- make order the same in implementation and description

diff --git a/daemon/README.rst b/daemon/README.rst
index 6b31f994d5665ee2e14bdb75e4d77e0826a5da43..0297f7387e0fa8514cb80e12b4e33d414b98db09 100644 (file)
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -648,6 +648,13 @@ Example:
        $ echo $?
        0
 
+
+Code reference
+==============
+
+.. doxygenfile:: daemon/worker.h
+
+
 .. _`JSON-encoded`: http://json.org/example
 .. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
 .. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/scripting/

diff --git a/daemon/bindings/worker.c b/daemon/bindings/worker.c
index 3850895caa5565494411f9899c3a5c558e8fdad5..ed859c7de2a04f61ac715f6591d784bb6bc12e21 100644 (file)
--- a/daemon/bindings/worker.c
+++ b/daemon/bindings/worker.c
@@ -127,24 +127,26 @@ static int wrk_stats(lua_State *L)
                return 0;
        }
        lua_newtable(L);
+       lua_pushnumber(L, worker->stats.queries);
+       lua_setfield(L, -2, "queries");
        lua_pushnumber(L, worker->stats.concurrent);
        lua_setfield(L, -2, "concurrent");
+       lua_pushnumber(L, worker->stats.dropped);
+       lua_setfield(L, -2, "dropped");
+
+       lua_pushnumber(L, worker->stats.timeout);
+       lua_setfield(L, -2, "timeout");
        lua_pushnumber(L, worker->stats.udp);
        lua_setfield(L, -2, "udp");
        lua_pushnumber(L, worker->stats.tcp);
        lua_setfield(L, -2, "tcp");
        lua_pushnumber(L, worker->stats.tls);
        lua_setfield(L, -2, "tls");
-       lua_pushnumber(L, worker->stats.ipv6);
-       lua_setfield(L, -2, "ipv6");
        lua_pushnumber(L, worker->stats.ipv4);
        lua_setfield(L, -2, "ipv4");
-       lua_pushnumber(L, worker->stats.queries);
-       lua_setfield(L, -2, "queries");
-       lua_pushnumber(L, worker->stats.dropped);
-       lua_setfield(L, -2, "dropped");
-       lua_pushnumber(L, worker->stats.timeout);
-       lua_setfield(L, -2, "timeout");
+       lua_pushnumber(L, worker->stats.ipv6);
+       lua_setfield(L, -2, "ipv6");
+
        /* Add subset of rusage that represents counters. */
        uv_rusage_t rusage;
        if (uv_getrusage(&rusage) == 0) {

diff --git a/daemon/bindings/worker.rst b/daemon/bindings/worker.rst
index c8982b26d0545915fb68b54f7470007b2352d2c2..63e9da451c2c7597fa0aa6284e9015a8056aca16 100644 (file)
--- a/daemon/bindings/worker.rst
+++ b/daemon/bindings/worker.rst
@@ -22,16 +22,14 @@ specified worker count and process rank.
 
 .. function:: worker.stats()
 
-   Return table of statistics.
-
-   * ``udp`` - number of outbound queries over UDP
-   * ``tcp`` - number of outbound queries over TCP
-   * ``ipv6`` - number of outbound queries over IPv6
-   * ``ipv4`` - number of outbound queries over IPv4
-   * ``timeout`` - number of timeouted outbound queries
-   * ``concurrent`` - number of concurrent queries at the moment
-   * ``queries`` - number of inbound queries
-   * ``dropped`` - number of dropped inbound queries
+   Return table of statistics.  See member descriptions in :c:type:`worker_stats`.
+   A few fields are added, mainly from POSIX ``getrusage()``:
+
+   * ``usertime`` and ``systime`` -- CPU time used, in seconds
+   * ``pagefaults`` -- the number of hard page faults, i.e. those that required I/O activity
+   * ``swaps`` -- the number of times the process was “swapped” out of main memory; unused on Linux
+   * ``csw`` -- the number of context switches, both voluntary and involuntary
+   * ``rss`` -- current memory usage in bytes, including whole cache (resident set size)
 
    Example:
 

diff --git a/daemon/worker.h b/daemon/worker.h
index f56e10d0651e176c09e118ace8272d839c32ef45..2882d4904d355babd5825d4db2fc2a2de4748845 100644 (file)
--- a/daemon/worker.h
+++ b/daemon/worker.h
@@ -107,6 +107,22 @@ uint64_t worker_task_creation_time(struct qr_task *task);
 void worker_task_subreq_finalize(struct qr_task *task);
 bool worker_task_finished(struct qr_task *task);
 
+
+/** Various worker statistics.  Sync with wrk_stats() */
+struct worker_stats {
+       size_t queries;     /**< Total number of requests (from clients and internal ones). */
+       size_t concurrent;  /**< The number of requests currently in processing. */
+       size_t rconcurrent; /*< TODO: remove?  I see no meaningful difference from .concurrent. */
+       size_t dropped;     /**< The number of requests dropped due to being badly formed.  See #471. */
+
+       size_t timeout; /**< Number of outbound queries that timed out. */
+       size_t udp;  /**< Number of outbound queries over UDP. */
+       size_t tcp;  /**< Number of outbound queries over TCP (excluding TLS). */
+       size_t tls;  /**< Number of outbound queries over TLS. */
+       size_t ipv4; /**< Number of outbound queries over IPv4.*/
+       size_t ipv6; /**< Number of outbound queries over IPv6. */
+};
+
 /** @cond internal */
 
 /** Number of request within timeout window. */
@@ -140,18 +156,7 @@ struct worker_ctx {
 
        uint8_t wire_buf[RECVMMSG_BATCH * KNOT_WIRE_MAX_PKTSIZE];
 
-       struct {
-               size_t concurrent;
-               size_t rconcurrent;
-               size_t udp;
-               size_t tcp;
-               size_t tls;
-               size_t ipv4;
-               size_t ipv6;
-               size_t queries;
-               size_t dropped;
-               size_t timeout;
-       } stats;
+       struct worker_stats stats;
 
        struct zone_import_ctx* z_import;
        bool too_many_open;

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 6e57cb37d54225c970dda018d2431a0439bdab76..1e41e94f1f9171f7e6fc8c51c78af148468a418c 100644 (file)
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -5,7 +5,7 @@ GENERATE_LATEX    = NO
 GENERATE_MAN      = NO
 GENERATE_RTF      = NO
 CASE_SENSE_NAMES  = NO
-INPUT             = ../lib
+INPUT             = ../lib ../daemon
 FILE_PATTERNS     = *.h
 QUIET             = YES
 RECURSIVE         = YES