2. User Interface

eProsima Fast DDS Spy is a CLI user application executed from command line and configured through a YAML configuration file.

2.1. Run application

Run eProsima Fast DDS Spy application by using command fastddsspy.

2.1.1. Source Dependency Libraries

eProsima Fast DDS Spy depends on some eProsima projects as Fast DDS or DDS Pipe. In order to correctly execute the application, make sure that these dependencies are properly sourced.

source <path-to-fastdds-installation>/install/setup.bash


If Fast DDS has been installed in the system, these libraries would be sourced by default.

2.2. Application Arguments

The eProsima Fast DDS Spy application supports several input arguments:



Long option


Default Value

Help Argument



Version Argument



Configuration File Argument



Readable File Path


Reload Time Argument



Period (in seconds) to reload
configuration file


Domain Argument


Domain to spy on


Debug Argument



Debug mode


Log Filter Argument


Filter the logs displayed


Log Verbosity Argument


Maximum category of the
logs displayed


2.2.1. Help Argument

It shows the usage information of the application.

Usage: Fast DDS Spy
Start an interactive CLI to introspect a DDS network.
General options:

Application help and information.
-h --help           Print this help message.
-v --version        Print version, branch and commit hash.

Application parameters
-c --config-path    Path to the Configuration File (yaml format) [Default: ./FASTDDSSPY_CONFIGURATION.yaml].
-r --reload-time    Time period in seconds to reload configuration file. This is needed when FileWatcher functionality is not available (e.g. config file is a symbolic link). Value 0 does not reload file. [Default: 0].
   --domain         Set the domain (0-255) to spy on. [Default = 0].

Debug parameters
-d --debug          Set log verbosity to Info (Using this option with --log-filter and/or --log-verbosity will head to undefined behaviour).
   --log-filter     Set a Regex Filter to filter by category the info and warning log entries. [Default = "FASTDDSSPY"].
   --log-verbosity  Set a Log Verbosity Level higher or equal the one given. (Values accepted: "info","warning","error" no Case Sensitive) [Default = "error"].

2.2.2. Version Argument

It shows the current version of the Fast DDS Spy and the hash of the last commit of the compiled code.

2.2.3. Configuration File Argument

A Fast DDS Spy supports YAML configuration file. Please refer to Configuration for more information on how to build this configuration file.

This YAML configuration can passed as argument to Fast DDS Spy when executed. If no configuration file is provided as argument, Fast DDS Spy will attempt to load a file named FASTDDSSPY_CONFIGURATION.yaml that must be in the same directory where the application is executed. If no configuration file is found, Fast DDS Spy will use default configuration. Reload Topics

This configuration file allows to allow and block DDS Topics. A modification in this file will modify the running application.

2.2.4. Reload Time Argument

This argument sets the time period in seconds to reload the configuration file.

2.2.5. Domain Argument

This argument sets the domain id of the Fast DDS Spy.


If set, it will override the domain id set in the configuration file.

2.2.6. Debug Argument

This argument sets the log verbosity to Info.


Using this option with log filter and/or log verbosity will head to undefined behaviour.

2.2.7. Log Filter Argument

Configure the Fast DDS Spy to print the logs that match the given filter. By default the filter is set to FASTDDSSPY for warning and info logs.

2.2.8. Log Verbosity Argument

Configure the Fast DDS Spy to print the logs up to a certain verbosity level. The verbosity levels are (from more to less restrictive): error, warning, and info.

2.3. Interactive application

The standard way to use this application is by running the interactive CLI. This is a user interface that repeatedly ask the user for a command, expecting a stdin command and arguments in order to retrieve the data querying the internal database.

Insert a command for Fast DDS Spy:

Check the following section to see the available commands and their arguments, or use help command to get this information in stdout.

2.3.1. Close Application

Use Quit to stop and close the application.

2.4. One-shot application

eProsima Fast DDS Spy can be executed as a one-shot application. This is, an application that connects to a DDS network, queries a specific command to the internal database generated from such DDS network, and retrieves the information by stdout. Thus it will not ask the user for commands, neither wait before closing.

In order to execute Fast DDS Spy in one-shot mode add the command and arguments right after the last tool argument.

This kind of application depends on the network size and speed in order to discover every entity before showing the information and close. In order to configure the amount of time elapsed before querying for the information requested, use Discovery Time.


Running a Fast DDS Spy instance will create DDS entities that will discover and connect everything in the same network. Thus, running one-shot Fast DDS Spy applications very frequently could affect to network performance, as each instance will be created and destroyed in the process.

2.4.1. Example

Let’s assume we want to retrieve the information of every DomainParticipant running in a current network.

Using the Interactive application, this will be the process and the output:

<path>$ fastddsspy

 ____|             |        __ \   __ \    ___|        ___|
|     _` |   __|  __|      |   |  |   | \___ \      \___ \   __ \   |   |
__|  (   | \__ \  |        |   |  |   |       |           |  |   |  |   |
_|   \__,_| ____/ \__|     ____/  ____/  _____/      _____/   .__/  \__, |
                                                            _|     ____/

Insert a command for Fast DDS Spy:
>> participants
- name: Fast DDS ShapesDemo Participant
  guid: 01.0f.|0.0.1.c1

Insert a command for Fast DDS Spy:
>> quit

However, using One-shot application this will be expected result:

<path>$ fastddsspy participants
- name: Fast DDS ShapesDemo Participant
  guid: 01.0f.|0.0.1.c1