| <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> |