Trace D-Bus Signals Safely with dbus-monitor

You will finish with a focused trace of messages on a D-Bus message bus, rather than a screen full of unrelated traffic. The examples use the installed dbus-monitor from D-Bus 1.14.10, packaged here as dbus-bin 1.14.10-4ubuntu4.1.

Allow about 10 minutes for a first investigation. You need a shell and access to the bus you want to inspect. Ordinary session-bus monitoring normally needs no elevated privileges. System-bus visibility is controlled by the bus policy, so sudo is not a general fix for missing messages.

What the command is doing

D-Bus carries messages between processes. A bus has a well-known address and routes method calls, replies, errors and signals between clients. dbus-monitor attaches a read-only monitoring client and prints messages that match the watch expressions supplied on the command line.

There are two common buses. --session selects the per-user login-session bus and is the default. --system selects the system-wide bus, where services such as device and service managers may communicate. Use --address ADDRESS only when you already have a specific D-Bus address from the service or its environment.

Start with your session bus and a short timeout. The timeout makes the command safe to copy and paste: it cannot leave a monitor running indefinitely.

timeout 10s dbus-monitor --session --profile

The command should print a tabular header followed by one compact line per message that arrives during the ten seconds. If nothing happens, that is still a useful baseline. Press Ctrl-C to stop an unbounded monitor; stopping it does not change the bus or the services using it.

Checkpoint: choose the bus

1. Run the session-bus probe first:

timeout 10s dbus-monitor --session --profile

2. If the event belongs to a system service, try the system bus:

timeout 10s dbus-monitor --system --profile

A failure such as an inability to connect means the selected bus is unavailable in this shell, not that the target service is broken. A successful connection with no matching lines means that no visible message arrived in the interval, or that the bus policy withheld it.

Filter traffic with a match rule

Unfiltered monitoring is usually too noisy to inspect. A watch expression is a comma-separated set of fields passed as a D-Bus match rule. The most useful starting field is often type: choose signal when you are watching an event emitted by a service.

This example watches property-change signals, which are common when desktop or service state changes:

timeout 15s dbus-monitor --session --profile \
  "type='signal',interface='org.freedesktop.DBus.Properties'"

Expected output begins with a header containing fields such as timestamp, sender, path, interface and member. A matching signal will show the selected interface. The exact sender, object path and payload depend on which application changes state while the command runs.

Add a member when you know the event name. For example, this narrows the same family to the standard PropertiesChanged signal:

timeout 15s dbus-monitor --session --profile \
  "type='signal',interface='org.freedesktop.DBus.Properties',member='PropertiesChanged'"

Do not guess a sender or path and then treat an empty result as proof that no event exists. Names are exact, and many services use a unique bus name such as :1.42 for one process. Begin with stable fields such as message type and interface, observe a match, then narrow the rule using the values shown.

Use readable output when payloads matter

--profile gives one compact line per message with microsecond-resolution timing. It is useful for ordering and latency investigations. The default --monitor format is more verbose and is easier to read when you need message fields and arguments.

timeout 15s dbus-monitor --session --monitor \
  "type='signal',interface='org.freedesktop.DBus.Properties',member='PropertiesChanged'"

Use --monitor when you need to copy a payload into a bug report. Remove private values first: D-Bus arguments can contain paths, account names, device identifiers or application data. The monitor is a diagnostic tap, not an access-control boundary.

Generate a safe test event

To verify that your filter and session bus are working, watch the standard bus interface in one terminal:

timeout 20s dbus-monitor --session --monitor \
  "type='signal',interface='org.freedesktop.DBus',member='NameOwnerChanged'"

In a second terminal, start a short-lived client that asks the bus for its own name. The call is read-only:

dbus-send --session --print-reply \
  --dest=org.freedesktop.DBus /org/freedesktop/DBus \
  org.freedesktop.DBus.GetId

The first terminal may show other ownership changes from clients entering or leaving during the test. If it shows nothing, check that both commands use --session, that the timeout has not expired, and that your watch rule is quoted as one shell argument.

Inspect the system bus without changing it

For a service on the system bus, start with a narrow, time-limited monitor. This example observes signals from the standard properties interface:

timeout 15s dbus-monitor --system --monitor \
  "type='signal',interface='org.freedesktop.DBus.Properties'"

Run this as your normal user first. Bus policy may hide messages or reject monitoring entirely. Only use elevated privileges if the service documentation explicitly requires it and your operational policy permits it:

sudo timeout 15s dbus-monitor --system --monitor \
  "type='signal',interface='org.freedesktop.DBus.Properties'"

Capture output for a tool

Text is the right choice for a first investigation. If another tool needs the complete binary message stream, --binary writes binary messages without the initial authentication handshake. --pcap adds a PCAP header and per-message headers so a packet-analysis tool can read the file.

Both modes produce binary data. Do not send it to a terminal, and avoid overwriting an existing capture:

capture="/tmp/dbus-capture-$$.pcap"
timeout 15s dbus-monitor --session --pcap \
  "type='signal',interface='org.freedesktop.DBus.Properties'" \
  > "$capture"
file "$capture"

The file is temporary evidence, not a harmless log. Review it for sensitive data and remove it when your investigation is complete:

rm -- "$capture"

If the command is interrupted before the shell reaches the assignment or capture step, use the exact path printed by file or list only the specific temporary filename you created. Do not use a broad wildcard under /tmp.

Common traps

• Wrong bus: session and system traffic are separate. Repeat the same narrow rule with the other selector.
• Wrong output expectation: an empty ten-second trace is not an error. Trigger a known event or extend the timeout deliberately.
• Over-broad rules: starting without a filter can bury the useful event. Add type, then interface, then member.
• Shell quoting: keep the complete match rule inside one pair of double quotes. The inner single quotes are part of the D-Bus expression.
• Visibility limits: bus configuration can prevent a non-root monitor from seeing every message. More privileges may increase exposure without proving that the event is absent.
• Long-running processes: use timeout during tests and record the exact rule and bus in notes so a forgotten monitor does not consume attention later.

Done means

• You selected the correct session or system bus.
• You used a time limit while exploring.
• Your rule names the message type and, where useful, interface and member.
• You chose --profile for timing or --monitor for readable payloads.
• You treated captured output as sensitive and removed temporary evidence when finished.