src/performance/trace/README.md

# trace - collects and converts trace data

trace enables tracing of an application. It exposes the following
command line interface (invoke trace with --help to get an overview):

```{shell}
trace [options] command [command-specific options]
  --help: Produce this help message

  list-categories - list all known categories
  record - starts tracing and records data
    --[command args]: Run program before starting trace.
        The program is terminated when tracing ends unless --detach is specified
    --append-args=[""]: Additional args for the app being traced, appended to
        those from the spec file, if any
    --buffer-size=[4]: Maximum size of trace buffer for each provider in
        megabytes
    --provider-buffer-size=[provider-name:buffer-size]:
        Specify the buffer size that "provider-name" will use.
        May be specified multiple times, once per provider.
    --buffering-mode=[oneshot]: Specify buffering mode as one of oneshot,
        circular, or streaming
    --categories=[""]: Categories that should be enabled for tracing
    --decouple=[false]: Don't stop tracing when the traced program exits
    --detach=[false]: Don't stop the traced program when tracing finished
    --spawn=[false]: Use fdio_spawn to run a legacy app.
        Detach will have no effect when using this option.
    --environment-name=[none]: Create a nested environment with the given
        name and run the app being traced under it.
    --return-child-result=[true]: Pass on the child's return code.
    --duration=[10]: Trace will be active for this many seconds after the
        session has been started. The provided value must be integral.
    --output-file=[/tmp/trace.json]: Trace data is stored in this file
        The output file may be "tcp:IP-ADDRESS:PORT" in which case a stream
        socket is connected to that address and trace data is streamed directly
        to it instead of saving the output locally.
    --compress=[false]: Compress the output stream. Compressing a network
        output stream is not supported, if both --output-file=tcp:... and
        --compress are provided, --compress is ignored.
    --spec-file=[none]: Tracing specification file
    --trigger=<alert>:<action>: Specifies an action to take when an alert with
        the specified name is received. Multiple alert/action rules may be
        specified using multiple --trigger arguments. The only action currently
        supported is "stop". This action causes the session to be stopped and
        results to be captured.
```

Options provided on the command line override options found in the
`--spec-file` spec file.