Google is committed to advancing racial equity for Black communities. See how.

fx fidlcat

run fidlcat on given target.

Runs fidlcat in the given configuration; currently, fidlcat logs all FIDL
chatter from the given target executable.  Starts the debug agent on the
proposed target, and closes the debug agent on exit.

CAUTION: This support is experimental, and invocation strategy is likely to
change.  The component launching configuration is *especially* likely to go
away over time.

TROUBLESHOOTING TIPS:

- Remember to use "fx set-device" when working with multiple devices.
- This scripts by default will mute the SSH connection stdout/stderr, so any
  errors triggered by it won't appear. Use the --debug-mode flag to see
  the debug log's from the debug agent and fidlcat.
- This scripts uses the tool "nc" for testing TCP connections. Check that it
  is in $PATH and that it works.

Usage: fx fidlcat [--debug-mode] [(--port|-p) <PORT>] [--with-symbol-server]
                  [--with-process-info] [--stack=<value>]
                  [--syscalls=<regexp>] [--exclude-syscalls=<regexp>] [--dump-messages]
                  [--verbose=<value> | --quiet=<value>] [--log-file <path>]
                  [--remote-pid=<pid> | --remote-name=<name> | run <component specification>]

   --port                Port the debug agent will be listening on. Will use 2345
                         by default.
   --with-symbol-server  Connect to the symbol server. The first time you use this option,
                         fidlcat will give you a link to an authentication page.
                         You then have to use the generated key to authenticate.
   --debug-mode          Whether the debug agent's debug logs should be shown.
   --with-process-info   Display the process name, process id and thread id on
                         each line (useful for grep).
   --stack=<value>       Define the amount of stack frame to display
                         0: none (default value)
                         1: call site (1 to 4 levels)
                         2: full stack frame (adds some overhead)
   --syscalls            A regular expression which selects the syscalls to decode and display.
                         Can be passed multiple times.
                         By default, only zx_channel_.* syscalls are displayed.
                         To display all the syscalls, use: --syscalls ".*"
   --exclude-syscalls    A regular expression which selects the syscalls to not decode and
                         display.
                         Can be passed multiple times.
                         To be displayed, a syscall must verify --syscalls and not verify
                         --exclude-syscalls.
                         To display all the syscalls but the zx_handle syscalls, use:
                         --syscalls ".*" --exclude-syscalls "zx_handle_.*"
   --messages            A regular expression which selects the messages to display.
                         To display a message, the method name must satisfy the regexp.
                         This option can be specified multiple times.
                         Message filtering works on the method's fully qualified name.
   --exclude-messages    A regular expression which selects the messages to not display.
                         If a message method name satisfy the regexp, the message is not
                         displayed (even if it satifies --messages).
                         This option can be specified multiple times.
                         Message filtering works on the method's fully qualified name.
   --trigger=<regexp>    Start displaying messages and syscalls only when a message for which
                         the method name satisfies the filter is found.
                         This option can be specified multiple times.
                         Message filtering works on the method's fully qualified name.
   --dump-messages       Always does a hexadecimal dump of the messages even if we can
                         decode them.
   --verbose=<value>     The log verbosity.  Legal values are "info", "warning",
                         "error", "fatal", or a number, starting from 0. Extra
                         verbosity comes with higher levels.
   --quiet=<value>       The log verbosity.  Legal values are "info", "warning",
                         "error", "fatal", or a number, starting from 0. Extra
                         verbosity comes with lower levels.
   --log-file=<path>     The log file destination.
   --remote-pid          The koid of the remote process to trace
   --remote-name         A set of comma-separated regexes. Fidlcat will monitor all existing
                         and future processes whose names match one of the regexes.
                         Can be provided multiple times for multiple regexes.
   --extra-name          Like --remote-name, it monitors some processes. However, for these
                         processes, monitoring starts only when one of of the "--remote-name"
                         process is launched. Also, fidlcat stops when the last "--remote-name"
                         process stops (even if some "--extra-name" processes are still
                         monitored).
   --symbol-path=<path>  An extra location where fidlcat can find debug symbols.
   --fidl-ir-path=<path> An extra location where fidlcat can find FIDL compiled files.
   --gdb                 Launch fidlcat using gdb. This is only useful to be able to debug
                         fidlcat. When this option is used, the string you have to type within
                         gdb to launch fidlcat is printed and then, gdb is launched.
                         This option only works if you have the unstripped version of fidlcat.
   run                   A token indicating that you want to invoke and trace
                         the following component. The component is specified
                         with either a bash regex that matches a component URL
                         known to the build, or a full component URL not known
                         to your build, but available to your target.

Flags after -- are parsed by fidlcat.  Example usage:

# Attaches to the process with the given pid on the target:
fx fidlcat --remote-pid=4755

# Launches the echo client, and monitors its FIDL chatter:
fx fidlcat run fuchsia-pkg://fuchsia.com/echo_client_cpp#meta/echo_client_cpp.cmx

# Also launches the echo client, and monitors its FIDL chatter:
fx fidlcat run echo_client_cpp.cmx

# Will trace existing and future processes whose name contains "echo_client"
fx fidlcat --remote-name=echo_client

All three options --remote-pid, --remote-name and run can be used together.
However, run must always be the last one.
When --remote-name and run are used together, only processes which match
--remote-name are monitored.

Examples (echo_server is launched by echo_client):

# run and monitor echo_client.
fx fidlcat run echo_client_cpp.cmx

# run and monitor echo_client.
fx fidlcat --remote-name=echo_client run echo_client_cpp.cmx

# run echo_client and monitor echo_server.
fx fidlcat --remote-name=echo_server run echo_client_cpp.cmx

# run echo_client and monitor echo_client and echo_server.
fx fidlcat --remote-name=echo run echo_client_cpp.cmx

# run echo_client and monitor echo_client and echo_server.
fx fidlcat --remote-name=echo_client --remote-name=echo_server run echo_client_cpp.cmx

fidlcat source code