mirror of
https://gitlab.freedesktop.org/dbus/dbus.git
synced 2026-05-08 11:28:01 +02:00
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>
This commit is contained in:
Simon McVittie
parent
ec2e24630c
commit
07c0a5232e
1 changed files with 369 additions and 0 deletions
|
|
@ -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<STRING,VARIANT> 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<STRING,VARIANT></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<STRING,VARIANT> 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<STRING,VARIANT></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<STRING,ARRAY<STRING>> 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<STRING,ARRAY<STRING>></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">
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue