Example 4: Updating a Trace Session

While a trace session is running, you can update the following properties of a real-time or logged trace session:

• Convert a real-time trace session to a trace log session (by using -f).

• Create a new trace log for an existing trace log session (by using -f).

• Add real-time trace message delivery to an existing trace log session (by using -rt).

• Change the maximum number of buffers (by using -max), but not the minimum number of buffers.

• Change the flush time interval (by using -ft).

• Flush the trace buffers (by using -tracelog -flush).

You cannot use a tracelog -update command to change the flags and level of a trace provider. Instead, use the tracelog -enable command, as shown in Example 5: Enabling Trace Providers.

The -rt and -f parameters work differently in a tracelog -update command. The -rt parameter adds real-time message delivery to a trace log session. As a result, new trace messages are sent directly to the trace consumer and to the trace log. However, before you can add real-time message delivery to a trace log session, the buffers must be flushed using the tracelog -flush command. When the -f parameter is used to update a real-time trace session, it replaces real-time message delivery with delivery to the trace log. As a result, new trace messages are sent only to the trace log; they are no longer sent directly to the trace consumer.

The following command changes a real-time trace session named "MyTrace" to a trace log session. The command uses the -f parameter to specify the location of the log file, C:\tracing\MyTrace.etl. It also uses the -max parameter with a value of 35 to increase the maximum number of buffers to 35.

tracelog -update MyTrace -f c:\tracing\mytrace.etl -max 35

In response, Tracelog displays the properties of the trace session, including the properties that have just been changed.

As a result of this command, all new trace messages generated by the provider, and any trace messages stored in the buffer when the command was submitted, are written only to the log file. They are no longer sent directly to the trace consumer, as in a real-time trace session.

To add a trace log to a real-time trace session, so that trace messages are sent to the trace consumer and to the trace log, include both the -rt and -f parameters, as shown in the following command.

tracelog -update MyTrace -rt -f c:\tracing\mytrace.etl -max 35

You can also flush the trace buffers while a session is running. This is a forced flush that is not coordinated with the flush timer. The system will flush the buffers again when the flush timer expires and when the trace session stops.

To flush the buffers of an existing trace session, use the -flush parameter, as shown in the following example. The -flush parameter is not a subparameter of the tracelog -update command.

tracelog -flush MyTrace

In response, Tracelog displays the revised properties of the trace session.