tree: c5f7288b91a9d41ddb8d0330a83796b355b9219d [path history] [tgz]
  5. command_line_options.h
  7. lib/

fidlcat: Monitor and debug your fidl calls


fidlcat is a tool that allows users to monitor FIDL connections. Currently, it can attach to or launch a process on a Fuchsia device, and will report its FIDL traffic.

Running it

To run fidlcat in-tree, you first build it, which you can do the following way:

fx set <whatever> --with //bundles:tools
fx build

If you want to add it to your existing gn args, you can do so by adding this stanza to the bottom of your <build_dir>/

universe_package_labels += [ "//bundles:tools" ]

To run fidlcat, you must boot with networking enabled.

For QEMU networking support, you need to setup your system with a TUN/TAP interface. Then, run:

fx run -N

In a separate console, you need to ensure your target is able to fetch updates:

fx serve

You should then be able to use fidlcat to monitor FIDL messages from processes on the target. If you run the ps command in the shell, you can get a pid you want to monitor, and run:

fx fidlcat --remote-pid <pid>

Alternatively, you can launch a component directly using its URL:

fx fidlcat run fuchsia-pkg://

You can also attach to programs that have not started yet by passing a regex to match their names. If you issue the following command, fidlcat will connect to the system, wait for a program with the substring “echo_client” to start, and automatically attach to it.

fx fidlcat --filter echo_client

Note that fidlcat needs two sources of information to work:

  • First, it needs the symbols for the executable. In practice, if you are running in-tree, the symbols should be provided to fidlcat automatically. Otherwise, you can provide fidlcat a symbol path, which can be a text file that maps build ids to debug symbols, an explicit ELF file path, or a directory it will scan for ELF files and index. This can be provided to fidlcat with the -s flag.

  • Second, it needs the intermediate representation for the FIDL it ingests, so it can produce readable output. If you are running in-tree, the IR should be provided to fidlcat automatically. Otherwise, you can provide fidlcat an IR path, which can be an explicit IR file path, a directory it will scan for IR files, or an argument file containing explicit paths. This can be provided to fidlcat with the --fidl-ir-path flag. The argument files need to be prepended with a @ character: --fidl-ir-path @argfile.

Finally, if you are running fidlcat without the fx tool, the debug agent needs to be running on the target. Connect to the target and run:

run fuchsia-pkg:// --port=8080

And, when you run fidlcat on the host, make sure you connect to that agent:

tools/fidlcat --connect [$(fx netaddr --fuchsia)]:8080 <other args>