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