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 [(--port|-p) <PORT>] [--with-symbol-server] [--debug-mode]
                  [--symbol-path=<path>] [--fidl-ir-path=<path>] [--gdb]
                  [--from=<source>] [--to=<path>] [--format=<output>]
                  [--with-process-info] [--stack=<value>]
                  [--syscalls=<regexp>] [--exclude-syscalls=<regexp>]
                  [--messages=<regexp>] [--exclude-messages=<regexp>] [--trigger=<regexp>]
                  [--dump-messages]
                  [--verbose=<value> | --quiet=<value>] [--log-file <path>]
                  [--remote-pid=<pid>] [--remote-name=<name>] [--extra-name=<name>]
                  [run <component specification>]

System options:
   --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.
   --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.

Input options:
   --from=<source>    This option must be used at most once.
                      Source can be:
                      --from=device This is the default input. The input comes from the live
                                    monitoring of one or several processes.
                                    At least one of '--remote-pid', '--remote-name', 'run' must
                                    be specified.
                      --from=<path> The input comes from a previously recorded session (protobuf
                                    format). Path gives the name of the file to read. If path is
                                    '-' then the standard input is used.

Session save option:
   --to=<path> The session is saved to the specified file (binary protobuf format).
               When a session is saved, you can replay it using "--from=<path>".
               The raw data is saved. That means that the data saved is independent from what is
               displayed.

Format (output) options:
   --format=<output> You can use one of this output formats:
                     --format=pretty    The session is pretty printed (with colors).
                                        This is the default output if --with is not used.
                     --format=json      The session is printed using a json format.
                     --format=textproto The session is printed using a text protobuf format.
                     --format=          Nothing is displayed on the standard output (this option
                                        only makes sense when used with --to=<path> or with
                                        --with).
                                        When there is no output, fidlcat is much faster (this is
                                        better when you want to monitor real time components).
                                        This is the default output is --with is used.

Extra generation:
   These options can be used several times.
   --with=summary        At the end of the session, a summary of the session is displayed on the
                         standard output.
   --with=summary=<path> Like --with=summary but the result is stored into the file specified by
                         <path>.
   --with=top            At the end of the session, generate a view that groups the output by
                         process, protocol, and method. The groups are sorted by number of
                         events, so groups with more associated events are listed earlier.
   --with=top=<path>     Like --with=top but the result is stored into the file specified by
                         <path>.

Display options:
   --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=<regexp>         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=<regexp> 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=<regexp>         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=<regexp> 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 satisfies --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.

Logging options:
   --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.

Monitoring options:
   --remote-pid=<pid>    The koid of the remote process to trace.
   --remote-name=<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=<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).
   run <component spec>  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 options --remote-pid, --remote-name, --extra-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