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>] [--stay-alive]
[--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.
--stay-alive Don't quit fidlcat when all the monitored processes have ended. This allows
to keep monitoring upcoming process. At the end you have to use control-c
to quit fidlcat. This is useful when you monitor a process and restart this
process.
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