Next: Tracepoint Restrictions, Previous: Listing Static Tracepoint Markers, Up: Set Tracepoints

#### 13.1.9 Starting and Stopping Trace Experiments

`tstart`
  This command takes no arguments. It starts the trace experiment, and begins collecting data. This has the side effect of discarding all the data collected in the trace buffer during the previous trace experiment.

`tstop`
  This command takes no arguments. It ends the trace experiment, and stops collecting data.

  Note: a trace experiment and data collection may stop automatically if any tracepoint's passcount is reached (see Tracepoint Passcounts), or if the trace buffer becomes full.

`tstatus`
  This command displays the status of the current trace data collection.

Here is an example of the commands we described so far:

         (gdb) trace gdb_c_test
         (gdb) actions
         Enter actions for tracepoint #1, one per line.
         > collect $regs,$locals,$args
         > while-stepping 11
           > collect $regs
           > end
         > end
         (gdb) tstart
         	[time passes ...]
         (gdb) tstop

You can choose to continue running the trace experiment even if gdb disconnects from the target, voluntarily or involuntarily. For commands such as `detach`, the debugger will ask what you want to do with the trace. But for unexpected terminations (gdb crash, network outage), it would be unfortunate to lose hard-won trace data, so the variable `disconnected-tracing` lets you decide whether the trace should continue running without gdb.

`set disconnected-tracing on`
`set disconnected-tracing off`
  Choose whether a tracing run should continue to run if gdb has disconnected from the target. Note that `detach` or `quit` will ask you directly what to do about a running trace no matter what this variable's setting, so the variable is mainly useful for handling unexpected situations, such as loss of the network.
`show disconnected-tracing`
  Show the current choice for disconnected tracing.

When you reconnect to the target, the trace experiment may or may not still be running; it might have filled the trace buffer in the meantime, or stopped for one of the other reasons. If it is running, it will continue after reconnection.

Upon reconnection, the target will upload information about the tracepoints in effect. gdb will then compare that information to the set of tracepoints currently defined, and attempt to match them up, allowing for the possibility that the numbers may have changed due to creation and deletion in the meantime. If one of the target's tracepoints does not match any in gdb, the debugger will create a new tracepoint, so that you have a number with which to specify that tracepoint. This matching-up process is necessarily heuristic, and it may result in useless tracepoints being created; you may simply delete them if they are of no use.

If your target agent supports a circular trace buffer, then you can run a trace experiment indefinitely without filling the trace buffer; when space runs out, the agent deletes already-collected trace frames, oldest first, until there is enough room to continue collecting. This is especially useful if your tracepoints are being hit too often, and your trace gets terminated prematurely because the buffer is full. To ask for a circular trace buffer, simply set ‘`circular_trace_buffer`’ to on. You can set this at any time, including during tracing; if the agent can do it, it will change buffer handling on the fly, otherwise it will not take effect until the next run.

`set circular-trace-buffer on`
`set circular-trace-buffer off`
  Choose whether a tracing run should use a linear or circular buffer for trace data. A linear buffer will not lose any trace data, but may fill up prematurely, while a circular buffer will discard old trace data, but it will have always room for the latest tracepoint hits.
`show circular-trace-buffer`
  Show the current choice for the trace buffer. Note that this may not match the agent's current buffer handling, nor is it guaranteed to match the setting that might have been in effect during a past run, for instance if you are looking at frames from a trace file.