spec: Document the o.fd.DBus.Debug.Stats interface

We never actually documented this when it was added to the dbus-daemon.
Do so now.

Signed-off-by: Simon McVittie <smcv@collabora.com>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 03d25d584fd13c6c40d785c86e342ab3be71348d..a494cdf0df8fa7f21621e6a9187ed0d48b358ca2 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -7531,6 +7531,375 @@
       </sect3>
     </sect2>
 
+    <sect2 id="message-bus-debug-stats-interface">
+      <title>Debug Statistics Interface: <literal>org.freedesktop.DBus.Debug.Stats</literal></title>
+      <para>
+        The special message bus name <literal>org.freedesktop.DBus</literal>
+        may optionally implement the
+        <literal>org.freedesktop.DBus.Debug.Stats</literal> interface on
+        the object path <literal>/org/freedesktop/DBus</literal>.
+        This interface provides statistics which might be useful to
+        investigate performance bottlenecks.
+      </para>
+      <para>
+        In the reference implementation, this interface is an optional
+        feature, which can be enabled or disabled at compile-time.
+        On the well-known system bus or other buses that serve more than
+        one user, access to this interface should normally be restricted to
+        administrative users, but can be opened up to developers via
+        configuration if required.
+      </para>
+
+      <sect3 id="bus-messages-get-stats">
+        <title>Method: <literal>org.freedesktop.DBus.Debug.Stats.GetStats</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            GetStats (out ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; stats)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;</entry>
+                  <entry>Statistics</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Get statistics about the message bus itself.
+        </para>
+        <para>
+          The following keys in the result dictionary are defined by
+          this specification:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Key</entry>
+                  <entry>Value type</entry>
+                  <entry>Value</entry>
+                </row>
+              </thead>
+              <tbody>
+
+                <!-- Basic information -->
+                <row>
+                  <entry><literal>Serial</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>A serial number which is incremented with each
+                    call to the <literal>GetStats</literal> method.</entry>
+                </row>
+
+                <!-- Connection count -->
+                <row>
+                  <entry><literal>ActiveConnections</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The number of active connections currently handled
+                    by this message bus.
+                    The exact meaning of an active connection is
+                    implementation-defined: in the reference dbus-daemon,
+                    a connection is considered to be active after it has
+                    successfully called
+                    <link xref="bus-messages-hello">the Hello
+                      method</link>.</entry>
+                </row>
+                <row>
+                  <entry><literal>IncompleteConnections</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The number of incomplete connections currently handled
+                    by this message bus.
+                    The exact meaning of an incomplete connection is
+                    implementation-defined: in the reference dbus-daemon,
+                    a connection is considered to be incomplete if it is
+                    still carrying out the SASL handshake or if it has not
+                    yet successfully called
+                    <link xref="bus-messages-hello">the Hello
+                      method</link>.</entry>
+                </row>
+
+                <!-- Match rules -->
+                <row>
+                  <entry><literal>MatchRules</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of match rules that are
+                    currently in use.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakMatchRules</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The largest total number of match rules that have
+                    been in use at any one time.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakMatchRulesPerConnection</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The largest total number of match rules that have
+                    been in use by a single connection at any one time.</entry>
+                </row>
+
+                <!-- Bus names -->
+                <row>
+                  <entry><literal>BusNames</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of unique or well-known bus names
+                    that are currently owned by all connections.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakBusNames</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The largest total number of bus names
+                    that have been owned by all connections at any
+                    one time.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakBusNamesPerConnection</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The largest total number of bus names
+                    that have been owned by any single connection at any
+                    one time.</entry>
+                </row>
+
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          All other keys are implementation-specific until or unless they
+          are standardized in this specification.
+          The reference dbus-daemon provides additional keys
+          <literal>ListMemPoolUsedBytes</literal>,
+          <literal>ListMemPoolCachedBytes</literal>,
+          <literal>ListMemPoolAllocatedBytes</literal>
+          with UINT32 values, all of which describe implementation details
+          of libdbus’ memory management.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-get-connection-stats">
+        <title>Method: <literal>org.freedesktop.DBus.Debug.Stats.GetConnectionStats</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            GetConnectionStats (in STRING connection, out ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; stats)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Unique or well-known name of a connection</entry>
+                </row>
+                <row>
+                  <entry>1</entry>
+                  <entry>ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;</entry>
+                  <entry>Statistics</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Get statistics about a connection, identified by its unique
+          connection name or by any well-known bus name for which it is
+          the primary owner.
+          This method is not meaningful for the message bus
+          <literal>org.freedesktop.DBus</literal> itself.
+       </para>
+        <para>
+          The following keys in the result dictionary are defined by
+          this specification:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Key</entry>
+                  <entry>Value type</entry>
+                  <entry>Value</entry>
+                </row>
+              </thead>
+              <tbody>
+
+                <!-- Basic information -->
+                <row>
+                  <entry><literal>Serial</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>A serial number which is incremented with each
+                    call to the <literal>GetConnectionStats</literal>
+                    method.</entry>
+                </row>
+                <row>
+                  <entry><literal>UniqueName</literal></entry>
+                  <entry>STRING</entry>
+                  <entry>The connection's unique connection name.
+                    If the first parameter to
+                    <literal>GetConnectionStats</literal> was a unique
+                    name, this will be the same unique name.
+                    If the first parameter was a well-known name, this
+                    is equivalent to the result of calling
+                    <link xref="bus-messages-get-name-owner">GetNameOwner</link>
+                    on that well-known name.</entry>
+                </row>
+
+                <!-- Match rules -->
+                <row>
+                  <entry><literal>MatchRules</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of match rules that are
+                    currently in use by this connection.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakMatchRules</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The largest total number of match rules that have
+                    been in use by this connection at any one time.</entry>
+                </row>
+
+                <!-- Bus names -->
+                <row>
+                  <entry><literal>BusNames</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of bus names that are
+                    currently owned by this connection.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakBusNames</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The largest total number of bus names
+                    that have been owned by this connection at any
+                    one time.</entry>
+                </row>
+
+                <!-- Incoming queued messages -->
+                <row>
+                  <entry><literal>IncomingMessages</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of messages queued in the message
+                    bus that have been received from this connection and not
+                    yet dispatched.</entry>
+                </row>
+                <row>
+                  <entry><literal>IncomingBytes</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of bytes in the incoming
+                    messages.</entry>
+                </row>
+                <row>
+                  <entry><literal>IncomingFDs</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of Unix file descriptors
+                    attached to the incoming messages.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakIncomingBytes</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The highest total number of bytes in the incoming
+                    messages at any one time.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakIncomingFDs</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The highest total number of Unix file descriptors
+                    attached to the incoming messages at any one time.</entry>
+                </row>
+
+                <!-- Outgoing queued messages -->
+                <row>
+                  <entry><literal>OutgoingMessages</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of messages queued in the message
+                    bus to be delivered to this connection.</entry>
+                </row>
+                <row>
+                  <entry><literal>OutgoingBytes</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of bytes in the outgoing
+                    messages.</entry>
+                </row>
+                <row>
+                  <entry><literal>OutgoingFDs</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The total number of Unix file descriptors
+                    attached to the outgoing messages.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakOutgoingBytes</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The highest total number of bytes in the outgoing
+                    messages at any one time.</entry>
+                </row>
+                <row>
+                  <entry><literal>PeakOutgoingFDs</literal></entry>
+                  <entry>UINT32</entry>
+                  <entry>The highest total number of Unix file descriptors
+                    attached to the outgoing messages at any one time.</entry>
+                </row>
+
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          All other keys are implementation-specific until or unless they
+          are standardized in this specification.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-get-all-match-rules">
+        <title>Method: <literal>org.freedesktop.DBus.Debug.Stats.GetAllMatchRules</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            GetAllMatchRules (out ARRAY of DICT_ENTRY&lt;STRING,ARRAY&lt;STRING&gt;&gt; rules)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>ARRAY of DICT_ENTRY&lt;STRING,ARRAY&lt;STRING&gt;&gt;</entry>
+                  <entry>Match rules</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          List all of the match rules that are active on this message bus.
+          The keys in the result dictionary are unique connection names.
+          The values are lists of match rules registered by that connection,
+          in an unspecified order.
+          If a connection has registered the same match rule more than once,
+          it is unspecified whether duplicate entries appear in the list.
+       </para>
+      </sect3>
+
+    </sect2>
+
   </sect1>
 <!--
   <appendix id="implementation-notes">