show trace

Display the state and monitored events for a trace.

Description Jump to heading #

After configuring and starting a trace with the trace command, you can use show trace to see the state of the trace and the events it’s watching.

With no parameter, show trace returns a list of trace sources and their current state (stopped, waiting, or running). When no trace is running, each trace source shows a state of stopped:

nix
echo "show trace" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "show trace" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

output
text
Supported trace sources and states (.=stopped, w=waiting, R=running) :
   [.] fcgi       -> none [drp 0]  [FastCGI multiplexer]
   [.] h1         -> none [drp 0]  [HTTP/1 multiplexer]
   [.] h2         -> none [drp 0]  [HTTP/2 multiplexer]
   [.] stream     -> none [drp 0]  [Applicative stream]
   [.] peers      -> none [drp 0]  [Peers protocol]

output
text
Supported trace sources and states (.=stopped, w=waiting, R=running) :
   [.] fcgi       -> none [drp 0]  [FastCGI multiplexer]
   [.] h1         -> none [drp 0]  [HTTP/1 multiplexer]
   [.] h2         -> none [drp 0]  [HTTP/2 multiplexer]
   [.] stream     -> none [drp 0]  [Applicative stream]
   [.] peers      -> none [drp 0]  [Peers protocol]

When a trace is running, it will show an R for its state:

nix
echo "show trace" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "show trace" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

output
text
Supported trace sources and states (.=stopped, w=waiting, R=running) :
   [.] fcgi       -> none [drp 0]  [FastCGI multiplexer]
   [R] h1         -> stdout [drp 0]  [HTTP/1 multiplexer]
   [.] h2         -> none [drp 0]  [HTTP/2 multiplexer]
   [.] stream     -> none [drp 0]  [Applicative stream]
   [.] peers      -> none [drp 0]  [Peers protocol]

output
text
Supported trace sources and states (.=stopped, w=waiting, R=running) :
   [.] fcgi       -> none [drp 0]  [FastCGI multiplexer]
   [R] h1         -> stdout [drp 0]  [HTTP/1 multiplexer]
   [.] h2         -> none [drp 0]  [HTTP/2 multiplexer]
   [.] stream     -> none [drp 0]  [Applicative stream]
   [.] peers      -> none [drp 0]  [Peers protocol]

Pass the source name to the command to see which events are included in the running trace:

nix
echo "show trace h1" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "show trace h1" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

output
text
Trace status for h1:
   - sink: stdout [0 dropped]
   - event name   :     report    start    stop    pause
      h1c_new      :        +        -        -       -
      h1c_recv     :        +        -        -       -
      h1c_send     :        +        -        -       -
      h1c_blk      :        +        -        -       -
      h1c_wake     :        +        -        -       -
      h1c_end      :        +        -        -       -
      h1c_err      :        +        -        -       -
      rx_data      :        +        -        -       -
      rx_eoi       :        +        -        -       -
      rx_headers   :        +        -        -       -
      rx_body      :        +        -        -       -
      rx_trailerus :        +        -        -       -
      tx_data      :        +        -        -       -
      tx_eoi       :        +        -        -       -
      tx_headers   :        +        -        -       -
      tx_body      :        +        -        -       -
      tx_trailerus :        +        -        -       -
      h1s_new      :        +        -        -       -
      h1s_blk      :        +        -        -       -
      h1s_end      :        +        -        -       -
      h1s_err      :        +        -        -       -
      strm_new     :        +        -        -       -
      strm_recv    :        +        -        -       -
      strm_send    :        +        -        -       -
      strm_wake    :        +        -        -       -
      strm_shut    :        +        -        -       -
      strm_end     :        +        -        -       -
      strm_err     :        +        -        -       -

output
text
Trace status for h1:
   - sink: stdout [0 dropped]
   - event name   :     report    start    stop    pause
      h1c_new      :        +        -        -       -
      h1c_recv     :        +        -        -       -
      h1c_send     :        +        -        -       -
      h1c_blk      :        +        -        -       -
      h1c_wake     :        +        -        -       -
      h1c_end      :        +        -        -       -
      h1c_err      :        +        -        -       -
      rx_data      :        +        -        -       -
      rx_eoi       :        +        -        -       -
      rx_headers   :        +        -        -       -
      rx_body      :        +        -        -       -
      rx_trailerus :        +        -        -       -
      tx_data      :        +        -        -       -
      tx_eoi       :        +        -        -       -
      tx_headers   :        +        -        -       -
      tx_body      :        +        -        -       -
      tx_trailerus :        +        -        -       -
      h1s_new      :        +        -        -       -
      h1s_blk      :        +        -        -       -
      h1s_end      :        +        -        -       -
      h1s_err      :        +        -        -       -
      strm_new     :        +        -        -       -
      strm_recv    :        +        -        -       -
      strm_send    :        +        -        -       -
      strm_wake    :        +        -        -       -
      strm_shut    :        +        -        -       -
      strm_end     :        +        -        -       -
      strm_err     :        +        -        -       -

Examples Jump to heading #

In the example below, we check whether a trace has been configured. It shows that the h1 trace is running and that it is sending its output to stdout:

nix
echo "show trace" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "show trace" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

output
text
Supported trace sources and states (.=stopped, w=waiting, R=running) :
   [.] fcgi       -> none [drp 0]  [FastCGI multiplexer]
   [R] h1         -> stdout [drp 0]  [HTTP/1 multiplexer]
   [.] h2         -> none [drp 0]  [HTTP/2 multiplexer]
   [.] stream     -> none [drp 0]  [Applicative stream]
   [.] peers      -> none [drp 0]  [Peers protocol]

output
text
Supported trace sources and states (.=stopped, w=waiting, R=running) :
   [.] fcgi       -> none [drp 0]  [FastCGI multiplexer]
   [R] h1         -> stdout [drp 0]  [HTTP/1 multiplexer]
   [.] h2         -> none [drp 0]  [HTTP/2 multiplexer]
   [.] stream     -> none [drp 0]  [Applicative stream]
   [.] peers      -> none [drp 0]  [Peers protocol]

See also Jump to heading #

• show events
• trace