From: Simon McVittie Date: Wed, 25 Sep 2024 16:59:36 +0000 (+0100) Subject: spec: Document the o.fd.DBus.Debug.Stats interface X-Git-Tag: dbus-1.15.12~15^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=07c0a5232e0834515a62965d8cba25690e0c5c0c;p=thirdparty%2Fdbus.git 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 --- diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 03d25d584..a494cdf0d 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -7531,6 +7531,375 @@ + + Debug Statistics Interface: <literal>org.freedesktop.DBus.Debug.Stats</literal> + + The special message bus name org.freedesktop.DBus + may optionally implement the + org.freedesktop.DBus.Debug.Stats interface on + the object path /org/freedesktop/DBus. + This interface provides statistics which might be useful to + investigate performance bottlenecks. + + + 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. + + + + Method: <literal>org.freedesktop.DBus.Debug.Stats.GetStats</literal> + + As a method: + + GetStats (out ARRAY of DICT_ENTRY<STRING,VARIANT> stats) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of DICT_ENTRY<STRING,VARIANT> + Statistics + + + + + Get statistics about the message bus itself. + + + The following keys in the result dictionary are defined by + this specification: + + + + + + Key + Value type + Value + + + + + + + Serial + UINT32 + A serial number which is incremented with each + call to the GetStats method. + + + + + ActiveConnections + UINT32 + 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 + the Hello + method. + + + IncompleteConnections + UINT32 + 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 + the Hello + method. + + + + + MatchRules + UINT32 + The total number of match rules that are + currently in use. + + + PeakMatchRules + UINT32 + The largest total number of match rules that have + been in use at any one time. + + + PeakMatchRulesPerConnection + UINT32 + The largest total number of match rules that have + been in use by a single connection at any one time. + + + + + BusNames + UINT32 + The total number of unique or well-known bus names + that are currently owned by all connections. + + + PeakBusNames + UINT32 + The largest total number of bus names + that have been owned by all connections at any + one time. + + + PeakBusNamesPerConnection + UINT32 + The largest total number of bus names + that have been owned by any single connection at any + one time. + + + + + + + + All other keys are implementation-specific until or unless they + are standardized in this specification. + The reference dbus-daemon provides additional keys + ListMemPoolUsedBytes, + ListMemPoolCachedBytes, + ListMemPoolAllocatedBytes + with UINT32 values, all of which describe implementation details + of libdbus’ memory management. + + + + + Method: <literal>org.freedesktop.DBus.Debug.Stats.GetConnectionStats</literal> + + As a method: + + GetConnectionStats (in STRING connection, out ARRAY of DICT_ENTRY<STRING,VARIANT> stats) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known name of a connection + + + 1 + ARRAY of DICT_ENTRY<STRING,VARIANT> + Statistics + + + + + 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 + org.freedesktop.DBus itself. + + + The following keys in the result dictionary are defined by + this specification: + + + + + + Key + Value type + Value + + + + + + + Serial + UINT32 + A serial number which is incremented with each + call to the GetConnectionStats + method. + + + UniqueName + STRING + The connection's unique connection name. + If the first parameter to + GetConnectionStats 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 + GetNameOwner + on that well-known name. + + + + + MatchRules + UINT32 + The total number of match rules that are + currently in use by this connection. + + + PeakMatchRules + UINT32 + The largest total number of match rules that have + been in use by this connection at any one time. + + + + + BusNames + UINT32 + The total number of bus names that are + currently owned by this connection. + + + PeakBusNames + UINT32 + The largest total number of bus names + that have been owned by this connection at any + one time. + + + + + IncomingMessages + UINT32 + The total number of messages queued in the message + bus that have been received from this connection and not + yet dispatched. + + + IncomingBytes + UINT32 + The total number of bytes in the incoming + messages. + + + IncomingFDs + UINT32 + The total number of Unix file descriptors + attached to the incoming messages. + + + PeakIncomingBytes + UINT32 + The highest total number of bytes in the incoming + messages at any one time. + + + PeakIncomingFDs + UINT32 + The highest total number of Unix file descriptors + attached to the incoming messages at any one time. + + + + + OutgoingMessages + UINT32 + The total number of messages queued in the message + bus to be delivered to this connection. + + + OutgoingBytes + UINT32 + The total number of bytes in the outgoing + messages. + + + OutgoingFDs + UINT32 + The total number of Unix file descriptors + attached to the outgoing messages. + + + PeakOutgoingBytes + UINT32 + The highest total number of bytes in the outgoing + messages at any one time. + + + PeakOutgoingFDs + UINT32 + The highest total number of Unix file descriptors + attached to the outgoing messages at any one time. + + + + + + + + All other keys are implementation-specific until or unless they + are standardized in this specification. + + + + + Method: <literal>org.freedesktop.DBus.Debug.Stats.GetAllMatchRules</literal> + + As a method: + + GetAllMatchRules (out ARRAY of DICT_ENTRY<STRING,ARRAY<STRING>> rules) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of DICT_ENTRY<STRING,ARRAY<STRING>> + Match rules + + + + + 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. + + + + +