f8/sdk/fidl/fuchsia.tracing.provider/README.md - reference-docs - Git at Google

 <link rel="stylesheet" href="../style.css" />

 [TOC]
 # fuchsia.tracing.provider

 <div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>

 ## **PROTOCOLS**

 ## Provider {#Provider}
 *Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=23)*
 <p>The provider interface which applications must implement and register
 with the <code>TraceRegistry</code> to participate in tracing.</p>
 <p>See //zircon/system/ulib/trace-provider/ for a C++ implementation of
 this interface which can easily be configured by an application.</p>

 ### Initialize {#Provider.Initialize}

 <p>Initialize tracing and prepare for writing trace records for events in
 the specified <code>categories</code> into <code>buffer</code> using <code>fifo</code> for signaling.
 Tracing hasn't started yet, a <code>Start()</code> call is still required.</p>
 <p>At most one trace can be active at a time. Subsequent <code>Initialize()</code>
 requests received prior to a <code>Terminate()</code> call must be ignored.</p>

 #### Request {#Provider.Initialize_Request}

 <table>
     <tr><th>Name</th><th>Type</th></tr>
         <tr>
             <td><code>config</code></td>
             <td>
                 <code><a class='link' href='#ProviderConfig'>ProviderConfig</a></code>
             </td>
         </tr>
 </table>


 ### Start {#Provider.Start}

 <p>Begin tracing.</p>
 <p>If tracing has already started the provider must ignore the request.</p>
 <p>There is no result. The provider must send a <code>TRACE_PROVIDER_STARTED</code>
 packet on <code>fifo</code> to indicate success/failure of starting.</p>

 #### Request {#Provider.Start_Request}

 <table>
     <tr><th>Name</th><th>Type</th></tr>
         <tr>
             <td><code>options</code></td>
             <td>
                 <code><a class='link' href='#StartOptions'>StartOptions</a></code>
             </td>
         </tr>
 </table>


 ### Stop {#Provider.Stop}

 <p>Stop tracing.</p>
 <p>If tracing has already stopped the provider must ignore the request.</p>
 <p>Once the provider has finished writing any final events to the trace
 buffer, it must send a <code>TRACE_PROVIDER_STOPPED</code> packet on <code>fifo</code>.
 Note that multiple <code>Start,Stop</code> requests can be received between
 <code>Initialize,Terminate</code>.</p>

 #### Request {#Provider.Stop_Request}

 &lt;EMPTY&gt;


 ### Terminate {#Provider.Terminate}

 <p>Terminate tracing.</p>
 <p>Tracing is stopped first if not already stopped.
 After tracing has fully terminated the provider must close both
 <code>buffer</code> and <code>fifo</code> to indicate to the trace manager that tracing is
 finished.</p>

 #### Request {#Provider.Terminate_Request}

 &lt;EMPTY&gt;


 ## Registry {#Registry}
 *Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=70)*
 <p>The service which trace providers use to register themselves with
 the tracing system.
 Note that one property of this interface is that once registration is made
 the provider can drop this connection.</p>

 ### RegisterProvider {#Registry.RegisterProvider}

 <p>Registers the trace provider.
 Note: Registration is asynchronous, it's only at some point after this
 returns that the provider is actually registered.
 To unregister, simply close the Provider pipe.
 <code>pid</code> is the process id of the provider, <code>name</code> is the name of the
 provider. Both of these are used in logging and diagnostic messages.</p>

 #### Request {#Registry.RegisterProvider_Request}

 <table>
     <tr><th>Name</th><th>Type</th></tr>
         <tr>
             <td><code>provider</code></td>
             <td>
                 <code><a class='link' href='#Provider'>Provider</a></code>
             </td>
         </tr>
         <tr>
             <td><code>pid</code></td>
             <td>
                 <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#koid'>koid</a></code>
             </td>
         </tr>
         <tr>
             <td><code>name</code></td>
             <td>
                 <code>string[100]</code>
             </td>
         </tr>
 </table>


 ### RegisterProviderSynchronously {#Registry.RegisterProviderSynchronously}

 <p>Registers the trace provider synchronously. The call doesn't return
 until the provider is registered.
 On return <code>s</code> is <code>ZX_OK</code> if registration was successful.
 <code>started</code> is true if tracing has already started, which is a hint to
 the provider to wait for the Start() message before continuing if it
 wishes to not drop trace records before Start() is received.
 To unregister, simply close the Provider pipe.
 <code>pid</code> is the process id of the provider, <code>name</code> is the name of the
 provider. Both of these are used in logging and diagnostic messages.</p>

 #### Request {#Registry.RegisterProviderSynchronously_Request}

 <table>
     <tr><th>Name</th><th>Type</th></tr>
         <tr>
             <td><code>provider</code></td>
             <td>
                 <code><a class='link' href='#Provider'>Provider</a></code>
             </td>
         </tr>
         <tr>
             <td><code>pid</code></td>
             <td>
                 <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#koid'>koid</a></code>
             </td>
         </tr>
         <tr>
             <td><code>name</code></td>
             <td>
                 <code>string[100]</code>
             </td>
         </tr>
 </table>


 #### Response {#Registry.RegisterProviderSynchronously_Response}

 <table>
     <tr><th>Name</th><th>Type</th></tr>
         <tr>
             <td><code>s</code></td>
             <td>
                 <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
             </td>
         </tr>
         <tr>
             <td><code>started</code></td>
             <td>
                 <code>bool</code>
             </td>
         </tr>
 </table>


 ## **STRUCTS**

 ### ProviderConfig [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ProviderConfig data-text="ProviderConfig"}
 *Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=129)*
 <p>Trace provider configuration.</p>

 <table>
     <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
         <tr id="ProviderConfig.buffering_mode">
             <td><code>buffering_mode</code></td>
             <td>
                 <code><a class='link' href='#BufferingMode'>BufferingMode</a></code>
             </td>
             <td><p><code>buffering_mode</code> specifies what happens when the buffer fills.</p>
 </td>
             <td>No default</td>
         </tr>
         <tr id="ProviderConfig.buffer">
             <td><code>buffer</code></td>
             <td>
                 <code>handle&lt;vmo&gt;</code>
             </td>
             <td><p>The buffer to write trace records into.</p>
 </td>
             <td>No default</td>
         </tr>
         <tr id="ProviderConfig.fifo">
             <td><code>fifo</code></td>
             <td>
                 <code>handle&lt;fifo&gt;</code>
             </td>
             <td><p>When the trace provider observes <code>ZX_FIFO_PEER_CLOSED</code> on <code>fifo</code>, it
 must assume the trace manager has terminated abnormally (since <code>Stop</code>
 was not received as usual) and stop tracing automatically, discarding
 any in-flight trace data.</p>
 </td>
             <td>No default</td>
         </tr>
         <tr id="ProviderConfig.categories">
             <td><code>categories</code></td>
             <td>
                 <code>vector&lt;string&gt;[100]</code>
             </td>
             <td><p>What trace categories to collect data for.</p>
 </td>
             <td>No default</td>
         </tr>
 </table>

 ### StartOptions  {#StartOptions data-text="StartOptions"}
 *Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=180)*
 <p>Additional options to control tracing at start.</p>

 <table>
     <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
         <tr id="StartOptions.buffer_disposition">
             <td><code>buffer_disposition</code></td>
             <td>
                 <code><a class='link' href='#BufferDisposition'>BufferDisposition</a></code>
             </td>
             <td><p>Whether and how to clear the buffer when starting data collection.
 This allows, for example, multiple Start/Stop trace runs to be
 collected in the same buffer.</p>
 </td>
             <td>No default</td>
         </tr>
         <tr id="StartOptions.additional_categories">
             <td><code>additional_categories</code></td>
             <td>
                 <code>vector&lt;string&gt;[100]</code>
             </td>
             <td><p>The trace categories to add to the initial set provided in
 <code>ProviderConfig</code>.</p>
 </td>
             <td>No default</td>
         </tr>
 </table>


 ## **ENUMS**

 ### BufferDisposition [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#BufferDisposition data-text="BufferDisposition"}
 Type: <code>uint8</code>

 *Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=154)*
 <p>Choices for clearing/retaining trace buffer contents at Start.
 A brief summary of buffer contents:
 The trace buffer is divided into two main pieces: durable and non-durable.
 The durable portion contains things like the string and thread data for
 their respective references (trace_encoded_string_ref_t and
 trace_encoded_thread_ref_t). The non-durable portion contains the rest of
 the trace data like events); this is the portion that, for example, is
 discarded in circular buffering mode when the (non-durable) buffer fills.</p>

 <table>
     <tr><th>Name</th><th>Value</th><th>Description</th></tr>
         <tr id="BufferDisposition.CLEAR_ENTIRE">
 <td><h3 id="BufferDisposition.CLEAR_ENTIRE" class="add-link hide-from-toc">CLEAR_ENTIRE</h3></td>
             <td><code>1</code></td>
             <td><p>Clear the entire buffer, including durable buffer contents.
 N.B. If this is done mid-session, then string and thread references
 from prior to this point will become invalid - the underlying data
 will be gone. To prevent this save buffer contents before clearing.</p>
 <p>This is typically used when buffer contents were saved after the
 preceding Stop.</p>
 </td>
         </tr>
         <tr id="BufferDisposition.CLEAR_NONDURABLE">
 <td><h3 id="BufferDisposition.CLEAR_NONDURABLE" class="add-link hide-from-toc">CLEAR_NONDURABLE</h3></td>
             <td><code>2</code></td>
             <td><p>Clear the non-durable portion of the buffer, retaining the durable
 portion.</p>
 <p>This is typically used when buffer contents were not saved after the
 preceding Stop and the current contents are to be discarded.</p>
 </td>
         </tr>
         <tr id="BufferDisposition.RETAIN">
 <td><h3 id="BufferDisposition.RETAIN" class="add-link hide-from-toc">RETAIN</h3></td>
             <td><code>3</code></td>
             <td><p>Retain buffer contents. New trace data is added where the previous
 trace run left off.</p>
 <p>This is typically used when buffer contents were not saved after the
 preceding Stop and the current contents are to be retained.</p>
 </td>
         </tr>
 </table>

 ### BufferingMode [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#BufferingMode data-text="BufferingMode"}
 Type: <code>uint8</code>

 *Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=103)*
 <p>The trace buffering mode.</p>

 <table>
     <tr><th>Name</th><th>Value</th><th>Description</th></tr>
         <tr id="BufferingMode.ONESHOT">
 <td><h3 id="BufferingMode.ONESHOT" class="add-link hide-from-toc">ONESHOT</h3></td>
             <td><code>1</code></td>
             <td><p>In oneshot mode there is only one buffer that is not reused. When the
 buffer fills the provider just keeps dropping records, keeping a count,
 and then when tracing stops the header is updated to record final
 state.</p>
 </td>
         </tr>
         <tr id="BufferingMode.CIRCULAR">
 <td><h3 id="BufferingMode.CIRCULAR" class="add-link hide-from-toc">CIRCULAR</h3></td>
             <td><code>2</code></td>
             <td><p>In circular mode, the buffer is continually written to until tracing
 stops. When the buffer fills older records are discarded as needed.</p>
 </td>
         </tr>
         <tr id="BufferingMode.STREAMING">
 <td><h3 id="BufferingMode.STREAMING" class="add-link hide-from-toc">STREAMING</h3></td>
             <td><code>3</code></td>
             <td><p>In streaming mode, the buffer is effectively split into two pieces.
 When one half of the buffer fills the provider notifies the trace
 manager via the provided fifo, and then starts filling the other half
 of the buffer. When the buffer is saved, the manager responds via the
 provided fifo. If trace manager hasn't saved the buffer in time, and
 the other buffer fills, then the provider is required to drop records
 until space becomes available.</p>
 </td>
         </tr>
 </table>


 ## **CONSTANTS**

 <table>
     <tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
         <tr id="MAX_CATEGORY_NAME_LENGTH">
             <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=16">MAX_CATEGORY_NAME_LENGTH</a></td>
                 <td>
                     <code>100</code>
                 </td>
                 <td><code>uint32</code></td>
             <td><p>The maximum length of a category name.</p>
 </td>
         </tr>
         <tr id="MAX_NUM_CATEGORIES">
             <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=13">MAX_NUM_CATEGORIES</a></td>
                 <td>
                     <code>100</code>
                 </td>
                 <td><code>uint32</code></td>
             <td><p>The maximum number of categories supported.</p>
 </td>
         </tr>
         <tr id="MAX_PROVIDER_NAME_LENGTH">
             <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=10">MAX_PROVIDER_NAME_LENGTH</a></td>
                 <td>
                     <code>100</code>
                 </td>
                 <td><code>uint32</code></td>
             <td><p>The maximum length of a provider's name.</p>
 </td>
         </tr>
 </table>
	<link rel="stylesheet" href="../style.css" />

	[TOC]
	# fuchsia.tracing.provider

	<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>

	## PROTOCOLS

	## Provider {#Provider}
	Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=23)
	<p>The provider interface which applications must implement and register
	with the <code>TraceRegistry</code> to participate in tracing.</p>
	<p>See //zircon/system/ulib/trace-provider/ for a C++ implementation of
	this interface which can easily be configured by an application.</p>

	### Initialize {#Provider.Initialize}

	<p>Initialize tracing and prepare for writing trace records for events in
	the specified <code>categories</code> into <code>buffer</code> using <code>fifo</code> for signaling.
	Tracing hasn't started yet, a <code>Start()</code> call is still required.</p>
	<p>At most one trace can be active at a time. Subsequent <code>Initialize()</code>
	requests received prior to a <code>Terminate()</code> call must be ignored.</p>

	#### Request {#Provider.Initialize_Request}

	<table>
	<tr><th>Name</th><th>Type</th></tr>
	<tr>
	<td><code>config</code></td>
	<td>
	<code><a class='link' href='#ProviderConfig'>ProviderConfig</a></code>
	</td>
	</tr>
	</table>


	### Start {#Provider.Start}

	<p>Begin tracing.</p>
	<p>If tracing has already started the provider must ignore the request.</p>
	<p>There is no result. The provider must send a <code>TRACE_PROVIDER_STARTED</code>
	packet on <code>fifo</code> to indicate success/failure of starting.</p>

	#### Request {#Provider.Start_Request}

	<table>
	<tr><th>Name</th><th>Type</th></tr>
	<tr>
	<td><code>options</code></td>
	<td>
	<code><a class='link' href='#StartOptions'>StartOptions</a></code>
	</td>
	</tr>
	</table>


	### Stop {#Provider.Stop}

	<p>Stop tracing.</p>
	<p>If tracing has already stopped the provider must ignore the request.</p>
	<p>Once the provider has finished writing any final events to the trace
	buffer, it must send a <code>TRACE_PROVIDER_STOPPED</code> packet on <code>fifo</code>.
	Note that multiple <code>Start,Stop</code> requests can be received between
	<code>Initialize,Terminate</code>.</p>

	#### Request {#Provider.Stop_Request}

	<EMPTY>


	### Terminate {#Provider.Terminate}

	<p>Terminate tracing.</p>
	<p>Tracing is stopped first if not already stopped.
	After tracing has fully terminated the provider must close both
	<code>buffer</code> and <code>fifo</code> to indicate to the trace manager that tracing is
	finished.</p>

	#### Request {#Provider.Terminate_Request}

	<EMPTY>


	## Registry {#Registry}
	Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=70)
	<p>The service which trace providers use to register themselves with
	the tracing system.
	Note that one property of this interface is that once registration is made
	the provider can drop this connection.</p>

	### RegisterProvider {#Registry.RegisterProvider}

	<p>Registers the trace provider.
	Note: Registration is asynchronous, it's only at some point after this
	returns that the provider is actually registered.
	To unregister, simply close the Provider pipe.
	<code>pid</code> is the process id of the provider, <code>name</code> is the name of the
	provider. Both of these are used in logging and diagnostic messages.</p>

	#### Request {#Registry.RegisterProvider_Request}

	<table>
	<tr><th>Name</th><th>Type</th></tr>
	<tr>
	<td><code>provider</code></td>
	<td>
	<code><a class='link' href='#Provider'>Provider</a></code>
	</td>
	</tr>
	<tr>
	<td><code>pid</code></td>
	<td>
	<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#koid'>koid</a></code>
	</td>
	</tr>
	<tr>
	<td><code>name</code></td>
	<td>
	<code>string[100]</code>
	</td>
	</tr>
	</table>


	### RegisterProviderSynchronously {#Registry.RegisterProviderSynchronously}

	<p>Registers the trace provider synchronously. The call doesn't return
	until the provider is registered.
	On return <code>s</code> is <code>ZX_OK</code> if registration was successful.
	<code>started</code> is true if tracing has already started, which is a hint to
	the provider to wait for the Start() message before continuing if it
	wishes to not drop trace records before Start() is received.
	To unregister, simply close the Provider pipe.
	<code>pid</code> is the process id of the provider, <code>name</code> is the name of the
	provider. Both of these are used in logging and diagnostic messages.</p>

	#### Request {#Registry.RegisterProviderSynchronously_Request}

	<table>
	<tr><th>Name</th><th>Type</th></tr>
	<tr>
	<td><code>provider</code></td>
	<td>
	<code><a class='link' href='#Provider'>Provider</a></code>
	</td>
	</tr>
	<tr>
	<td><code>pid</code></td>
	<td>
	<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#koid'>koid</a></code>
	</td>
	</tr>
	<tr>
	<td><code>name</code></td>
	<td>
	<code>string[100]</code>
	</td>
	</tr>
	</table>


	#### Response {#Registry.RegisterProviderSynchronously_Response}

	<table>
	<tr><th>Name</th><th>Type</th></tr>
	<tr>
	<td><code>s</code></td>
	<td>
	<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
	</td>
	</tr>
	<tr>
	<td><code>started</code></td>
	<td>
	<code>bool</code>
	</td>
	</tr>
	</table>


	## STRUCTS

	### ProviderConfig [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ProviderConfig data-text="ProviderConfig"}
	Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=129)
	<p>Trace provider configuration.</p>

	<table>
	<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
	<tr id="ProviderConfig.buffering_mode">
	<td><code>buffering_mode</code></td>
	<td>
	<code><a class='link' href='#BufferingMode'>BufferingMode</a></code>
	</td>
	<td><p><code>buffering_mode</code> specifies what happens when the buffer fills.</p>
	</td>
	<td>No default</td>
	</tr>
	<tr id="ProviderConfig.buffer">
	<td><code>buffer</code></td>
	<td>
	<code>handle<vmo></code>
	</td>
	<td><p>The buffer to write trace records into.</p>
	</td>
	<td>No default</td>
	</tr>
	<tr id="ProviderConfig.fifo">
	<td><code>fifo</code></td>
	<td>
	<code>handle<fifo></code>
	</td>
	<td><p>When the trace provider observes <code>ZX_FIFO_PEER_CLOSED</code> on <code>fifo</code>, it
	must assume the trace manager has terminated abnormally (since <code>Stop</code>
	was not received as usual) and stop tracing automatically, discarding
	any in-flight trace data.</p>
	</td>
	<td>No default</td>
	</tr>
	<tr id="ProviderConfig.categories">
	<td><code>categories</code></td>
	<td>
	<code>vector<string>[100]</code>
	</td>
	<td><p>What trace categories to collect data for.</p>
	</td>
	<td>No default</td>
	</tr>
	</table>

	### StartOptions {#StartOptions data-text="StartOptions"}
	Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=180)
	<p>Additional options to control tracing at start.</p>

	<table>
	<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
	<tr id="StartOptions.buffer_disposition">
	<td><code>buffer_disposition</code></td>
	<td>
	<code><a class='link' href='#BufferDisposition'>BufferDisposition</a></code>
	</td>
	<td><p>Whether and how to clear the buffer when starting data collection.
	This allows, for example, multiple Start/Stop trace runs to be
	collected in the same buffer.</p>
	</td>
	<td>No default</td>
	</tr>
	<tr id="StartOptions.additional_categories">
	<td><code>additional_categories</code></td>
	<td>
	<code>vector<string>[100]</code>
	</td>
	<td><p>The trace categories to add to the initial set provided in
	<code>ProviderConfig</code>.</p>
	</td>
	<td>No default</td>
	</tr>
	</table>


	## ENUMS

	### BufferDisposition [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#BufferDisposition data-text="BufferDisposition"}
	Type: <code>uint8</code>

	Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=154)
	<p>Choices for clearing/retaining trace buffer contents at Start.
	A brief summary of buffer contents:
	The trace buffer is divided into two main pieces: durable and non-durable.
	The durable portion contains things like the string and thread data for
	their respective references (trace_encoded_string_ref_t and
	trace_encoded_thread_ref_t). The non-durable portion contains the rest of
	the trace data like events); this is the portion that, for example, is
	discarded in circular buffering mode when the (non-durable) buffer fills.</p>

	<table>
	<tr><th>Name</th><th>Value</th><th>Description</th></tr>
	<tr id="BufferDisposition.CLEAR_ENTIRE">
	<td><h3 id="BufferDisposition.CLEAR_ENTIRE" class="add-link hide-from-toc">CLEAR_ENTIRE</h3></td>
	<td><code>1</code></td>
	<td><p>Clear the entire buffer, including durable buffer contents.
	N.B. If this is done mid-session, then string and thread references
	from prior to this point will become invalid - the underlying data
	will be gone. To prevent this save buffer contents before clearing.</p>
	<p>This is typically used when buffer contents were saved after the
	preceding Stop.</p>
	</td>
	</tr>
	<tr id="BufferDisposition.CLEAR_NONDURABLE">
	<td><h3 id="BufferDisposition.CLEAR_NONDURABLE" class="add-link hide-from-toc">CLEAR_NONDURABLE</h3></td>
	<td><code>2</code></td>
	<td><p>Clear the non-durable portion of the buffer, retaining the durable
	portion.</p>
	<p>This is typically used when buffer contents were not saved after the
	preceding Stop and the current contents are to be discarded.</p>
	</td>
	</tr>
	<tr id="BufferDisposition.RETAIN">
	<td><h3 id="BufferDisposition.RETAIN" class="add-link hide-from-toc">RETAIN</h3></td>
	<td><code>3</code></td>
	<td><p>Retain buffer contents. New trace data is added where the previous
	trace run left off.</p>
	<p>This is typically used when buffer contents were not saved after the
	preceding Stop and the current contents are to be retained.</p>
	</td>
	</tr>
	</table>

	### BufferingMode [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#BufferingMode data-text="BufferingMode"}
	Type: <code>uint8</code>

	Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=103)
	<p>The trace buffering mode.</p>

	<table>
	<tr><th>Name</th><th>Value</th><th>Description</th></tr>
	<tr id="BufferingMode.ONESHOT">
	<td><h3 id="BufferingMode.ONESHOT" class="add-link hide-from-toc">ONESHOT</h3></td>
	<td><code>1</code></td>
	<td><p>In oneshot mode there is only one buffer that is not reused. When the
	buffer fills the provider just keeps dropping records, keeping a count,
	and then when tracing stops the header is updated to record final
	state.</p>
	</td>
	</tr>
	<tr id="BufferingMode.CIRCULAR">
	<td><h3 id="BufferingMode.CIRCULAR" class="add-link hide-from-toc">CIRCULAR</h3></td>
	<td><code>2</code></td>
	<td><p>In circular mode, the buffer is continually written to until tracing
	stops. When the buffer fills older records are discarded as needed.</p>
	</td>
	</tr>
	<tr id="BufferingMode.STREAMING">
	<td><h3 id="BufferingMode.STREAMING" class="add-link hide-from-toc">STREAMING</h3></td>
	<td><code>3</code></td>
	<td><p>In streaming mode, the buffer is effectively split into two pieces.
	When one half of the buffer fills the provider notifies the trace
	manager via the provided fifo, and then starts filling the other half
	of the buffer. When the buffer is saved, the manager responds via the
	provided fifo. If trace manager hasn't saved the buffer in time, and
	the other buffer fills, then the provider is required to drop records
	until space becomes available.</p>
	</td>
	</tr>
	</table>





	## CONSTANTS

	<table>
	<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
	<tr id="MAX_CATEGORY_NAME_LENGTH">
	<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=16">MAX_CATEGORY_NAME_LENGTH</a></td>
	<td>
	<code>100</code>
	</td>
	<td><code>uint32</code></td>
	<td><p>The maximum length of a category name.</p>
	</td>
	</tr>
	<tr id="MAX_NUM_CATEGORIES">
	<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=13">MAX_NUM_CATEGORIES</a></td>
	<td>
	<code>100</code>
	</td>
	<td><code>uint32</code></td>
	<td><p>The maximum number of categories supported.</p>
	</td>
	</tr>
	<tr id="MAX_PROVIDER_NAME_LENGTH">
	<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=10">MAX_PROVIDER_NAME_LENGTH</a></td>
	<td>
	<code>100</code>
	</td>
	<td><code>uint32</code></td>
	<td><p>The maximum length of a provider's name.</p>
	</td>
	</tr>
	</table>