fidlcat [ <options> ] [ command [args] ] fidlcat will run the specified command until it exits. It will intercept and record all fidl calls invoked by the process. The command may be of the form "run <component URL>", in which case the given component will be launched. fidlcat will return the code 1 if its parameters are invalid. fidlcat expects a debug agent to be running on the target device. It will return the code 2 if it cannot connect to the debug agent.
Options:
--build-id-dir=<path> Adds the given directory to the symbol search path. Multiple --build-id-dir switches can be passed to add multiple directories. The directory must have the same structure as a .build-id directory, that is, each symbol file lives at xx/yyyyyyyy.debug where xx is the first two characters of the build ID and yyyyyyyy is the rest. However, the name of the directory doesn't need to be .build-id. --colors=[never|auto|always] For pretty print, use colors: - never - auto: only if running in a terminal (default value) - always --columns=<size> For pretty print, width of the display. By default, on a terminal, use the terminal width. --compare=<path> Compare output with the one stored in the given file --connect The host and port of the debug agent running on the target Fuchsia instance, of the form [<ipv6_addr>]:port. --dump-messages Always display the message binary dump even if we can decode the message. By default the dump is only displayed if we can't decode the message. --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. --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_.*" --extra-name=<regexp> 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). You must specify at least one filter with --remote-name if you use this option (without --remote-name, nothing would be displayed). --fidl-ir-path=<path>|@argfile Adds the given path as a repository for FIDL IR, in the form of .fidl.json files. Passing a file adds the given file. Passing a directory adds all of the .fidl.json files in that directory and any directory transitively reachable from there. An argfile contains a newline-separated list of .fidl.json files relative to the directory containing the argfile; passing an argfile (starting with the '@' character) adds all files listed in that argfile. This switch can be passed multiple times to add multiple locations. --format=<output> This option must be used at most once. The output format can be: --format=pretty The session is pretty printed (with colors). This is the default output is --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=none 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. --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. --help -h Prints all command-line switches. --ids-txt=<path> Adds the given file to the symbol search path. Multiple --ids-txt switches can be passed to add multiple files. The file, typically named "ids.txt", serves as a mapping from build ID to symbol file path and should contain multiple lines in the format of "<build ID> <file path>". --log-file=<pathspec> The name of a file to which the log should be written. --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. --quiet=<number or log level> The log verbosity. Legal values are "info", "warning", "error", "fatal", or a number, starting from 0. Extra verbosity comes with lower levels. --quit-agent-on-exit Will send a quit message to a connected debug agent in order for it to shutdown. This is so that fidlcat doesn't leak unwanted debug agents on "on-the-fly" debugging sessions. --remote-name=<regexp> -f <regexp> Adds a filter to the default job that will cause fidlcat to attach to existing or future processes whose names match this regexp. For example: --remote-name echo_client.*.cmx --remote-name echo_client Multiple filters can be specified to match more than one process. --remote-pid The koid of the remote process. Can be passed multiple times. --stack=<value> The amount of stack frame to display: - 0: no stack (default value) - 1: call site (1 to 4 levels) - 2: full stack frame (adds some overhead) --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. --symbol-cache=<path> Directory where we can keep a symbol cache. If a symbol server has been specified, downloaded symbols will be stored in this directory. The directory structure will be the same as a .build-id directory, and symbols will be read from this location as though you had specified "--build-id-dir=<path>". --symbol-index=<path> Populates --ids-txt and --build-id-dir using the given symbol-index file, which defaults to ~/.fuchsia/debug/symbol-index. The file should be created and maintained by the "symbol-index" host tool. --symbol-path=<path> -s <path> Adds the given directory or file to the symbol search path. Multiple -s switches can be passed to add multiple locations. When a directory path is passed, the directory will be enumerated non-recursively to index all ELF files. When a file is passed, it will be loaded as an ELF file (if possible). --symbol-server=<url> Adds the given URL to symbol servers. Symbol servers host the debug symbols for prebuilt binaries and dynamic libraries. --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=".*" --thread Only display the events for the specified thread. This option can be specified multiple times to display several threads. By default all the events are displayed. --to=<path> Save the session using protobuf in the specified file. All events are saved including the messages which have been filtered out by --messages or --exclude-messages. --trigger 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. --verbose=<number or log level> The log verbosity. Legal values are "info", "warning", "error", "fatal", or a number, starting from 0. Extra verbosity comes with higher levels --version Prints the version. --with-process-info Display the process name, process id and thread id on each line. 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>. --with=group-by-thread Like For each thread, display a short version of all the events. --with=group-by-thread=<path> Like --with=group-by-thread but the result is stored into the file specified by <path>.
